database/pprdocumentation

Contents


PPR and the OpenPrinting Database

We support PPR through the PPD-O-Matic PPD generator and companion foomatic-filters backend filter package. The filter can be used as a PPR RIP filter or as a PPR interface. What follows is quick-start information on setting up your printer with this pair, followed by some details on how it all works.


Quick Start

This is not necessarily needed if you have a Postscript printer; in that case go get a PPD from your printer's vendor, copy it into the /usr/share/ppr/PPDFiles directory, and set up the printer with one of the interfaces which came with PPR and without defining a RIP filter. You can optionally use foomatic-rip by following the steps below beginning with step 3. Then you will be able to apply options only to selected pages and you can edit the default settings in the PPD file ("*Default..." lines) and foomatic-rip will insert the default settings into the PostScript job data for you. In addition you will be able to print a documentation page then.

See also the "Postscript" driver page and the instructions on how to use PPD files.

More detailed instructions with examples and screenshots you will find in the tutorial chapter "Foomatic from the User's Point of View: Installing a Printer" (PDF). Note that the instructions in the tutorial are for the former Foomatic 2.0.x.

In case of any problems regarding the printer configuration under PPR read the documentation of PPR before posting on our Forums or on other mailing lists/newsgroups.

This system is supposed(tm) to work with PPR 1.44 or newer as a PPR interface and with PPR 1.50 or newer as a PPR RIP (recommended), other versions should also work, but we didn't test them. Check that you have this installed; see the PPR website for details on that.

1. You will need the driver that you wish to use installed (foomatic-rip and the PPD file only provide a way to connect PPR to your driver). There are several styles of driver; the ones suitable for your printer will be referenced from your printer's page in the database:
Ghostscript built-in
Ghostscript is present on most free and many commercial Unix systems. It is not part of Mac OS X as shipped by Apple. Ghostscript contains many "compiled-in" drivers.
You can see the available Ghostscript drivers on your system by running 'gs -h'. If the driver you need is not listed, you need to obtain a new Ghostscript package which includes this driver, or compile Ghostscript yourself. GPL GhostScript includes all known free software built-in drivers and Linux distributions ship it with all drivers actually compiled. Currently such drivers are not developed any more by third parties, as adding these drivers is awkward and there are plenty of interfaces for modular drivers: CUPS Raster, IJS, OpenPrinting Vector, filters, ....
CUPS Raster
CUPS has a native driver style called "CUPS Raster". These are executable programs, installed into CUPS' filter directory, which CUPS drives using a set of filters and Ghostscript. Such drivers are relatively easy to get going with CUPS, so are usually the best choice for CUPS users. With foomatic-rip one can use them also with other printing systems, though. You can see which CUPS Raster drivers are installed by examining the filters in /usr/lib/cups/filter; usually CUPS Raster drivers have names beginning with "rasterto". Each CUPS Raster driver program will also have one or more PPD files in /usr/share/ppd or /usr/share/cups/model, each containing a reference to the proper CUPS Raster program.
IJS
IJS is a plug-in interface to connect raster driver modules with Ghostscript (or a renderer in general) based on pipes. It was introduced for HP's HPIJS driver but currently it also used by several other drivers. The driver executables are usually installed into the standard search path for programs (/usr/bin or /usr/local/bin).
OpenPrinting Vector
This driver concept is developed by the Japanese members of the OpenPrinting project. It is a plugin interface for Ghostscript and other renderers which supports high-level (vector) graphics. This way modular drivers for printers with proprietary high-level page description languages can be created. Such printers are common on the Japanese market.
Filter
Some drivers are simply a filter into which generic bitmap output of Ghostscript is piped. This was one of the first solutions to make printer drivers without compiling them into Ghostscript. The filter executables are usually installed into the standard search path for programs (/usr/bin or /usr/local/bin).
Uniprint
A few drivers are Uniprint drivers. These consist simply of a upp file containing various parameters; most are included with Ghostscript. Others you will need to obtain and place in your ghostscript library directory (one of the directories listed under "Search path:" at the end of the "gs -h" output).
2. You will need a PPD for the printer driver you wish to use. To get it, look up your printer's page in the database. When you want to use the driver which is recommended for your printer, click on the "download PPD" link in the summary box at the top of the page. For other drivers and some info about the drivers, go to the driver list at the bottom of the page. If a driver has no "download PPD" link, there is no info to generate a PPD in this driver entry, see the text of the driver entry, sometimes these drivers are covered by the PPD of another driver or the PPDs come with the driver.
3. Save the PPD file in the directory /usr/share/ppr/PPDFiles (may be a different location for you, but it will be called something/PPDFiles). The PPD file does not have to be executable, but it should be world-readable.
4. Install the foomatic-filters package.

