Foomatic 1.1 beta release
Grant Taylor <gtaylor@picante.com>
http://www.linuxprinting.org/

With contributions from Till Kamppeter <till.kamppeter@gmx.net>

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 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. There 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, CUPS, PDQ). In addition all known free
software printer drivers are supported.

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 has a specialized command line utility. 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. It needs the Perl interpreter and the following Perl
libraries (all downloadable on http://www.cpan.org/):

Storable-1.0.12.tar.gz
DateManip-5.39.tar.gz
Parse-Yapp-1.04.tar.gz
XML-Grove-0.46alpha.tar.gz (already in Debian)
XML-Dumper-0.4.tar.gz
XML-Encoding-1.01.tar.gz
XML-Parser-2.29.tar.gz     (includes expat; easy to install)
XML-Parser.2.30.tar.gz     (doesn't include expat; harder to install) 
XML-Twig-2.02.tar.gz
libxml-enno-1.02.tar.gz
libxml-perl-0.07.tar.gz    (Debian has, but out of date)

All libraries not listed are part of both the Mandrake and Debian
Linux distributions.

For Foomatic making sense one also needs at least one of the printer
spoolers LPD, LPRng, CUPS, and PDQ and GhostScript (5.50 or newer) if
one has a non-PostScript printer.

After installing the Perl libraries Foomatic can be installed using
the commands

   make
   make install

To fit it to one's system the definitions in the beginning of the
Makefile can be edited or they can be overridden using alternative
definitions on the command line:

   make PREFIX=/usr
   make PREFIX=/usr install

A default spooler can be set by putting its name into an
/etc/foomatic/defaultspooler file or into ~/.defaultspooler


Adding a queue
--------------

To add a printer queue you use the queue administration tool
foomatic-configure. You call it this way:

   foomatic-configure [-q] [-f] [-s <spooler>] -n <queue> -c <connection> 
		      [-p <printer ID> -d <driver ID>] [-o <option>=<value>
	              -o <option>=<value> ...]

Options in [...] can be left out. The options mean:

   -q		Quiet operation: You are not asked for anything.
   -f		Force rebuild: The disk cache of the database will be
		deleted, so changes in the database are taken into account.
   -s <spooler>	The spooler to be used. If this option is left out, the
		spooler is auto-detected and the user is asked whether
		the auto-detection is correct (unless -q is given). Possible
		choices are: "lpd", "lprng", "cups", "pdq".
   -n <queue>	The queue name. This argument is required.
   -c <connection> The way how the printer is connected (also required):

		   file:<file name> : Local printer, <file name> can also
			              be a device special file as /dev/lp0,
				      /dev/usb/lp1, ...
		   lpd://<server>/<queue> : Remote LPD printer (on server
				      running LPD/LPRng or ethernet-
				      connected printer)
		   socket://<server>:<port>/ : TCP/Socket printer (ethernet-
				      connected printer)
		   smb://<user>:<password>@<workgroup>/<server>/<share>
		   smb://<user>@<workgroup>/<server>/<share>
		   smb://<workgroup>/<server>/<share>
		   smb://<server>/<share>
		   smb://<user>:<password>@<server>/<share> : Printer on 
				      Windows server. Leaving out user and
				      password sends the job to the "GUEST"
				      account, the workgroup is optional
				      (not in PDQ).
		   ncp://<server>/<queue>
		   ncp://<user>:<password>@<server>/<queue> : Printer on
				      Novell NetWare server (only LPD and 
				      LPRng).
		   postpipe:"<command line>" : Pipe the PostScript output
				      into the given command line (only LPD
				      and LPRng).

   -p <printer ID> : The database ID of the used printer model. To get it,
		type

		   foomatic-configure -O | less

		on the command line and search the output for your printer
		model. The entry for your model contains both the printer
		ID and the driver IDs for all suitable drivers. To search
		strings in the output of the command above press "/", type
		a search term, and press <Enter>.
   -d <driver ID> : The ID of the desired printer driver. If the "-p" and
		the "-d" options are left out, a raw (filterless) queue is
		set up (PDQ does not support raw queues).
   -o <option>=<value> : Set the default value for an option.

