
Foomatic 2.0.2
==============

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. 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, GNUlpr, CUPS, PPR, PDQ, 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" 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.

The only things which you need except Perl, are a C compiler (usually
gcc) with its standard libraries, the "make" utility, either the
"wget" or the "curl" utility, and the libxml C library for XML
handling. All this is part of nearly every distribution of GNU/Linux
or *BSD, especially because libxml is also used by GNOME. One can also
easily build it on any Unix-like operating system.

If your distribution does not provide "wget" you can find it on

   http://www.gnu.org/software/wget/wget.html

and "curl" is located on

   http://curl.haxx.se/

If your distribution does not contain libxml or a too old version of
it, you can get libxml from

   http://www.xmlsoft.org/

If your distribution contains libxml, note that besides the "libxml"
or "libxml2" package you must install also a package with a name
"libxml-devel" or "libxml2-devel" to be able to compile programs which
use libxml. This additional package contains the needed header files
and "xml(2)-config", which tells the C compiler where it finds the
header files. If "xml(2)-config" or some header files in the packages
of your distribution are missing, compile libxml from source.

I (Till) have tested with the versions 1.8.17 and 2.4.19 of libxml,
both work, but 1.8.17 requires that the XML files do not have leading
blank lines. Use foomatic-fix-xml if you have such XML files (old or
third-party files). libxml 1.8.9 and earlier do not work.

Using libxml 2.x is highly recommended.

For Foomatic making sense one also needs GhostScript (5.50 or newer,
GNU GhostScript 6.53 or newer recommended) if one has a
non-PostScript printer. In addition, the appropriate driver for a
non-PostScript printer must be installed.