(If you are using a PostScript printer with a PPD from your printer vendor, you probably do not need Foomatic and should skip this step). Usually, your Linux distribution ships the foomatic-filters package (you have /usr/bin/foomatic-rip then). If not, get the foomatic-filters package from here. You need a C compiler and the Ghostscript shared library to build it. See the USAGE file in the foomatic-filters package for more information. The package should link /usr/bin/foomatic-rip to /usr/lib/ppr/bin/foomatic-rip and /usr/lib/ppr/interfaces/foomatic-rip. If this is not the case, set the links manually:

ln -s /usr/bin/foomatic-rip /usr/lib/ppr/bin/foomatic-rip
ln -s /usr/bin/foomatic-rip /usr/lib/ppr/interfaces/foomatic-rip

We don't recommend to put foomatic-rip directly into the PPR directories because one can also run it stand-alone, for example when you want to run the printer driver without using the spooler, so that you can find out whether a problem is caused by the spooler or by the driver. The location of the PPR base directory may differ on other installations (When installing PPR from the source code one probably gets /usr/local/lib/ppr/). Be sure that the filter is world-executable/readable (use 'chmod 755 foomatic-rip' if not).

5. If you want to be able to print a page listing all available printer and driver options for your printer/driver pair, you need one of the text-to-PostScript converters "a2ps", "enscript", "mpage" installed on your system. foomatic-rip will auto-detect them and choose one automatically. If the one automatically chosen by foomatic-rip is not the desired one, edit the "textfilter:" line in the /etc/foomatic/filter.conf file inserting the name of one of the supported converters ("a2ps", "enscript", "mpage") after the colon. Do not forget to remove the "#" in the beginning of the line.
6. Execute as an appropriately empowered administrator (usually root) the proper setup commands as found in the PPR documentation. Here are a few examples for the HP LaserJet 2200 used with the Ghostscript driver "pxlmono" as defined in the database-generated file HP-LaserJet_2200-pxlmono.ppd. We distinguish between configuration as PPR RIP, the recommended way for PPR 1.50 or newer, or as PPR interface, the only way how it works with PPR 1.4x.

Configuration as PPR RIP

