Foomatic 3.0.2 ============== 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> 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 free operating systems and free printer drivers, where "free" is meant as free software in the sense of the Free Software Foundation (http://www.gnu.org). Therefore the database only contains information about printer drivers which are free software. The technology of this database can also be used for non-free drivers, but the database entries have to be published in separate packages then. The database can also be run under non-free operating systems (as commercial Unixes) as they often use GhostScript and free printer drivers. Since most free operating systems (GNU/Linux, *BSD, ...) are compatible to Unix, their applications send PostScript to the printer queues. Therefore one usually hands over the PostScript directly to a PostScript printer (sometimes with some prepended PostScript commands for options) or uses GhostScript for generating the data format the printer needs. This is done by the printer spooler which also stores the data in a spool directory when the printer is still occupied by another job, transmits the data to a print server in the network, and so on. The printer drivers for non-PostScript printers are either compiled into GhostScript, a plug-in for GhostScript (e. g. IJS drivers), or they are an extra filter which converts a generic bitmap generated by GhostScript into the printer's data format. For this the spooler has to call complicated command lines of GhostScript and the extra filter (if needed). The user of a free operating system normally does not see these command lines because an installation program takes appropriate filter scripts and/or description files from a database and assigns them to the printer queue. Widely used databases were the RHS-Printfilters and the APS filters. Their disadvantages were that they only supported one spooler (LPD/LPRng) and only a small part of the driver's options (mostly page size and resolution). Foomatic supports all options of the drivers and all known spoolers (LPD, LPRng, GNUlpr, CUPS, PPR, PDQ, CPS, direct spooler-less printing). In addition, all known free software printer drivers are supported. Foomatic also supports printing of various non-PostScript file types for spoolers which do not support this by themselves (LPD, LPRng, GNUlpr, spooler-less printing). To enable this feature you need to have "a2ps", "enscript", or "mpage" installed. Another problem is that the way how to install queues, to print files, and to handle jobs is very different with different spoolers. LPD for example requires editing of configuration files for adding a queue, whereas CUPS and PPR have specialized command line utilities. Foomatic puts a layer between the applications and the spoolers so that one has a common, spooler-independent command line interface for all spoolers, so that switching of spoolers or administration of a network with different spoolers gets much easier, because for the same operations there are the same commands, independent of the spooler. This command line interface can also be used as a base for spooler-independent graphical frontends. Installation ------------ Foomatic runs on all systems where one can run the Perl interpreter. Besides Perl and a C compiler with its standard libraries you will need the libxml C library for XML handling and one of the tools "wget"/"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/ Because libxml is also used by GNOME, it is probably also part of every distribution of GNU/Linux or *BSD and one can also easily build it on any Unix-like operating system. If you distribution does not provide libxml 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. Till has 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, ESP GhostScript 7.05.4 or newer highly 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 package, 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". 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://hpinkjet.sourceforge.net/ 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 -------------------------------- 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://hpinkjet.sourceforge.net/). 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 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" (Obsolete, but still working). 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://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. 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. Printing from the command line with libppd/ppdfilt -------------------------------------------------- In most cases you don't need this, because foomatic-rip has more or less the same functionality (see section directly above this one) and is much easier to install (one Perl script). If you do not want to install Foomatic (or at least foomatic-rip and the PPD file) 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 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/<spooler>/<printer queue name>.ppd on your server. Then enter a command line as follows: ppdfilt [-p <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 -o Quality: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/), GTKLP (http://www.stud.uni-hannover.de/~sirtobi/gtklp/index.html) 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" button or the tabs), independent whether the printer is on the local or on a remote machine. 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 use the PPD files assigned to your print queues, they are stored on your hard disk as /etc/foomatic/<spooler>/<printer queue name>.ppd kprinter (http://printing.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 as the other graphical frontends for CUPS (see above), for users of LPD/LPRng/GNUlpr older versions do not show the Foomatic options, recent do. In addition to providing access to all printers and driver options, you can also let you jobs being pre-filtered (for example to make booklets with the tools of the "ps-utils" package or to pretty-print text files with "a2ps"), or you can print posters on usual A4/Legal-sized printers. CUPS user have also access to job scheduling and priority features of CUPS. Printing from applications -------------------------- The PPD files, which foomatic-configure generates in (or copies to) the /etc/foomatic/<spooler>/ 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 your printer is on a remote CUPS server and you have set it up with a PPD file (no raw queue), 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 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 PPD files (/etc/foomatic/<spooler>/<printer queue name>.ppd) as Star Office "drivers" and this way fully support all Foomatic-supported (or PostScript printer PPD 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 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 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 file (/etc/foomatic/<spooler>/<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 Gutenprint plug-in (http://gutenprint.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 Gutenprint 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 file is located (foomatic-configure puts it into /etc/foomatic/<spooler>/<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 a generic PostScript printer driver (best from http://www.adobe.com/, but for certain Windows versions also from http://www.cups.org/) and the PPD file (/etc/foomatic/<spooler>/<printer queue name>.ppd) assigned to the queue. Then you don't need to install the Windows driver for your printer. On Epson inkjets driven by the current version of Gutenprint 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 files of the queues 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. After setting up your printer(s) with foomatic-configure follow the instructions shown by "man cupsaddsmb". NOTE: The PostScript driver for Windows from CUPS (http://www.cups.org/) has a bug which makes the driver choke on GUI strings with more than 39 characters in PPD. To work around this, use either the Adobe driver (recommended) or generate the PPD files using the "-w" option on the command line of "foomatic-configure" or "foomatic-ppdfile". This cuts off the too long strings in the PPD file (which makes them sometimes difficult to understand). 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