USAGE

Foomatic 4.1.0
==============

foomatic-db-engine
------------------

Foomatic's database engine generates PPD files from the data in
Foomatic's XML database. It also contains scripts to directly generate
print queues and handle jobs.


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.

Besides Perl with its standard libraries you will need the libxml2
Perl bindings for XML handling and one of the tools "wget" or "curl".

In addition, you need the Foomatic database ("foomatic-db") and the
Foomatic filters ("foomatic-filters"). It is recommended to install
these packages before you install this package. Then the paths to its
components get auto-detected during the build of this package.

"wget" is really a standard tool which nearly every distribution
includes. If yours does not include it, you find "wget" on

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

and "curl" is located on

   http://curl.haxx.se/

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

Foomatic can be installed using the commands (if you have downloaded
this package from the BZR repository, 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 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".

If "configure" did not auto-detect where you have placed the database
(or if you intend to install the database afterwards), do

   export LIBDIR=/path/to/the/database
   ./configure
   make
   make install
   
You have specified the path correctly, when

   /path/to/the/database/db/source/driver/ljet4.xml

exists.

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-ppdfile ..."). 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. To have the local database you
need to put the "foomatic-db" tarball into the main directory of this
package or into the directory where you have also put this package for
unpacking. Simply unpack the database package. You do not need to build or
install it. 

You can use Foomatic databases from wherever you want, edit the "$libdir"
line in lib/Foomatic/Defaults.pm to point to the desired database. To
use the system-wide one, let the line look like:

   ...
   # Library directory; typically /usr/share/foomatic or somesuch.
   $libdir = '/usr/share/foomatic';
   ...

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 printer or multi-function device from HP, install HPLIP from

   http://hplipopensource.com/

before starting to set up printer queues with Foomatic. This gives you
the possibility to access all extra functions of your HP device,
independent whether it is connected via parallel port, USB, or
ethernet. This gives you, depending on the device, functionality, as
ink/toner level check, nozzle check and cleaning, color adjustment,
head alignement, scanning, memory card access, and even sending faxes.

Printing through the MTink daemon from the MTink package
(http://xwtools.automatix.de/) is also supported. When CUPS is the
spooler the special "mtink" backend (included in the MTink package)
will be used. Using the MTink daemon it is possible to check the ink
levels while printing. The MTink daemon supports only Epson inkjets
from the Epson Stylus Color 740 on to the current models.


Easy printer setup with CUPS 1.2 or newer
-----------------------------------------

If you have CUPS 1.2 or newer, you do not need the command line to
set up printers with Foomatic. Simply fire up the web interface entering

http://localhost:631/

and click the "Administration" tab. Then click the "Add this printer" at
the entry of an auto-detected printer (parallel, USB, ethernet) or click
"Add printer" at the top. Follow the instructions on the following pages.

If the printers of the Foomatic database do not appear, check whether the
link to foomatic-ppdfile is in /usr/lib/cups/driver:

lrwxrwxrwx  1 root root 25 Apr 19 18:13 foomatic -> /usr/bin/foomatic-ppdfile

If not, create it manually.

If you want the web interface only list entries for the recommended
driver for each printer, create a file /etc/cups/foomatic.conf
containing the line

OnlyRecommended Yes

Note: CUPS paths may be different on your system.



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] [-w] [-s <spooler>] -n <queue> -c <connection> 
		      [-p <printer ID> -d <driver ID>] [ --ppd <ppdfile> ]
		      [-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: If you queue uses a PPD file generated from
		the Foomatic database, it will be rebuilt when this option
		is set. Otherwise only the default settings are updated.
   -w		Generate PPD which is compatible to the CUPS PostScript
		driver for Windows (GUI strings are limited to 39 characters).
		If you use Adobe's PostScript driver on your Windows clients,
		you do not need to supply this option, because Adobe's driver
		does not have this bug. Usage of Adobe's driver is recommended
		as you do not need to live with crippled GUI strings then.
		This applies only to PPDs built from the Foomatic database, it
		has no influence on PPDs supplied with the "--ppd" option.
   -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,
		These are exactly the URIs as one uses them for CUPS):

		   parallel:<device> : Printer connected to local parallel
				      port, for example "parallel:/dev/lp0".
		   usb:<device>     : Printer connected to local USB port,
				      for example "usb:/dev/usb/lp0". With
				      CUPS 1.1.17 or newer the URI is
				      automatically converted to an URI
				      referring to the printer model and
				      serial number. So if one has plugged
				      the printers in a different order
				      and reboots, they are still found
				      even if they are assigned to other
				      /dev/usb/lp? device files.
		   usb://<make>/<model>?serial=<ser. num.> URIs referring 
				      to printer models/serial numbers can 
				      also be directly given, but they must
				      exactly match one of the URIs listed
				      by "lpinfo -v" (only available for
				      CUPS).
		   serial:<device>  : Printer connected to local serial
				      port, for example "serial:/dev/ttyS1".
		   file:<file name> : Printing into a file, a named pipe,
				      or similar. <file name> can also
			              be a device special file as /dev/lp0,
				      /dev/usb/lp1, ..., so we are 
				      compatible to older versions of
				      Foomatic.
		   hp:/<device name> : HP printer used with the low-level 
				      driver HPLIP (see
				      http://hplipopensource.com/). The
				      device name is name assigned to the
				      device by the HPLIP system, Run
				      "lpinfo -v" to see valid URIs (works
				      only with CUPS).
		   ptal:/<device name> : HP multi-function device used with
				      the obsolete 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". Please
				      replace HPOJ by HPLIP
				      (http://hplipopensource.com/) if you
				      have it still in use somewhere.
		   mtink:/<device name> : Epson Stylus Color, Photo, Pro,
				      or Scan inkjet printer used through
				      the mtink daemon. <device name>
				      is the name of the appropriate pipe
				      in the /var/mtink directory. Example:
				      To print to /var/mtink/C70 the URI is
				      mtink:/C70. 
		   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).
   --ppd <ppdfile> : If you have a PostScript printer which is shipped
		with a PPD file (or a PPD file from the internet, a CD,
		or so), you can set up your print queue with this PPD
		file using this option. Works also with the PPD files
		of CUPS raster drivers, even if another spooler than
		CUPS is used. The driver itself and a Ghostscript version
		with the "cups" device (check with "gs -h") must be
		installed. Compressed PPD files ("file.ppd.gz") are 
		allowed. Do not use "-p" and "-d" then.
   -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>HP-DeskJet_840C</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 and is derived from the
manufacturer and modek name (so it can often be determined without
looking it up). The model name is 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 usb:/dev/usb/lp0
		      -p HP-DeskJet_840C -d cdj880 -o PageSize=A4

Under CUPS 1.1.17 or newer the URI will be converted to an URI referring
to manufacturer, model, and serial number of the printer. So if the printer
gets /dev/usb/lp1 after the next boot, the queue will still work.

Exactly the same queue, but for PDQ:

   foomatic-configure -s pdq  -n DeskJet -c usb:/dev/usb/lp0
		      -p HP-DeskJet_840C -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 HP-DeskJet_840C -d cdj880 -o PageSize=A4

If you have an HP LaserJet 4050, which is a PostScript printer, you
can get its PPD file from its Windows driver CD, http://hplip.sf.net/,
or http://www.openprinting.org/. After downloading it you can set up a
queue as follows:

   foomatic-configure -s pdq  -n LJ4050 -c socket://printer:9100
		      --ppd HP_LaserJet_4050_Series.ppd -o PageSize=A4
   
and you get full access to all features of the printer, even with
non-PPD-aware spoolers (as PDQ in this example). Compressed PPD files
("file.ppd.gz") are also allowed here.

In this example we set up an Epson Stylus Photo 1290 with the CUPS
driver of Gutenprint, but with PDQ as the spooler:

   foomatic-configure -s pdq  -n Eps1290 -c usb:/dev/usb/lp0
		      --ppd escp2-1290.ppd -o PageSize=A4

One simply takes the PPD file which comes with the CUPS
driver. Naturally the CUPS driver itself and a Ghostscript with the
"cups" output device (Check with "gs -h", ESP Ghostscript
recommended). In most cases you will need also the CUPS libraries to
run a CUPS driver or to compile Ghostscript/the driver with CUPS
support. The liberaries (and its "-devel" or "-dev" for compiling
drivers/Ghostscript) are only a small part of CUPS and in most distros
you can install the separately.

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
"hpijs" driver (HP's DeskJet driver from
http://hplipopensource.com/). 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. Option settings are also overtaken when one switches from
a Foomatic setup ("-p <printer> -d <driver>" to a setup with a
manufacturer-supplied PPD ("--ppd <ppd file>") or vice-versa or
from one to another manufacturer-supplied PPD.

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 parallel:/dev/lp0



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

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

   foomatic-configure [-q] [-f] [-w] [-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 usb:/dev/usb/lp0
		      -p HP-DeskJet_840C -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.

When one has set up a USB printer with CUPS, its URI is converted to
an URI referring to manufacturer, model, and serial number (see
above). As these URIs are not supported by other spoolers, they are
converted back in the copied queue under the bew spooler. But note
that for this back-conversion CUPS must still be installed and running
(it uses the "lpinfo -v" command of CUPS). When a USB printer queue is
copied from another spooler to CUPS, the URI is also automatically
converted to the new URI referring to manufacturer, model, and serial
number.


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 PPD files for manual queue setup
----------------------------------------

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

   foomatic-ppdfile -h

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

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

to know how to set up a queue with these PPD 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 
		     -o Quality=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

   pdq -P DeskJet -odocs ~/.bashrc


- Direct, spooler-less printing

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

   foomatic-rip [-P <queue>] [--ppd <ppdfile>]
       [-o <option1>=<value1>] [-o <option2>=<value2>] 
       [-o <option3>] [<file1>] [<file2>] ... [ > <destination> ]

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.
   --ppd <ppdfile> If your printer is not configured (or for testing/
		debugging) you can specify a PPD file which defines
		how the job should be handled. The PPD file cane be
		one generated by Foomatic, but also one shipped with a
		PostScript printer.
   -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.
   > <destination> If no destination ("/dev/lp0", ...) for the output
		data is specified, the data is directed to standard
		output. In most cases it makes more sense to re-direct
		the output to a printer or into a file.

The first example from above looks like the following now:

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

Print a listing of valid options with

   foomatic-rip -P DeskJet -o docs ~/.bashrc

If you want to try out a PostScript printer which you have not configured
yet, do

   foomatic-rip --ppd HP_LaserJet_4050_Series.ppd file.ps > /dev/lp0
   foomatic-rip --ppd HP_LaserJet_4050_Series.ppd file.ps | nc -w1 host 9100

The first command assumes that the printer is on the first parallel
port.  Make sure that you have write permissions to /dev/lp0. The
second command one has to use when the printer is connected via the
local network, has the host name "host" and listens for jobs on port
9100 (TCP/Socket/JetDirect).

You can also use this for debugging purposes, for example when your
jobs do not get printed. This surrounds the spooler and sends the
filtered job directly to the printer. When they get printed this way,
the problem is probably a problem of the spooler, not of the printer
or the driver.

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


Applying options only to selected pages
---------------------------------------

With most spoolers options can be supplied only to selected pages when
Foomatic is used. The queues can be either Foomatic queues or they can
use a manufacturer-supplied PPD file with "foomatic-rip". To make CUPS
using "foomatic-rip" with manufacturer-supplied PPD files, add the
line

*cupsFilter:    "application/vnd.cups-postscript 0 foomatic-rip"

to the PPD file. To make an option setting acting only on certain
pages one only needs to preceed the option by a page specification:

CUPS, GNUlpr, CPS, no spooler:
  lpr -o 1:InputSlot=Letterhead
  lpr -o even:Watermark=on
  lpr -o 1,6-10,15,20-:MediaType=YellowPaper

LPRng:
  lpr -Z 1-2:MediaType=Cardboard

LPD:
  lpr -J "1,6-10,15,20-:MediaType=YellowPaper"

PPR (RIP):
  ppr --ripopts "1:InputSlot=Letterhead"

PPR (Interface)
  ppr -i "1:InputSlot=Letterhead"

The syntax is "even", "odd", or giving comma-separated page numbers or
page ranges. Applying options to selected pages with PDQ is not
supported. Note that specifying a page selection with the "-F" option
of "ppr" does not work.

Option settings with page selection override option settings for the
whole document on the appropriate pages. More specific (less pages
selected) settings override less specific settings on the appropriate
pages.

Page-specific option settings cannot be set as default in the PPD
files, but they can be set by editing the ~/.lpoptions file of CUPS.


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