ppad interface foo1 parallel /dev/lp0
ppad ppd foo1 HP-LaserJet_2200-pxlmono.ppd
ppad rip foo1 foomatic-rip x
ppad bins ppd foo1
ppop mount foo1 Tray2 letter
ppop mount foo1 Tray3 legal
This defines a print queue named 'foo1' connected to /dev/lp0 and tells PPR that tray 2 contains Letter format paper and tray 3 contains Legal format paper (so the tray is chosen automatically depending on what paper size is set in the PostScript input file).
If you do not want to have automatic paper tray selection (for example when your printer has only one paper tray), you can leave out the "ppad bins ..." and "ppop mount ..." lines, but note that when you use "ppad bins ..." you have also to use "ppop mount ...".
ppad interface foo1 tcpip laserjet:9100
...
Beginning the above command sequence with this line defines a queue for the same printer model with the same papers, but connected via an HP JetDirect interface (HP's "N" models have this built-in) or a similar print server box using the TCP/IP or Socket protocol. The hostname of the printer is "laserjet" in this example and the port is 9100.

The default option settings for the driver can be set on the "ppad rip ..." line:

ppad rip foo1 foomatic-rip x "-o Resolution=1200 -o HPLJDensity=4"

Note that this way of setting option defaults is only provided by foomatic-rip, when you use a PostScript printer with the manufacturer's PPD file or one of PPR's native GhostScript interfaces, you cannot set option defaults on the "ppad rip ..." command line.

Important: When your printer has PJL options (see the "Execution Details" page for your printer/driver combo), you must turn off the "Job break" feature using the line:

ppad jobbreak foo1 none

Otherwise some PostScript files will not be printed correctly.

Configuration as PPR Interface

ppad interface foo1 foomatic-rip /dev/lp0
ppad options foo1 backend=parallel
ppad ppd foo1 HP-LaserJet_2200-pxlmono.ppd
ppad bins ppd foo1
ppop mount foo1 Tray2 letter
ppop mount foo1 Tray3 legal
This defines a print queue named 'foo1' connected to /dev/lp0 and tells PPR that tray 2 contains Letter format paper and tray 3 contains Legal format paper (so the tray is chosen automatically depending on what paper size is set in the PostScript input file).
If you do not want to have automatic paper tray selection (for example when your printer has only one paper tray), you can leave out the "ppad bins ..." and "ppop mount ..." lines, but note that when you use "ppad bins ..." you have also to use "ppop mount ...".
ppad interface foo1 foomatic-rip laserjet:9100
ppad options foo1 backend=tcpip
...
Beginning the above command sequence with these lines defines a queue for the same printer model with the same papers, but connected via an HP JetDirect interface (HP's "N" models have this built-in) or a similar print server box using the TCP/IP or Socket protocol. The hostname of the printer is "laserjet" in this example and the port is 9100.

foomatic-rip does not provide the interface for the printer connection (parallel port, network, ...). It makes use of the already existing interfaces of PPR. The interface itself ("parallel", "serial", "tcpip", ... all in /usr/lib/ppr/interfaces/, except foomatic-rip and the GhostScript interfaces) is assigned to the queue by the "backend" option of foomatic-rip:

ppad options foo1 backend=tcpip

The address of the device is given in the syntax as the backend interface needs it, but in the "interface" command of "ppad":

ppad interface foo1 foomatic-rip laserjet:9100

This way all printer connection types supported by PPR can also be used with foomatic-rip, even interfaces which are provided by third parties.
If your interface needs options by itself, add them to the "ppad options ..." line:

ppad options foo1 backend=smb smbuser=paperwaster smbpassword=xyz123

The "ppad options ..." line can also be used to change the default option settings of the driver:

ppad options foo1 backend=tcpip Resolution=1200 HPLJDensity=4

Note that this way of setting option defaults is only provided by foomatic-rip, when you use a PostScript printer with the manufacturer's PPD file or one of PPR's native GhostScript interfaces, you cannot set option defaults on "ppad options ..." line.

Important: When your printer has PJL options (see the "Execution Details" page for your printer/driver combo), you must turn off the "Job break" feature using the line:

ppad jobbreak foo1 none

Otherwise some PostScript files will not be printed correctly.

7. To get your printouts well-centered and to be able to make use of the full imageable area (the area of the page where the printer can print, most printers cannot print up to the borders of the paper) of your printer, you should adjust the printout. With a driver made especially for your printer this is usually not necessary, but som printers, as for example PCL laser printers from other manufacturers than HP since need this adjustment since the Ghostscript PCL drivers are mainly tested on HP printers.

Download the alignment page align.ps (when you click on the link, the page will be displayed, please choose "File"|"Save As..." in your browser's menus to write the file to your disk) and print it. Follow the instructions on the page to do the adjustment.

8. If you want to print out of PPD-aware applications as Star Office, Open Office, GIMP, ... or from a client (Windows, MacOS), use the same PPD file as you already have used for setting up your printer queue and follow the appropriate instructions.


Printing with foomatic-rip

To actually use this now that you've set it up, you use the ppr(1) command; given our example setup above,

$ ppr -d foo1 -F "*PageSize Letter" -F "*Resolution 1200" /etc/motd

Would use the pxlmono driver to print on letter paper with a resolution of 1200 dpi to your HP LaserJet 2200. You do not need to specify the paper input tray. PPR selects automatically tray 2 for you, where you have the Letter paper.
Options can also be supplied only to selected pages. To make an option setting acting only on certain pages one only needs to preceed the option by a page specification separated by a colon:

PPR RIP:

$ ppr -d foo1 --ripopts '1:InputSlot=Letterhead InputSlot=Standard' file
$ ppr -d foo1 --ripopts 'even:Watermark=on odd:ColorMode=Gray' file
$ ppr -d foo1 --ripopts '1,6-10,15,20-:MediaType=YellowPaper' file

PPR interface:

$ ppr -d foo1 -i '1:InputSlot=Letterhead InputSlot=Standard' file
$ ppr -d foo1 -i 'even:Watermark=on odd:ColorMode=Gray' file
$ ppr -d foo1 -i '1,6-10,15,20-:MediaType=YellowPaper' file

The syntax is "even", "odd", or giving comma-separated page numbers or page ranges. 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.

The first lines in the examples print the first page on letter head paper and the rest on standard paper. The second lines print the even-numbered pages with watermark and the odd-numbered pages in grayscale. The third lines print the first, the 6th to the 10th, the 15th, the 20th, and all later pages on yellow paper, the rest on standard paper.

Page-specific option settings cannot be set as default in the PPD files.

With some printer/driver combos it is also possible to use arbitrary, custom page sizes (as long as they fit into the printer). Then you have a "Custom" setting for the "PageSize" option which you can use as follows:

PPR RIP:

$ ppr -d foo1 -F "*PageSize Custom" --ripopts 20x30cm file.ps

PPR interface:

$ ppr -d foo1 -F "*PageSize Custom" -i 20x30cm file.ps

You give always at first the width, then the height and in the end one of the units "pt" (PostScript points, 1/72 inch), "in" (inches), "cm" (centimeters), or "mm" (millimeters). If you leave out the unit, "pt" will be used as default. The numbers do not need to be integers, something like "4.3x5.5in" is allowed.

To see the options available for your setup, send a print job with the option '--ripopts docs' or '-i docs', like this: 'ppr -d foo1 --ripopts docs /etc/hosts'. This will make foomatic-rip print out an option summary (instead of the actual printjob; hence the file /etc/hosts; no, it can't be /dev/null).
Note that options with a user-provided integer or float value are not supported by the PPD syntax. The PPD-O-Matic PPD files replace the numerical options by enumerated options where you can choose out of between 50 and 100 equally-spaced values (including the maximum, the minimum, and the default value). Giving values which are not under these choices with the "-F" option of "ppr" will not be accepted by PPR, but you can specify them with the "--ripopts" (RIP mode) or "-i" (interface mode) option of "ppr". This way they get directly passed to foomatic-rip and so they get fully taken into account. Example: 'ppr -d foo1 --ripopts "Gamma=1.43 Density=1.14" darkimage.ps'.
For more information on using PPR and defining print queues, consult the PPR documentation.

If it doesn't work, turn on the debug flag in /etc/foomatic/filter.conf and examine the debugging output in the file /tmp/foomatic-rip.log. Do not forget to remove the "#" in the beginning of the line. And feel free to contact us for help.


How does it work?

There are three parts to the Foomatic scheme:

The Database
The database contains a number of XML files which detail exactly how to execute a given printer driver. There are two front-ends which use these files: the human-readable one generates the information shown on all "Execution Details" pages, the PPD-O-Matic PPD generator computes an Adobe-compliant PPD file which you need to configure your print queue and PPD-aware applications/clients.
The PPD File
The PPD file generated by the database contains all inforation about important printer capabilities, available options and how to build the renderer's (usually GhostScript's) command line depending on the user's choices for the options. foomatic-rip reads it to know how to execute the print job. GUI frontends read it to build dialog boxes in which the user can adjust the options. Besides the usual stuff the PPD file contains various extra lines beginning with "*Foomatic...". These contain details of the driver command line, the information whether an option accepts arbitrary numbers and not only the choices listed in the PPD file, and more. PPR and application programs ignore these extra lines.
The backend filter
The filter 'foomatic-rip' is called by PPR with various inputs, including both the PPD filename and the various options selected by the user. foomatic-rip opens the PPD, extracts all options and their possible settings and also the command line to execute GhostScript with the appropriate driver. It parses the PostScript input for option settings which were stuffed in by PPR or by application programs and it also stuffs in PostScript code by itself, if needed. It also massages the standard PPR option types into the more generic printer/driver-specific format used by the database.
Groups: