path: root/USAGE

Foomatic 3.0.2
==============

foomatic-filters
----------------

Filter scripts used by the printer spoolers to convert the incoming
PostScript data into the printer's native format using a
printer/driver specific, but spooler-independent PPD file.


Grant Taylor <gtaylor@picante.com>
Till Kamppeter <till.kamppeter@gmx.net>
http://www.linuxprinting.org/

This usage documentation file is written by Till Kamppeter


Intro
-----

Foomatic is a database providing information about the usage of
printers with free operating systems and free printer drivers, where
"free" is meant as free software in the sense of the Free Software
Foundation (http://www.gnu.org). Therefore the database only contains
information about printer drivers which are free software. The
technology of this database can also be used for non-free drivers, but
the database entries have to be published in separate packages
then. The database can also be run under non-free operating systems
(as commercial Unixes) as they often use GhostScript and free printer
drivers.

Since most free operating systems (GNU/Linux, *BSD, ...) are
compatible to Unix, their applications send PostScript to the printer
queues. Therefore one usually hands over the PostScript directly to a
PostScript printer (sometimes with some prepended PostScript commands
for options) or uses GhostScript for generating the data format the
printer needs. This is done by the printer spooler which also stores
the data in a spool directory when the printer is still occupied by
another job, transmits the data to a print server in the network, and
so on.

The printer drivers for non-PostScript printers are either compiled
into GhostScript, a plug-in for GhostScript (e. g. IJS drivers), or
they are an extra filter which converts a generic bitmap generated by
GhostScript into the printer's data format. For this the spooler has
to call complicated command lines of GhostScript and the extra filter
(if needed). The user of a free operating system normally does not see
these command lines because an installation program takes appropriate
filter scripts and/or description files from a database and assigns
them to the printer queue.

Widely used databases were the RHS-Printfilters and the APS
filters. Their disadvantages were that they only supported one spooler
(LPD/LPRng) and only a small part of the driver's options (mostly page
size and resolution). Foomatic supports all options of the drivers and
all known spoolers (LPD, LPRng, GNUlpr, CUPS, PPR, PDQ, CPS, direct
spooler-less printing). In addition, all known free software printer
drivers are supported. Foomatic also supports printing of various
non-PostScript file types for spoolers which do not support this by
themselves (LPD, LPRng, GNUlpr, spooler-less printing). To enable this
feature you need to have "a2ps", "enscript", or "mpage" installed.

Another problem is that the way how to install queues, to print files,
and to handle jobs is very different with different spoolers. LPD for
example requires editing of configuration files for adding a queue,
whereas CUPS and PPR have specialized command line utilities. Foomatic
puts a layer between the applications and the spoolers so that one has
a common, spooler-independent command line interface for all spoolers,
so that switching of spoolers or administration of a network with
different spoolers gets much easier, because for the same operations
there are the same commands, independent of the spooler.

This command line interface can also be used as a base for
spooler-independent graphical frontends.


Installation
------------

Foomatic runs on all systems where one can run the Perl
interpreter.

foomatic-filters needs nothing else than the Perl interpreter to build
and run.

