path: root/USAGE

Foomatic 4.0.1
==============

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.

Till Kamppeter <till.kamppeter@gmail.com>
Lars Uebernickel <larsuebernickel@gmx.de>

http://www.openprinting.org/

This usage documentation file is written by Till Kamppeter


Intro
-----

Foomatic is a database providing information about the usage of
printers with Unix-like operating systems (Linux, Solaris, ...).

The applications of these operating systems send PostScript or PDF to
the printer queues. Therefore one usually hands over the PostScript
directly to a PostScript printer (sometimes with some inserted
PostScript commands for options) or uses Ghostscript for generating
the data format the printer needs from PostScript or PDF input. 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 Unix-like 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, Solaris LP, 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/PDF file types for spoolers which
do not support these 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 and Ghostscript.

foomatic-filters needs the Ghostscript library for foomatic-rip and
the Perl interpreter for beh (Backend Error Handler) and the test
suite.

To build foomatic-rip you need a C compiler, its standard libraries,
and the Ghostscript library (libgs, /usr/lib/libgs.so*). For the
latter Ghostscript must be built in shared library mode ("make
so"). If your libgs is provided by your operating system distribution,
make sure that its C headers (package libgs.dev(el) or
ghostscript.dev(el)) are installed.

To run foomatic-rip you need to have the Ghostscript library installed.

To run beh (Backend Error Handler) or the test suite a Perl interpreter
(5.6.0 and newer) is needed.

To connect to remote printers with a non-CUPS printing system, you
need additional connectivity software (as "rlpr", "nc", "smbspool',
...). To print non-PostScript/PDF 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.openprinting.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 the OpenPrinting site, with
manufacturer-supplied PPDs for PostScript printers, and probably with
other PPD files.

For non-PostScript printers one also needs Ghostscript (5.50 or newer,
GPL Ghostscript 8.63 or newer highly recommended) and the appropriate
printer driver.

For drivers which have to be compiled into Ghostscript ("Execution
style: Ghostscript built-in" on the driver pages on the OpenPrinting
site) 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 (preferably GPL
Ghostscript 8.63 or newer).

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 the BZR repository, 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 programs have to be
installed and where the Perl interpreter and the Ghostscript library
are 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-rip), to get it into
subdirectories of /usr (/usr/bin/foomatic-rip), enter:

   ./configure --prefix=/usr --sysconfdir=/etc
   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, if you do not use CUPS, 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, most image formats) and together with
ImageMagick (for images) and Ghostscript 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 printer or multi-function device from HP, install HPLIP from

   http://hplipopensource.com/

before starting to set up printer queues with foomatic-filters. This
is needed for printing on certain USB devices and for scanning and
photo memory card access on all devices. It also adds maintenance
functionality for inkjets, reporting of ink or toner levels and
printer status, and also remote readout of the printers front-panel
LCD. CUPS is required as the printing system when HPLIP is used.

Note: The "hp" CUPS backend and "beh" (see below) cannot be used
together.



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.openprinting.org/cups-doc.html

LPD, LPRng, GNUlpr:

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

PPR:

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

PDQ:

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

CPS:

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

Direct, spooler-less printing:

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

Usage of PPD files (for all spoolers):

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



beh - Backend Error Handler
---------------------------

A wrapper for CUPS backends to make error handling configurable

Usually, if a CUPS backend exits with an error status other than zero
(for example if a printer is not turned on or not reachable on the
network), CUPS disables the print queue and one can only print again
if a system administrator re-enables the queue manually. Even restarting
CUPS (or rebooting) does not re-enable disabled queues.

For system administrators this can get annoying, for newbie users
who are not aware of this problem it looks like that CUPS is severely
broken. They remove and re-install print queues, getting on the nerves
of distro install support, people, or even switch back to a proprietary
operating system.

This script makes the handling of such backend errors configurable, so
that the problem can easily be worked around. The new possibilities are:

 - Let queues simply not being disabled. Simple approach, but job gets 
   lost.

 - Repeat a given number of times.

 - Repeat infinitely often, until the job gets finally through. This
   is the standard of LPRng, and it eliminates loss of the job.

 - The interval between two attemts to run the backend can also be
   configured.

 - Configuration is done independently for each print queue. So local
   printers and network printers can be treated differently.


Usage: 

Make sure "beh" is in the CUPS backend directory (usually
/usr/lib/cups/backend/) and world-readable and -executable. Restart
CUPS (usually "killall -HUP cupsd" or "/etc/init.d/cups restart"). If
all is correct "lpinfo -v" should have "beh" in its output.

Then activate "beh" for your print queue(s) with command(s) like this:

lpadmin -p <queue name> -E -v beh:/<dd>/<att>/<delay>/<originaluri>

with 
  <queue name>:     The name of your print queue
  <dd>:             Don't Disable, if "1", beh always exits with zero
                    status, so the queue gets never disabled when the
                    original backend exits with an error. "0" carries
                    the error status of the last call of the backend
                    (after <att> retries) on to CUPS, so the queue
                    usually gets disabled.
  <att>:            Attempts, number of attempts to recall the backend
                    in case of an error. "0" means infinite retries. In
                    this case <dd> gets meaningless.
  <delay>:          Delay between two attempts to call the beckend, to
                    be given in seconds and as an integer number.
                    Meaningless if <att> is one.
  <originaluri>:    The original URI, which your queue had before. Can 
                    be determined with "lpstat -v".

All parameters, especially, <dd>, <att>, and <delay> have always to
be specified, even if one of them is meaningless due to the setting of
the others.

beh works with every backend except the "hp" backend of HPLIP.

Example URIs:

beh:/1/3/5/socket://printer:9100

  On the network printer with host name "printer" it is tried to access
  3 times with 5 second delays between the attempts. If the job still
  fails, the queue is not disabled (and the job discarded).

beh:/0/10/60/socket://printer:9100

  Retry 10 times in one minute intervals, disable the queue when still
  not succeeding.

beh:/1/0/60/usb://Brother/HL-5040%20series

  On a Brother HL-5040 on the USB try infinitely often until the printer
  comes back, in intervals of one minute. This way the job does not get
  lost when the printer is turned off and one can intendedly delay
  printing by simply switching off the printer. The ideal configuration
  for desktop printers and/or home users.