After installing the libxml Foomatic can be installed using the
commands (if you have downloaded this package from CVS, run
"./make_configure" at first, for that you will also need libxml 2.x,
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 libxml is installed and
which version and also where relevant programs, files, and directories
of your printer spooler are located. In addition, it is made sure that
Perl will find the Perl libraries of Foomatic. 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 is installed into subdirectories of /usr/local
(e. g. /usr/local/bin/foomatic-configure), to get it into subdirectories
of /usr (/usr/bin/foomatic-configure), 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-datafile ..."). This also works on a machine where
a system-wide Foomatic is already installed. This way you can develop
XML files for the database and test them in your local database
without messing up the system-wide one.

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", "enscript", and "mpage". Recommended
is "a2ps" because it detects many file types (text, PDF, most image
formats) and together with ImageMagick (for images) and GNU 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 the filter script for your spooler and used
automatically if necessary. CUPS and PPR need this tool only for
printing the option list, they use internal filters for printing
non-PostScript files. The PDQ configuration files only supports
"mpage", with LPD, GNUlpr, LPRng, or direct, spooler-less printing you
can use all tools.

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

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. 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.


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> ...] [--oldppd]

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", "ppr", "direct".
   -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, ...
		   ptal:/<device name> : HP multi-function device used with
				      the low-level driver HPOJ (see
				      http://hpoj.sourceforge.net/). The
				      device name is name assigned to the
				      device by the ptal-mlcd daemon, for
				      example "mlc:usb:PSC_950".
		   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
				      (SMB not available in PDQ, workgroup
				      ignored in PPR).
		   ncp://<server>/<queue>
		   ncp://<user>:<password>@<server>/<queue> : Printer on
				      Novell NetWare server (only LPD, 
				      LPRng, and direct printing).
		   postpipe:"<command line>" : Pipe the PostScript output
				      into the given command line (only LPD,
				      LPRng, and direct printing).
		   stdout	      Print to standard output (only 
				      available for direct printing).

   -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.
   --oldppd     If you set up a queue for CUPS, a PPD-O-Matic PPD file will
		be created because this is closer to the Adobe standards.
		These files work also with XPP 1.1 and KDE 3.x. If you want
		to have XPP 1.0 and the printer manager of KDE 2.x correctly
	        working, you should let foomatic-configure generate the older
	        CUPS-O-Matic PPD files by setting this option. Note that you
		have to give it whenever you modify your queue.

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>
    <driver>hpijs</driver>
    <drivers>
      <driver>cdj550</driver>
      <driver>cdj670</driver>
      <driver>cdj880</driver>
      <driver>cdj970</driver>
      <driver>hpdj</driver>
      <driver>hpijs</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

This gives you a CUPS queue with a PPD-O-Matic PPD file. For getting a
CUPS-O-Matic PPD file you should use (see "--oldppd" in the option
list above for more info):

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

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/

If you want to print on a multi-function device from HP you should use
the low-level driver HPOJ (http://hpoj.sourceforge.net/) so that you
are also able to scan or to access memory cards. For USB devices you
need HPOJ even when you only want to print. To set up a queue, set up
HPOJ first and then look for the HPOJ device for your printer. You
find it in the /etc/ptal-start.conf file in the line where
"ptal-printd" is started, directly after "ptal-printd", for example
"mlc:usb:PSC_950" for an HP PSC 950 connected via USB. To set up a
queue for this printer under CUPS you have to enter:

   foomatic-configure -s cups -n PSC950 -c ptal:/mlc:usb:PSC_950
		      -p HP-PSC_950 -d hpijs -o PageSize=A4

If you use CUPS 1.1.12 and newer, you need the most recent "ptal"
backend script from

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

(use the "File"/"Save as ..." function of your browser to get it onto
your hard disk). Copy the file into

   /usr/lib/cups/backend/ptal

and make it executable

   chmod a+rx /usr/lib/cups/backend/ptal

Now restart the CUPS daemon and ONLY NOW set up your printer queue,
foomatic-configure will then auto-detect the script and make use of
it.


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
"hpijs" driver (HP's DeskJet driver from
http://hpinkjet.sourceforge.net/). Enter

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

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 Printing 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

Do not forget to add the "--oldppd" option at every queue modification
when you are using CUPS queues with the old CUPS-O-Matic PPD files.


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 hpijs -o PageSize=A4 
		      -o Quality=600PhotoCMYK

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

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.

Add the "--oldppd" when the copy should be a CUPS queue with the old
CUPS-O-Matic PPD file.


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", "ppr", "direct".
   -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", "ppr", "direct".
   -n <queue>	The queue name. This argument is required.

Example: Remove the "DeskJet" queue from above:

   foomatic-configure -s cups -R -n DeskJet


Getting data files for manual queue setup
-----------------------------------------

You can get Foomatic data files for manual queue setup. Use

   foomatic-datafile -h

to get information about how to get the data files and follow the
links on

   http://www.linuxprinting.org/foomatic.html

to know how to set up a queue with these data files.


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 from the command line with Foomatic
--------------------------------------------

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", "ppr",
		"direct".
   -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 PageSize=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".


Printing from the command line with your spooler's printing command
-------------------------------------------------------------------

You do not need to have Foomatic installed on all your clients to be
able to print on your printer which you have set up on your server
using Foomatic. You can use the normal printing commands of your
printing system. Proceed as follows:


- LPD

Stock LPD (not LPRng or GNUlpr) do not support the submission of
option settings along with the print job. Here a workaround is used by
stuffing the option settings into the job title field:

   lpr [-P <queue>] 
       [-J '<option1>=<value1> <option2>=<value2> ... 
            <option3> ...'] [-Jdocs] [<file1>] [<file2>] ...

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

   -P <queue>	The queue where the job should be printed. If not given the
		default is chosen according to the rules of the spooler.
   -J '...'     Option settings, they must be enclosed in the '-J' option.
		The settings can be expressed as follows:
		<option>          The switch "option" is set.
		<option>=<value>  The option "option" is set to the value
		                  "value".
   -J docs      Print listing of the options. Works only when you provide
		a file or something on standard input (which will not be 
		printed).
   <file>	File(s) to be printed. When no file is given, the data to
		print is taken from standard input.

All other options can be used as forseen by the LPD printing system.

The first example from above looks like the following now:

   lpr -P DeskJet -J 'PageSize=A4 Quality=presentation' file.ps

Print a listing of valid options with

   lpr -P DeskJet -J docs ~/.bashrc


- LPRng

LPRng uses "-Z" to include option settings:

   lpr [-P <queue>] 
       [-Z <option1>=<value1>] [-Z <option2>=<value2>] 
       [-Z <option3>] [<file1>] [<file2>] ...

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

   -P <queue>	The queue where the job should be printed. If not given the
		default is chosen according to the rules of the spooler.
   -Z <option>  The switch "option" is set.
   -Z <option>=<value> The option "option" is set to the value "value".
   -Z docs      Print listing of the options. Works only when you provide
		a file or something on standard input (which will not be 
		printed).
   <file>	File(s) to be printed. When no file is given, the data to
		print is taken from standard input.

All other options can be used as forseen by the LPRng printing system.

The first example from above looks like the following now:

   lpr -P DeskJet -Z PageSize=A4 -Z Quality=presentation file.ps

Print a listing of valid options with

   lpr -P DeskJet -Z docs ~/.bashrc


- CUPS/GNUlpr

These spoolers use "-o" to include option settings:

   lpr [-P <queue>] 
       [-o <option1>=<value1>] [-o <option2>=<value2>] 
       [-o <option3>] [<file1>] [<file2>] ...

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

   -P <queue>	The queue where the job should be printed. If not given the
		default 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".
   -o docs      Print listing of the options. Works only when you provide
		a file or something on standard input (which will not be 
		printed).
   <file>	File(s) to be printed. When no file is given, the data to
		print is taken from standard input.

The first example from above looks like the following now:

   lpr -P DeskJet -o PageSize=A4 -o Quality=presentation file.ps

Print a listing of valid options with

   lpr -P DeskJet -o docs ~/.bashrc


- PPR

PPR uses the "ppr" command for printing and options are set by "-F":

   ppr [-d <queue>] 
       [-F "*<option1> <value1>"] [-F "*<option2> <value2>"] 
       [-F "*<option3> True"] [<file1>] [<file2>] ...

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

   -d <queue>	The queue where the job should be printed. If not given the
		default is chosen according to the rules of the spooler.
   -F "*<option> True" The switch "option" is set.
   -F "*<option> <value>" The option "option" is set to the value "value".
   -i docs      Print listing of the options. Works only when you provide
		a file or something on standard input (which will not be 
		printed).
   <file>	File(s) to be printed. When no file is given, the data to
		print is taken from standard input.

The first example from above looks like the following now:

   ppr -d DeskJet -F "*PageSize A4" -F "*Quality presentation" file.ps

Print a listing of valid options with

   ppr -d DeskJet -i docs ~/.bashrc


- PDQ

PDQ uses "-o" and "-a" to include option settings:

   pdq [-P <queue>] 
       [-o<option1>_<value1>] [-o<option2>_<value2>] 
       [-o<option3> -a<num_option>=<num_value>] [<file1>] [<file2>] ...

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

   -P <queue>	The queue where the job should be printed. If not given the
		default 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".
   -a<num_option>=<num_value> The numerical option "num_option" is set to 
		the value "num_value".
   -odocs       Print listing of the options. Works only when you provide
		a file or something on standard input (which will not be 
		printed).
   <file>	File(s) to be printed. When no file is given, the data to
		print is taken from standard input.

The first example from above looks like the following now:

   pdq -P DeskJet -oPageSize_A4 -oQuality_presentation file.ps

Print a listing of valid options with

   lpr -P DeskJet -odocs ~/.bashrc


- Direct, spooler-less printing

Here one uses the "directomatic" filter with a similar syntax as the "lpr"
commands of CUPS and GNUlpr. Use "-o" to include option settings:

   directomatic [-P <queue>] 
       [-o <option1>=<value1>] [-o <option2>=<value2>] 
       [-o <option3>] [<file1>] [<file2>] ...

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

   -P <queue>	The queue where the job should be printed. If not given the
		default 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".
   -o docs      Print listing of the options. Works only when you provide
		a file or something on standard input (which will not be 
		printed).
   <file>	File(s) to be printed. When no file is given, the data to
		print is taken from standard input.

The first example from above looks like the following now:

   directomatic -P DeskJet -o PageSize=A4 -o Quality=presentation file.ps

Print a listing of valid options with

   directomatic -P DeskJet -o docs ~/.bashrc

Note that "directomatic" only exits when the whole data is passed
through the printer driver and sent to the printer, because we hav no
spooler which stores the data on the hard disk to print out of the
background.


Printing from the command line with libppd/ppdfilt
--------------------------------------------------

If you do not want to install Foomatic on a client machine you can
also use the ppdfilt utility of the libppd
(http://libppd.sourceforge.net/, http://sourceforge.net/projects/lpr)
to submit jobs with option settings (for example when the client uses
stock LPD (not LPRng) and the server CUPS). You need to download the
PPD-O-Matic PPD file for your printer onto the client. It is generated
by foomatic-configure when setting up the printer and you find it as
/etc/foomatic/<printer queue name>.ppd on your server. Then enter a
command line as follows:

   ppdfilt [-p <PPD-O-Matic PPD file>]
	   [-o <option1>:<value1>] [-o <option2>:<value2>] 
           [-o <option3>] [<file1>] [<file2>] ... | lpr [-P <queue>]

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

   -p <PPD file> The PPD file for your printer, if not given, the file
                name is read from the PPD environment variable.
   -P <queue>	The queue where the job should be printed. If not given the
		default defined on your client is used.
   -o <option>  The switch "option" is set.
   -o <option>:<value> The option "option" is set to the value "value".
		Note that "ppdfilt" needs a ":" between the option name
		and its value, and not a "=".
   <file>	File(s) to be printed. When no file is given, the data to
		print is taken from standard input.

The first example from above will look as follows:

   ppdfilt -p DeskJet.ppd -o PageSize:A4 -oQuality:presentation file.ps | 
           lpr -P DeskJet

Extra options of ppdfilt can be used independent of Foomatic.


Printing through a graphical interface
--------------------------------------

XPP (http://cups.sourceforge.net/xpp/),
QtCUPS (http://cups.sourceforge.net/qtcups/)

These graphical interfaces for CUPS work just out of the box. You call
them instead of "lpr" or "foomatic-printjob" (from the command line or
out of an application) and you get a window to select the desired
printer and thanks to the capabilities of CUPS you also can access all
options of the driver (through the "Options" or "Properties" button),
independent whether the printer is on the local or on a remote
machine. When you are using kprinter, QtCUPS or XPP 1.0 or earlier you
should set up your queues with the old CUPS-O-Matic PPD files
("--oldppd" option in foomatic-configure). XPP 1.1 (upgrading to this
version is highly recommended) is adapted to handle both CUPS-O-Matic
and PPD-O-Matic PPD files, the QtCUPS development was discontinued
before the PPD-O-Matic PPDs were introduced (QtCUPS is replaced by
kprinter now).

GTKLP (http://www.stud.uni-hannover.de/~sirtobi/gtklp/index.html)

This is another graphical frontend for CUPS, which works the same way
as XPP and QtCUPS, but it does not show the numerical options of the
drivers. To make the numerical options at least visible as enumerated
options, you should set up your printer queue with the PPD-O-Matic PPD
file (No "--oldppd" option in foomatic-configure). Note that then XPP
1.0 or earlier, QtCUPS and kprinter 2.x will not work correctly any
more.

GPR (http://sourceforge.net/projects/lpr)

GPR is a graphical printing interface made for GNUlpr (VA-Linux LPD)
and LPRng. Stock LPD is not supported because it does not provide
option passing (the "-J'option1=setting1 option2=setting2 ...'" trick
of Foomatic is not supported by GPR). GPR can also be used as frontend
for CUPS when one sets up one's printers with Foomatic as shown
above. As PPD files for GPR use the PPD-O-Matic PPD files for all
spoolers, they are automatically generated by foomatic-configure and
dropped into /etc/foomatic/<printer queue name>.ppd when you set up
your printer as shown above. For printers on CUPS servers GPR will
also work with the CUPS-O-Matic PPD files, but it will not show the
numerical options. So setting up CUPS queues with the PPD-O-Matic PPDs
is recommended.

kprinter (http://www.kde.org/)

This is the printing interface of KDE 2.2 and newer, it either appears
as the printing dialog of KDE applications or you use the "kprinter"
command instead of "lpr" on the command line or in non-KDE
applications. For users of CUPS it behaves exactly as QtCUPS (see
above), for users of LPD/LPRng/GNUlpr it does not show the Foomatic
options. When you are using kprinter of KDE 2.x with CUPS you should
set up your queues with the old CUPS-O-Matic PPD files ("--oldppd"
option in foomatic-configure), when you are using KDE 3.x or no KDE at
all the PPD-O-Matic PPD files are recommended.


Printing from applications
--------------------------

The PPD-O-Matic PPD files, which foomatic-configure generates in the
/etc/foomatic directory, can be used to make the driver options of
your printer(s), which you have set up with Foomatic, available in
various PPD-file-aware applications. If you are using CUPS do not use
the CUPS-O-Matic PPD files, set up your queues with PPD-O-Matic PPD
files (No "--oldppd" option in foomatic-configure) or use the
PPD-O-Matic PPD file which is always in /etc/foomatic. Otherwise you
will not have access to the numerical options.

If your printer is on a remote CUPS server and you have set it up with
a PPD-O-Matic PPD file, you can easily download the PPD file to your
client with

wget http://<server name or IP>:631/printers/<printer queue name>.ppd

or by entering the web interface of CUPS (http://localhost:631/),
clicking on "Manage Printers", and then clicking on the icon of the
desired printer. Then click on the "Location" (internet address) field
and add ".ppd" to the end of the line. After pressing <Enter> the PPD
file will be displayed and you only need to save it on your local disk
with "File"/"Save As ...".

Many non-PPD-aware applications allow setting a printing
command. Replace "lpr" by one of the above-mentioned graphical
interfaces here ("xpp", "kprinter", "gpr", ...) so that you can choose
the printer and access the options. You can also add options to the
"lpr" command in the printing command field or use "foomatic-printjob"
there.

Note that the font handling in KDE 2.x is totally broken. If you
cannot print correctly with KDE 2.x applications, especially if you
use fancy fonts, this is most probably not a bug of Foomatic or your
printer driver. Try printing with a non-KDE application at first to
check this. OpenOffice.org 1.0 or newer is highly recommended as free
office solution.

Here are some tips for using common applications with PPD-O-Matic PPD
files:


Star Office 5.x (http://www.sun.com/staroffice/)

If you want to get all the options of your printer into the printing
dialog of Star Office ("Properties" button), you can use the
PPD-O-Matic PPD files (/etc/foomatic/<printer queue name>.ppd) as Star
Office "drivers" and this way fully support all Foomatic-supported
printers under Star Office.

To do so start "spadmin", the printer setup program of Star Office (it
is usually in /opt/office52/program or /usr/lib/office52/program) as
"root". Click on "Install new driver ..." and in the dialog use the
"Browse" button to navigate to the directory where the PPD-O-Matic PPD
file for your printer is located. Choose the file in the file list and
click "OK". Now your printer has an entry in the list "Existing
printer drivers". Choose it and click "Add new printer". Choose the
new entry in "Installed printers" and click on "Connect". In the
dialog choose the queue with the command pointing to your printer or
enter a new, non-existing queue name, an "=" character, and the
command to print PostScript files on your printer plus a perl
one-liner to fix the bug of the Euro currency symbol not being
printed, for example:

EpsonQueue=perl -p -e "s=16#80 /euro=16#80 /Euro=" | lpr -P Epson

Do not specify graphical frontends as "xpp", "kprinter", "gpr" ... as
printing command. Click on "Configure" to adjust the default settings
for your printer and on "Test page" to check whether all works. No
close "spadmin" and start Star Office. When you select "File"/"Print"
you can choose your printer and with the "Properties" button all the
options provided by the printer driver.


Open Office (http://www.openoffice.org/)/
Star Office 6.0 (http://www.sun.com/staroffice/)

The printing environment of OpenOffice.org and Star Office 6.0 is very
similar to the one of the old Star Office versions. As Star Office 6.0
is a snapshot of OpenOffice.org with some proprietary enhancements the
way setting up printers for both programs is absolutely identical.

Start the printer setup program "spadmin" as "root" (in most cases you
find it in /opt/openoffice/, /usr/lib/openoffice/, /opt/office60/, or
/usr/lib/office60/). In its main window click on "New Printer...". A
wizard opens and on its first page choose "Add a printer". The next
page shows a list of printer models. These entries come from PPD files
of native PostScript printers which were already shipped with
OpenOffice.org or Star Office 6.0. Click "Import" to import your
PPD-O-Matic PPD file into the list. Then a "Driver Installation"
dialog appears. There click on "Browse" to get to the directory with
your PPD file or type in the path. If you did it correctly, the name
of your printer model appears in the big field. Note that when you use
the "Browse" button, the browsing dialog does not show any file
name. Click on the entry with your printer's model name and then on
OK. Now your printer is in the list of printer models in the wizard
and you can choose it. The next step asks for the desired printing
command. Choose the "lpr" command for your printer's queue in the
list. Then add a Perl one-liner to it so that the bug of the Euro
currency symbol not being printed gets fixed, as the following example
shows:

perl -p -e "s=/euro /unused=/Euro /unused=" | lpr -P laserjet

Do not use graphical frontends as "xpp", "gpr", "kprinter" or similar
as printing command. On the last page of the wizard you only need to
give a name to the new printer and tell whether it should be the
default printer (for OpenOffice.org/Star Office 6.0). Now you can
print out of all applications of your office suite and access all the
printer's/the driver's options via the "Properties" button in the
printing dialog.

If you have OpenOffice.org 638 or earlier, either update to a newer
version, or proceed as following:

Unfortunately, the older versions of OpenOffice.org do not include
"spadmin". So you have to edit the config file manually to integrate
your printer.

A note about directories: Depending on your installation the
OpenOffice.org directory can be at different places:
/usr/lib/OpenOffice.org638, /opt/OpenOffice.org638,
/usr/local/lib/OpenOffice.org638, /home/<yourlogin>/OpenOffice.org638,
... for simplicity I will only refer to /usr/lib/OpenOffice.org638 in
the following. Please use the directory according to your
installation.

At first copy (or link) the PPD-O-Matic PPD file
(/etc/foomatic/<printer queue name>.ppd) into the
/usr/lib/OpenOffice.org638/share/psprint/driver directory and rename
the copy (or the link) to have the file name extension ".PS". Make the
file world-readable ("chmod 644 <filename>"). When you have done so,
edit the file /usr/lib/OpenOffice.org638/share/psprint/psprint.conf
copying the part beginning with "[Generic Printer] up to the next
expression in square brackets ("[...]") or, if there is no such
expression, up to the end of the file. The copied dataset will be the
dataset for your printer. Now edit this dataset: modify the name in
the square brackets to a name which your printer should have in the
menu, spaces are allowed. In the line starting with "Printer=" you
have to provide two items, one befor and one after the slash ("/"),
before the slash you put the name of the PPD file which you have put
into /usr/lib/OpenOffice.org638/share/psprint/driver, without the
".PS", after the slash you repeat the name which you have put into the
square brackets, without the square brackets. Every printer dataset
has a line beginning with "DefaultPrinter=", enter "1" in this line
for the printer which should be the default printer, "0" in the
others. "Location=" and "Comment=" are only comments shown in the
printing dialog of OpenOffice.org, you don't need to fill them
in. "Command=" should contain the command line command to print
PostScript files on your printerplus a perl
one-liner to fix the bug of the Euro currency symbol not being
printed, for example:

perl -p -e "s=/euro /unused=/Euro /unused=" | lpr -P Epson

Do not specify graphical frontends as "xpp", "kprinter", "gpr"
... here. Leave the default settings for all the remaining entries.

The entry for your printer could look like the following (Assuming the
PPD file is copied/linked to
/usr/lib/OpenOffice.org638/share/psprint/driver/Eps1290.PS and the
printer queue name is "Epson", comments are not shown):

[Epson Stylus Photo 1290]
   Printer=Eps1290/Epson Stylus Photo 1290
   DefaultPrinter=1
   Location=Graphics Department, 2nd floor
   Comment=Photo-capable (6-ink) A3-format printer
   Command=perl -p -e "s=/euro /unused=/Euro /unused=" | lpr -P Epson
   PerformFontSubstitution=true
   SubstFont_Helmet= ...
   ...

After saving the configuration file you (re)start your OpenOffice.org
applications and then printing works as in the other versions of
OpenOffice.org and Star Office.


The GIMP (http://www.gimp.org/)

The GIMP uses the GIMP-Print plug-in
(http://gimp-print.sourceforge.net/) to print. If it is installed you
can click into the window with your image using the right mouse button
and then choose "File" and "Print". In the printing dialog choose your
printer queue (if it is not listed, click "New Printer ..." to create
a list entry) and click on "Setup Printer ...". If your printer is
listed, it is supported by GIMP-Print and you do not need a PPD file
for using it with GIMP. If it is not listed, choose "PostScript Level
2". Then an input field for a PPD file will appear. Enter the path and
name under which your PPD-O-Matic PPD file is located
(foomatic-configure generates it as /etc/foomatic/<printer queue
name>.ppd) or choose it with the "Browse" button. Adapt the printing
command to your spooler, especially remove the "-oraw" option, because
it is important that the print job is going through the Foomatic
filter. After closing the dialog with "OK" the fields for the options
("Media Size", "Media Source", ...) will contain the choices according
to your printer. Click "Save Settings" to make your setup permanent.


Printing from Windows clients
-----------------------------

When you have configured a printer on a GNU/Linux or Unix server with
Foomatic, you can set up Windows clients using the generic PostScript
printer driver (best from http://www.adobe.com/) and the PPD-O-Matic
PPD file (/etc/foomatic/<printer queue name>.ppd). Then you don't need
to install the Windows driver for your printer. On Epson inkjets
driven by the current version of GIMP-Print you could even obtain a
better printout quality than with the Windows driver. You can also do
things as installing filters which parse the PostScript and count the
pages on your server which is not possible when the client's Windows
driver sends a data stream in a proprietary format. It also helps you
when you have an old printer which works nicely under Windows 3.1 and
under GNU/Linux or Unix with GhostScript, but not any more under
Windows 98/ME/XP/2000.

To set up this you should configure the Samba (http://www.samba.org/)
on your server so that its printing command does not contain options
for raw (unfiltered) printing ("-oraw", "-l"). The printing command
you find in /etc/samba/smb.conf in the "[printers]" section in the
"print command = " line. It is also convenient to make the PPD-O-Matic
PPD files downloadable for the Windows clients.

When you have CUPS 1.1.12 or newer on your server you can get it even
easier by the "cupsaddsmb" tool. Set up your printers with PPD-O-Matic
PPD files (No "--oldppd" option in foomatic-configure) and than follow
the instructions shown by "man cupsaddsmb".


More info
---------

Enter

   foomatic-configure -h
   foomatic-printjob -h

for a full option list or see the man pages:

   man foomatic-configure
   man foomatic-printjob