Example: We have the HP DeskJet 840C on the USB and want to use it
with the "cdj880" driver. To get a CUPS queue named "DeskJet" we have
to enter:

   foomatic-configure -O | less

and find in the output:

  <printer>
    <id>133664</id>
    <make>HP</make>
    <model>DeskJet 840C</model>
    <functionality>B</functionality>
    <unverified>B</unverified>
    <autodetect>
      <parallel>
        <manufacturer>Hewlett-Packard</manufacturer>
        <model>DeskJet 840C</model>
      </parallel>
    </autodetect>
    <drivers>
      <driver>DJ8xx</driver>
      <driver>cdj550</driver>
      <driver>cdj670</driver>
      <driver>cdj880</driver>
      <driver>cdj970</driver>
      <driver>hpdj</driver>
      <driver>pcl3</driver>
      <driver>stp</driver>
    </drivers>
  </printer>

The printer ID is between the "<id>" tags, the model name between the
"<model>" tags and the driver names between the "<driver>" tags. Then
the command line to add the queue must be (with the default paper size
set to A4):

   foomatic-configure -s cups -n DeskJet -c file:/dev/usb/lp0
		      -p 133664 -d cdj880 -o PageSize=A4

Exactly the same queue, but for PDQ:

   foomatic-configure -s pdq  -n DeskJet -c file:/dev/usb/lp0
		      -p 133664 -d cdj880 -o PageSize=A4

When the printer is connected to a Samba server (name: "winserver",
queue: "dj"), the line has to be:

   foomatic-configure -s cups -n DeskJet -c smb://winserver/dj
		      -p 133664 -d cdj880 -o PageSize=A4

A raw LPD queue pointing to an HP JetDirect box (IP: 192.168.1.234,
port: 9100) is made this way:

   foomatic-configure -s lpd -n remoteraw -c socket://192.168.1.234:9100/


Modifying a queue
-----------------

Do the same as for adding a queue, but take care that you use the same
queue name. The old queue will be replaced. You only need to supply
the items which you want to change.