To connect to remote printers, you need additional connectivity
software (as "rlpr", "nc", "smbspool', ...). To print non-PostScript
files with LPD, LPRng, GNUlpr, or without spooler, you will need a2ps,
enscript, mpage, or similar filters which convert non-PostScript files
to PostScript. a2ps, enscript, and mpage will be automatically used by
the scripts when they are installed.

Download sources:
rlpr: http://freshmeat.net/projects/rlpr/ or
      http://www.linuxprinting.org/download/printing/
netcat: http://freshmeat.net/projects/netcat/

This package does not require any other Foomatic package. it can be
used with PPD files downloaded from linuxprinting.org, with
manufacturer-supplied PPDs for PostScript printers, and probably with
other PPD files.

Note: PPD files for native CUPS drivers, as the ones shipping with
CUPS or Gimp-Print cannot be used with other spoolers than CUPS.

For non-PostScript printers one also needs GhostScript (5.50 or newer,
ESP GhostScript 7.05.4 or newer highly recommended) and the
appropriate printer driver.

For drivers which have to be compiled into GhostScript ("Execution
style: GhostScript" on the driver pages on linuxprinting.org) check
with "gs -h" whether the driver is in your GhostScript. If not you
need to compile the driver into your GhostScript or use a GhostScript
version which already contains it.

If the driver page says "Execution style: Uniprint", it is much
easier, check whether the appropriate ".upp" file is in one of the
directories listed under "Search path:" in the end of the "gs -h"
output. Copy the ".upp" file to one of these directories when it was
not there already.

The third type of driver is marked with "Execution style: Filter",
this means, that you have to install a filter executable in addition
to GhostScript. Check with "which <name of the filter>" whether the
filter is already there, otherwise download and install the
appropriate package.



foomatic-filters can be installed using these commands (if you have
downloaded this package from CVS, run "./make_configure" at first, for
that you will also need the "autoconf" and "aclocal" utilities,
"aclocal" is in the "automake" package in some distributions):

   ./configure
   make
   make install

"make install" must be run as "root", the other commands can be run as
a normal user.

The "configure" script will auto-detect where the scripts have to be
installed and where the Perl interpreter is located. If "configure"
fails because of something not being installed, do

   rm -rf config.cache autom*.cache

before you run "configure" again (after installing the missing parts).

By default, foomatic-filters is installed into subdirectories of /usr/local
(e. g. /usr/local/bin/foomatic-gswrapper), to get it into subdirectories
of /usr (/usr/bin/foomatic-gswrapper), enter:

   ./configure --prefix=/usr
   make
   make install

There are other things which can be adjusted by options on the
"configure" command line, enter "./configure --help" for more
info. You can also modify variables in the beginning of the "Makefile"
after running "configure", but note that every run of "configure"
re-creates the "Makefile".

You can also run Foomatic out of its source directory (for example
when you want to try it out, or when you don't have root
access). Therefore enter (can be done as a normal user):

   ./configure
   make inplace
   
and enter the commands with "./" in the beginning
(e. g. "./foomatic-rip ...", "man ./foomatic-rip.1"). This also works
on a machine where a system-wide Foomatic is already installed.

In addition, you should install a utility to make PostScript out of
non-PostScript files, so that you can print those non-PostScript files
and also a list of available options using the "docs" option. The
supported utilities are "a2ps"
(http://www-inf.enst.fr/~demaille/a2ps/), "enscript"
(http://people.ssh.fi/mtr/genscript/), and "mpage"
(http://www.mesa.nl/pub/mpage). Recommended is "a2ps" because it
detects many file types (text, PDF, most image formats) and together
with ImageMagick (for images) and GNU/ESP/AFPL GhostScript 6.51 or
newer (for PDF) it converts them to PostScript. The other tools
convert only text files. The tool you have installed is auto-detected
by foomatic-rip and used automatically if
necessary. PPR needs this tool only for printing the option
list, and CUPS does not need it at all. PPR and CUPS use internal filters for printing non-PostScript files.

If you have a multi-function device from HP, install HPOJ from

   http://hpoj.sourceforge.net/

before starting to set up printer queues with foomatic-filters. This
is needed for printing on USB devices and for scanning and photo
memory card access on all devices. If you use CUPS 1.1.12 or newer
together with the old HPOJ 0.8, you need also the latest "ptal"
backend script from

   http://www.hornclan.com/~mark/cups/

License information and installation instructions for this script you
find in the beginning of the script itself. See also the end of the
"Adding a queue" section in this file to see how to use this script.

The "ptal" backend script is already included in HPOJ 0.9.


Setting up printers
-------------------

If you have "foomatic-db-engine" installed, see the USAGE file there.

If not, see, depending on your spooler:

CUPS:

   http://www.linuxprinting.org/cups-doc.html

LPD, LPRng, GNUlpr:

   http://www.linuxprinting.org/lpd-doc.html

PPR:

   http://www.linuxprinting.org/ppr-doc.html

PDQ:

   http://www.linuxprinting.org/pdq-doc.html

CPS:

   http://www.tww.cx/cps.php

Direct, spooler-less printing:

   http://www.linuxprinting.org/direct-doc.html

Usage of PPD files (for all spoolers):

   http://www.linuxprinting.org/ppd-doc.html