Example: The "DeskJet" queue from above can be switched to use the
"DJ8xx" driver (HP's DeskJet driver from
http://hpinkjet.sourceforge.net/). Enter

   foomatic-configure -s cups -n DeskJet -d DJ8xx

Both drivers have the option "PageSize", so its default value (here
"A4") is overtaken to the new driver. So you do not need to configure
all the options again when you change something with
foomatic-configure. Also option defaults set with external programs
(KUPS, CUPS web interface, KDE 2.2 Printer Manager, XPDQ, ...) do not
get lost.

This command line sets an option:

   foomatic-configure -s cups -n DeskJet -o Quality=600photo

and this line you need when you want to connect your printer to the
parallel port:

   foomatic-configure -s cups -n DeskJet -c file:/dev/lp0


Copying a queue
---------------

To copy a queue we have the "-C" option:

   foomatic-configure [-q] [-f] [-s <spooler>] -n <queue> 
		      -C [sourcespooler] sourcequeue
		      -c <connection> 
		      [-p <printer ID> -d <driver ID>] [-o <option>=<value>
	              -o <option>=<value> ...]

This creates the queue <queue> under the spooler <spooler> making a
copy from the queue <sourcequeue> under the spooler
<sourcespooler>. If you do not supply a <sourcespooler>, the source
queue is assumed to be under the same spooler as the copy. All the
other arguments have the same meaning as for creating a queue and they
modify the copy. So lets make two queues for our HP DeskJet 840C with
two different output qualities (under LPRng):

   foomatic-configure -s lprng -n DeskJetHi -c file:/dev/usb/lp0
		      -p 133664 -d DJ8xx -o PageSize=A4 -o Quality=600photo

   foomatic-configure -s lprng -n DeskJetLo -C DeskJetHi 
                      -o Quality=300normal

The first queue is for high quality printouts. The second is for low
quality printouts, here we copy all characteristics of the first
queue, but we modify the quality option to get the lower quality. So
we do not need to type all the other arguments again. The page size
setting of A4 is copied, too.

Now we want to replace LPRng by CUPS without loosing our queues. After
installing CUPS we do:

   foomatic-configure -s cups -n DeskJetHi -C lprng DeskJetHi
   foomatic-configure -s cups -n DeskJetLo -C lprng DeskJetLo

and our queues are transferred to CUPS. LPRng does not need to be
installed to do that copy, but CUPS as the destination spooler must be
running. All option settings, description, location, and so on are
conserved.


Setting the default queue
-------------------------

To define a default queue (which is used when one uses the "lpr", "pdq", or
"foomatic-printjob" commands without the "-P" option) enter

   foomatic-configure [-q] -D [-s <spooler>] -n <queue>

Options in [...] can be left out. The options mean:

   -q		Quiet operation: You are not asked for anything.
   -D		Set the given queue as the default queue.
   -s <spooler>	The spooler to be used. If this option is left out, the
		spooler is auto-detected and the user is asked whether
		the auto-detection is correct (unless -q is given). Possible
		choices are: "lpd", "lprng", "cups", "pdq".
   -n <queue>	The queue name. This argument is required.

Example: Set the "DeskJet" queue from above as the default queue:

   foomatic-configure -s cups -D -n DeskJet

The super user ("root") can set system-wide default queues for all spoolers,
normal users can set a personal default queue for CUPS or PDQ. Use the
 "-Q" option of "foomatic-configure" to find out which is the current
default queue.


Removing a queue
----------------

To remove a queue you do

   foomatic-configure [-q] -R [-s <spooler>] -n <queue>

Options in [...] can be left out. The options mean:

   -q		Quiet operation: You are not asked for anything.
   -R		Delete the given queue.
   -s <spooler>	The spooler to be used. If this option is left out, the
		spooler is auto-detected and the user is asked whether
		the auto-detection is correct (unless -q is given). Possible
		choices are: "lpd", "lprng", "cups", "pdq".
   -n <queue>	The queue name. This argument is required.

Example: Remove the "DeskJet" queue from above:

   foomatic-configure -s cups -R -n DeskJet


Querying info
-------------

You can query info about your configuration with the -Q and the -P
option.  Use

   foomatic-configure -h

to get more info.


Printing
--------

Printing is done with the foomatic-printjob command. It is similar to the
"lpr" commands of the spoolers. It is called as follows:

   foomatic-printjob [-i] [-s <spooler>] [-P <queue>] 
		     [-o <option1>=<value1>] [-o <option2>=<value2>] 
		     [-o <option3>] [<file1>] [<file2>] ...

Options in [...] can be left out. The options mean:

   -i		interactive, the user has to confirm the spooler auto-
		detection
   -s <spooler>	The spooler to be used. If this option is left out, the
		spooler is auto-detected. When the -i option is given the 
		user is asked whetherb the auto-detection is correct.
		Possible choices are: "lpd", "lprng", "cups", "pdq".
   -P <queue>	The queue where the job should be printed. If not given the
		default is read from the PRINTER environment variable or
		the default set with the "-D" option of "foomatic-configure"
		is used. If no default queue is set, it is chosen according
		to the rules of the spooler.
   -o <option>  The switch "option" is set.
   -o <option>=<value> The option "option" is set to the value "value".
   <file>	File(s) to be printed. When no file is given, the data to
		print is taken from standard input.

Example: "file.ps" should be printed on the "DeskJet" in presentation
quality on A4 paper:

   foomatic-printjob -s cups -P DeskJet -o PaperSize=A4 
		     -oQuality=presentation file.ps

The current directory should be printed on the default printer:

   ls | foomatic-printjob

In applications "foomatic-printjob" can be inserted as printing
command instead of "lpr".


More info
---------

Enter

   foomatic-configure -h
   foomatic-printjob -h

for a full option list.

