Foomatic 4.0.13

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 README contains mainly info for developers. See the file USAGE if you want to know how to use Foomatic.

Copying

This package and also the other Foomatic packages needed to run this are under the GPL. See http://www.gnu.org/.

Bugs

If you spot a data error or any other bug, please report it on the OpenPrinting bug tracking system:

http://bugs.linux-foundation.org/

Choose "OpenPrinting" as the product and "foomatic-db-engine" as the component.

Intro

This is the stable version of Foomatic. This version is also the base of our database web interface on

http://www.openprinting.org/

New features for Foomatic 4.0.x

Added in 4.0.0:

• Support for the PDF-based printing workflow. foomatic-rip now understands both PostScript and PDF as input. PPDs are generated with two "*cupsFilter" lines now, so that CUPS knows that also PDF can get fed in. By the cost factors PDF is made the preferred input format.

• foomatic-rip is rewritten in C, so that libraries can be used without needing Perl bindings.

• Support for CUPS custom options. If a printer/driver combo has numerical, string, or password options, appropriate keywords are added to the PPD so that these options are also recognized as CUPS custom options (see http://www.cups.org/documentation.php/doc-1.4/spec-ppd.html for the CUPS PPD extension for custom options).

• PJL/JCL options in PPD files are now generated in the standard way as defined by the PPD specs. Foomatic keywords are only used if really necessary.

• Generated PPDs have now an additional "*cupsFilter:" line to tell CUPS that foomatic-rip understands PDF input (output of the "pdftopdf" CUPS filter).

• Driver XML files can now have a new "<prototype_pdf>" tag in the "" section, to supply a different command line prototype for PDF input. If left out, the same command line prototype is used for both PDF and PostScript input.

• Margins in generated PPDs now default to safer values and not to zero if no margins are specified in the XML files.

• CUPS page accounting can be suppressed on a per-driver basis now, via the tag "" and the PPD keyword "*FoomaticRIPNoPageAccounting: True".

• Added new "foomatic-ppd-to-xml" utility to generate Foomatic XML files corresponding to a given PPD file.

• Printer/driver relations now can be defined by the "" section in the driver XML file or by the "" section in the printer XML file. Before, only the former was possible.

• Added find_printer() method, to search for printers in the database. This method is especially used by the web query API for automatic driver/PPD downloads from the OpenPrinting web site. It can also be used in a local installation with the new "foomatic-searchprinter" utility.

• Added support for more detailed driver information, like license, whether it is free, whether it comes from the printer's manufacturer, support contacts, short description, by-task ratings. This gives more information to decide on downloading and installing a driver for both driver auto download and browsing the OpenPrinting web site. The information can also be used by printer setup tools using a locally installed Foomatic database. The information is available in the driver XML files (there one enters it), the PPD files, and also in the device ID strings, defined in the PPDs (so that the information goes into the output of "lpinfo -l -m" of CUPS).

New features for Foomatic 3.0.x

Added after 3.0.2:

• Support for on-the-fly PPD generation by CUPS 1.2. Now all Foomatic PPDs appear in the model lists of the CUPS web interface without needing to pre-compile the PPDs. The PPDs get actually generated if one selects them for the new print queue to be set up.

Added in 3.0.2:

• Some fixes to make foomatic-rip more robust against weird input via the command line or environment variables are done. This solves the problem of an attacker being able to run arbitrary commands as "lp" (or however the spooler's special user is named) on the print server (Security Advisory CAN-2004-0801).

• Workaround for PostScript generation bug in all OpenOffice.org 1.1.x versions.

• Let the PPD generator use the manufacturer as defined in the Foomatic database and not the one from the IEEE-1284 auto-detection ID string for the "*Manufacturer: ..." tag of the PPD files, as in the IDs the manufacturer names often do not comply with the Adobe specs (as "Hewlett-Packard", "HP" has to be used).

Added in 3.0.1:

• CUPS raster drivers can now be used with any spooler. This makes a lot of newer commercial or manufacturer-supplied printer drivers available for non-CUPS environments. To use a CUPS raster driver with a spooler other than CUPS, you need to install Ghostscript (preferrably ESP Ghostscript) with CUPS raster support, the appropriate CUPS raster driver. You do not need to install the complete CUPS package, the CUPS libraries are enough (libcups and libcupsimage, usually in the "libcups" package of your distribution) and to compile CUPS raster drivers you need also the header files of the CUPS library (libcups-devel, cupsys-dev, or similar package of your distro). Then you can set up a print queue with the PPD file of the CUPS driver the same way as if you had a native PostScript printer.

• If a printer/driver combo has Foomatic-defined JCL options and the driver already generates a JCL header, the JCL options are merged into the header produced by the driver.

• Workaround for newly introduced PostScript generation bug of OpenOffice.org 1.1.0 (OOo puts settings for whole document into "%%PageSetup" section of first page).

• Added "use strict;" to the most important Perl scripts, clean-up of the scripts (Thanks to Patrick Powell from LPRng)

• Improved LPRng support (Thanks to Patrick Powell from LPRng)

• Printer listing options and auto-selection of recommended driver for the PPD generator foomatic-ppdfile (Thanks to Patrick Powell from LPRng).

• Support for string options and additional operation modes for foomatic-addpjloptions (Thanks to Patrick Powell from LPRng).

• Additional checks in the configure scripts (Thanks to Patrick Powell from LPRng).

• Composite options can be nested now (normal and forced composite options can be mixed).

• Several modifications to make the PPD files compatible with the PostScript drivers for Windows: 100 instead of 999 choices for the "Copies" options, no "," and "+" in the "*NickName" and "*ShortNickName" entries, optional cutting of the long names of the options and choices (translation strings in the PPDs) to 39 characters for compatibility with the Microsoft PostScript driver and the original PostScript driver for Windows of CUPS. All this is not required by the Adobe specification for PPD files.

• Compatibility fixes for IRIX and the *BSD operating systems.

• Script to update the "gutenprint" driver entry in the database using the src/foomatic/foomatic-printermap file of the source tarball of Gutenprint 5.0.x.

• perltoxml() Perl function in DB.pm to generate XML database entries from PPD files (thanks to Tim Waugh from Red Hat).

• Let foomatic-ppdfile (which can be also called under the name "foomatic-datafile", for compatibility with frontends) accept and ignore the "-t" option for backwards compatibility. Now the KDE Printing Manager works correctly again.

• Fixed PPD file generation so that the files pass the "cupstestppd" of CUPS 1.1.20.

Added in 3.0.0:

• For all supported spoolers (CUPS, LPRng, LPD, GNUlpr, PPR, PDQ, CPS, no spooler) the same PostScript-to-printer's-native-language filter (RIP, Raster Image Processor), foomatic-rip is used. foomatic-rip detects automatically from which spooler it is called.

• foomatic-rip gets the info about the printer's capabilities and the driver options and default settings always from PPD files, independent which spooler is used. It is possible to use Foomatic-generated PPD files (usually for non-PostScript printers) or manufacturer- supplied PPD files of PostScript printers. So

  o PPD files of PostScript printers can be used with every spooler, not only with CUPS and PPR and on all spoolers all options will be available. So PostScript printers work always "Perfectly".

  o With the PPD file one has one configuration file for every place where information about the printer and its options is needed: The print queue itself, PPD-aware applications (as Star Office, OpenOffice.org, GIMP, ...), and clients (Windows, Mac, Unix with arbitrary spooler). The PPD format is a standard format used by every modern operating system.

• PPD building and PostScript processing is done according to the Adobe specifications DSC (Document Structuring Conventions) and PPD (PostScript Printer Description) as published on

  http://partners.adobe.com/public/developer/ps/index_specs.html

• foomatic-rip inserts all default settings from the PPD file (so you can edit the "*Default..." lines in the PPD files to set the defaults), reads option settings from the user's command line, and from the PostScript data stream. Settings in the PostScript data stream have the highest priority to assure that what one sets in an application is used. Depending on the option type the settings are applied to the renderer's (usually Ghostscript's) command line, to the JCL header, or stuffed in at the right place of the PostScript data stream.

• Support for option settings only acting on a certain page selection (example: First page on letterhead paper from tray 1, rest on plain paper from tray 2). Settings must be put into the "%%BeginPageSetup"/ "%%EndPageSetup" sections (or at least right after the "%%Page:" comments) of the appropriate pages in the PostScript input file. They can also be specified on the command line by specifying a page range before the option name (ex: "lpr -o 1,5-8:ColorMode=CMYK file.ps"). If necessary, the renderer (usually Ghostscript) is stopped and restarted in the middle of the job, when certain pages need a different command line for the renderer. The bug of Star Office/OpenOffice.org inserting the "%%BeginSetup...%%EndSetup" section after the first "%%Page:" comment is taken care of.

• foomatic-rip does neither use temporary files on the disk, nor does it need to load huge documents completely into memory. All is done in data streams where not more data than necessary is buffered. To make this possible foomatic-rip forks into up to six sub-processes.

• The installation is very easy, one needs only foomatic-rip (absolutely monolithic, no Perl modules needed), a PPD file, and optionally foomatic-gswrapper. No different files for different spoolers.

• Custom page size support with all spoolers when the PPD file has Adobe-compliant definitions for usage of custom page sizes.

• The spooler-less printing mode of foomatic-rip can be used for testing and debugging PPD files in arbitrary directories, one simply specifies them with the new "--ppd" option.

• With PDQ one can print arbitrary file types now, and even set up raw printers. The PDQ driver files are generated by foomatic-rip, so the user does not need to download more files than with other spoolers.

• Under PPR 1.50 and newer foomatic-rip runs as a PPR RIP, under older versions, as before, as a PPR interface.

• foomatic-configure sets up printer queues based on Foomatic database entries, arbitrary third-party PPDs (as shipped with PostScript printers), or raw queues.

• foomatic-configure is much faster when copying or modifying print queues now, as it does not rebuild the PPD from the Foomatic database all the time (as long as one does not force a rebuild with "-f").

• foomatic-addpjloptions works also in regular installations now, not only in "inplace" installations.

• foomatic-compiledb generates only PPD and XML files now.

• foomatic-datafile is renamed to foomatic-ppdfile, a compatibility link named foomatic-datafile is set. foomatic-ppdfile generates only PPDs, the options "-t" and "-f" are ignored.

• foomatic-configure, foomatic-printjob, and all the other scripts have the same command lines as in Foomatic 2.0. Exceptions: In foomatic-configure "--oldppd" was dropped, "--ppd" (for setting up a queue with a third-party PPD file) added, and the meaning of "-f" (force rebuild of PPD) changed.

• Option groups: Options can be put into groups and subgroups in the PPD files, so that GUIs can present them in a structured way (in tabs or in a tree structure). It is nearly completely functional, the only thing missing is translation support ("long names" for the groups, as "Adjustments and Corrections" for "Adjustment", or translations to other languages). Now the PPD generator makes trivial translations ("ThisIsAGroup" -> "This Is A Group") automatically.

• Composite options: This is a new option type to make it easier for users to choose the best settings for a certain printing task, especially if the driver has very many options. The idea is to have an enumerated choice option which does not directly modify something in the driver's command line but sets several of the other options.

  We will have a "Printout Mode" option for all printers with the following choices:

  Draft Normal High Quality Very High Quality Photo

  For an Epson Stylus Color 680 with Gutenprint it sets the options resolution, dithering, and image type as follows:

  Choice Resolution Dither ImageType

  Draft 180x180 dpi Very Fast LineArt Normal 360x360 dpi Adaptive Hybrid Photographs High Quality 720x720 dpi Adaptive Hybrid Photographs Very High Qual. 1440x720 dpi Adaptive Hybrid Photographs Photo 2880x720 dpi Even Tone Photographs

  The mentioned settings set all the color mode to "Color", there are also choices with a ".Gray" modifier (ex: "Normal.Gray" which set the color mode to "Grayscale", but the other mentioned options as the standard variants ("Normal").

  The member options of the composite option all get one choice called "FromPrintoutMode"/"Controlled by 'Printout Mode'" added, which gets their default setting. If this choice is selected, the option is set by the composite option according to the table. If the user wants to modify one of the individual member options, he simply chooses a value other than "FromPrintoutMode" for this particular option. In addition the member options will be put into a group (named "Printout Mode"). and the composite option goes into the same group as "PageSize", "InputSlot", ... So the user sees the composite option on the "Front page" of the GUI and can quickly set up print jobs without getting confused. The user with more special demands goes to the tab with the member options and makes detailed choices.

• Forced composite options: These are special composite options where the user cannot set the individual member options, but only the composite option (the user is forced to use the composite option). This allows options acting at two or more places, for example a "PageSize" option for a driver which is a filter translating Ghostscript bitmap output to the printer's language. One lets one member option be an option inserting PostScript code for the page size into the PostScript input data stream for Ghostscript, and another member option insert the correct bitmap size into the filter's command line. The user sees only the composite option and sets the paper size with it as usual.

• String and password options: These options allow the user to supply nearly arbitrary strings (a length limit and restrictions be a list of allowed characters or a Perl regular expression can be set) to the printer driver, for example names of color calibration files, fax numbers, passwords for confidential jobs, ... Frequently needed strings can be added as enumerated choices, so a frontend can show the option as a combo-box. The enumerated choices are also used for frontends which only support options as defined by the PPD spec.

• New handling of numerical options in the PPD files: "*Default: ..." now always contains one of the enumerated choices to be Adobe-compliant, the exact default value for Foomatic-aware applications is stored with the new "*FoomaticRIPDefault: ..." keywords now.

• URIs (Unified Resource Identifiers, the descriptions for the printer connection type used with the "-c" option of foomatic-configure) are exactly the same as under CUPS now. The only difference was that before for local printers always URIs beginning with "file:" were used, now "parallel:", "usb:", or "serial:" is used. The old form with "file:" is still accepted for compatibility.

• For USB printers CUPS 1.1.17 and newer supports URIs which refer to manufacturer, model, and serial number and not to the device file (/dev/usb/lp*) any more. This way the queues still work when the printers are plugged in or turned on in another order in a later session (the printers can get different device files then). Foomatic now automatically converts the conventional USB URIs to the new ones when an appropriate versions of CUPS is used. When copying a queue to another spooler the URI is converted back in the copied queue.

• Support for the MTink daemon from the MTink package (http://xwtools.automatix.de/). MTink allows monitoring the ink levels of Epson inkjets also while printing.

• Non-printable margins: Both printer and driver XML database entries should get a new section for unprintable margins, so that the "*ImageableArea" entries in the PPD files can be correctly set. Entries should be possible for printers (printer XML file), for drivers (main part of driver XML file), for printer/driver combos (in printer list of driver XML file), and they can contain general margins (valid for all paper sizes) and paper-size-specific margins. If for one "*ImageableArea" entry in a PPD file more than one of the above mentioned possible margin entries applies, the "worst case" (individually determined for each page border) is inserted. If the unprintable margins of a printer depend on options settings, the "worst case" is chosen, too.

• Facility to make a package consisting of all possible Foomatic PPD files, foomatic-rip, and foomatic-configure, see README.build-foomatic-filters-ppds for how to proceed.

• Support for inserting arbitrary constant entries (as a default resolution if there is no "Resolution" option) into the PPD file. The entries can be printer-specific, driver-specific, or printer/driver-combo-specific.

• Extended structure for auto-detection info in printer XML files: General section for entries valid for both USB and parallel port connection, possibility to insert the constant part of the original IEEE-1284 ID string. The ID string will also be inserted into the PPD file.

• Added a facility to chnage all the cryptic numerical printer IDs from the old PostGreSQL time to clear-text printer IDs. With a translation function it is assured that one can still use the old IDs, for example to not break links to the old linuxprinting.org web site.

• The Foomatic database uses clear-text printer IDs for all printers now.

Ideas for future releases:

• (Soon) Add support for all PPD extensions for the Commom Printing Dialog: http://www.linuxfoundation.org/en/OpenPrinting/CommonPrintingDialog, http://www.linuxfoundation.org/en/OpenPrinting/PPDExtensions

• Option conflicts: PPDs allow to define conflicts between option settings, so that one cannot set up things which the printer cannot do or which dont make sense (Duplex on transparencies, printing from tray 4 when only 2 trays are installed, ...).

• Printer and driver classes: The class XML files should look like printer or driver entries, with the same fields and with an additional member list. If one marks an option or an option choice as being valid for a class, it is valid for all member printers and classes, If a printer or driver is a member of a class, all fields which are left blank in this entry, are filled in with the value defined in the appropriate field of the class. If the class contains a comment text, it is shown in addition to the printer's or driver's own text. This saves from a lot of duplicate entering of data when adding printers, drivers, options, choice, option groups, or option conflicts to the database.

General features

• The XML database is fully internationalizable, For all human-readable strings translations into different languages can be added and the web query API allows localized requests with answers in the requested language. The OpenPrinting web site appears only in English currently. Not only translations can be done but there can be also different entries for the same printer driver for different regions, so that localized driver packages can get offered for automatic download.

• There is code to manipulate the XML files of the database. You can load them and get Perl data structures out of them. You can generate a printer overview list which shows all printers and for each printer which drivers make this model work and you can also generate an XML file with all information needed to use a certain printer with a certain driver, which is the basis for the PPD files which are used to configure printer queues under a spooler. These XML files can also be transformed into a Perl data structure.

• All XML handling is done by two C programs, one makes use of libxml to do a DOM parsing of all types of XML files appearing in the Foomatic system to get Perl data structures out of them, because Foomatic does all printer configuration, job manipulation, printing, and filtering with Perl scripts. The other one does XML-to-XML operations: the generation of the printer overview list, and the generation of the printer/driver combo files. These operations involve reading hundreds of files, cutting them apart and assembling them together in another way. To make this as fast as possible and also less memory-consuming, we do not use libxml, but did the parsing "manually" to keep data moving operations low.

• All configuration work, especially the generation of the PPD files is done by Perl code, because it is much easier to implemnent text manipulation operations in Perl.

• A program foomatic-configure is provided which implements complete printer configuration for the common spoolers. It is designed to support CUPS, PPR, PDQ, LPRng, LPD, GNUlpr, and direct spooler-less printing and it is designed to make it easy to write GUI or automagic printer configuration tools. It also transfers queues between different spoolers and generates Perl data structures or XML files so that frontends can build menues.

• The program foomatic-searchprinter finds printers in the local database, based on manufacturer/model search terms or the printer's device ID. This allows to make scripts which find the printer ID and suitable drivers automatically.

• Printing and managing print jobs is done by foomatic-printjob, you supply exactly the same command line options for doing the same tasks on every supported spooler.

• PJL (Printing Job Language) options can be read from the printer and added into the local Foomatic database. This allows access to many functions of the printer which are not supported by the driver, as paper tray selection, toner saving, toner density, ... This is done with foomatic-getpjloptions and foomatic-addpjloptions. Usually, PJL is only supported by PCL or PostScript laser printers.

• The PPD files serve also for PPD-aware applications as Open Office, the GIMP (Gutenprint plug-in and printers not directly supported by Gutenprint), GPR, Windows/Mac clients using their PostScript driver (and the Linux/Unix server using the Linux driver for the printer). They give access to all the driver's options in the printing dialogs of said applications. This works for all spoolers.

The upshot of all this is that you can now make changes easily and run the scripts to calculate out whatever your printer/spooler needs directly.

Programs and important files from this package

Note: The scripts appear as ".in" files in the source tree and BZR repository, because the path for the Perl interpreter/the bourne shell is inserted by the "configure" script.

configure.ac

The source from which GNU autoconf generates the "configure" script

acinclude.m4

Additional macros for the "configure" script

make_configure

Calls aclocal and autoconf to generate "configure" from "configure.ac" and "acinclude.m4"

Makefile.in

The template from which "configure" generates the Makefile

install-sh

Helper script for "configure"

foomatic-ppdfile

This program will compute the spooler-independent Foomatic PPD file for any valid printer/driver combo available in the Foomatic database, both for printing with foomatic-rip and for applications/clients being able to access the printer's options. This script serves also as on-the-fly PPD generator for CUPS 1.2.x and newer. "make install" creates a symlink named /usr/lib/cups/driver/foomatic to this script and so CUPS makes all PPDs of the local database available without the PPDs needing to exist physically. CUPS automatically calls foomatic-ppdfile if one of the PPDs is requested. This way in most printer setup tools (all which fully support CUPS 1.2.x and newer) all Foomatic PPDs are available, without explicit Foomatic support by the printer setup tool.

foomatic-configure

See USAGE for more info.

This is the great-grandady of printer configuration programs.

You can invoke this to configure a printer under any spooler with any sort of printer connection.

The printer can be either one in the Foomatic database, it can be one for which you have a PPD file (for example a PostScript printer with the PPD from the Windows driver) or a printer which you want to use without driver/filter (raw queue).

It also includes methods to summarize the current configurations, to add new queues, reconfigure existing queues, enumerate the printers known to the world, and return xml data objects describing individual printers and drivers.

It should be very straightforward to write interactive printer configuration tools around this script:

1. foomatic-configure -O prints the XML db overview on stdout
2. foomatic-configure -Q prints an XML summary of printer queues
3. foomatic-configure -X prints the XML for a database object
4. foomatic-configure with various options does the actual setup
5. foomatic-configure -P prints Perl structures for frontends
6. foomatic-configure -C copies queues, also to other spoolers
7. foomatic-configure -D sets a queue as the default queue
8. foomatic-configure -R removes a queue

foomatic-configure supports CUPS, PPR, PDQ, LPD, LPRng, GNUlpr, and direct spooler-less printing nearly completely. The program is structured with a dispatch table; for the cost of a few Perl functions it can support even more spoolers. If not told, it attempts to guess which spooler to use, or asks.

Regarding item (2), the summary of current config. It shows each queue, giving attributes for spooler, and various settings. Queues with the foomatic attribute set to zero are neither queues set up with the help of the Foomatic database nor set up with a PPD file (and foomatic-rip in case of LPRng, LPD, GNUlpr, PDQ, or no spooler). These queues cannot be modified by foomatic-configure. Trying to modify them would turn them into raw queues. The summary shows also which is the default queue, if a default queue is defined for the current spooler. The $PRINTER environment variable is not taken into account here.

For all spoolers, foomatic-configure fully groks the configuration format. It rewrites the whole thing, preserving ordering, comments, etc, and regularizing the syntax on each rewrite. So it can change entries that are clearly foomatic-rip/PPD ones, and leave others alone. Also changes of the option default settings done manually (or with GUI tools) are preserved when modifying a queue.

It is wrong to store configuration in a weird place just because foomatic is used: the user should be able to edit the config by hand the old-fashioned way...

When configuring printers, the PPD file is put into /etc/foomatic// (and if needed symlinked to from elsewhere). The PPD files are Adobe-compliant and can also be symlinked/used by applications or clients. They get a basename taken from the queue name.

For printer configuration frontends it is necessary to get all info about the queue configuration, the options, possible settings, and default settings. This info can be retrieved as a Perl data structure. The structure produced by

 foomatic-configure -q -P > testfile.pl

can be read by the following Perl script example.pl

 #!/usr/bin/perl
 my @QUEUES;

 eval (join('',(<STDIN>)));

 my $i;
 my $N = $#QUEUES + 1;
 print "$N Queues\n";
 for ($i = 0;  $i < $N; $i++) {
     my $n = $i + 1;
     print "$n : $QUEUES[$i]->{'queuedata'}{'queue'}\n";
 }

with

 cat testfile.pl | ./example.pl

Queue copying especially allows to switch between spoolers overtaking ones queues with all settings and adjustments.

foomatic-searchprinter

With this tool it is easy to find the desired printer in the database. You do not need to know the exact manufacturer and model name and how it is written in the database. foomatic-searchprinter matches what is closest to your search term. You can even use the IEEE-1284 device ID read from your printer as search term. This tool together with foomatic-configure allows to write printer setup tools for fully automatic print queue setup. Results are shown sorted by relevance and the threshold for accepting results and the amount of results to be shown is adjustable. See "foomatic-searchprinter -h" for available options.

foomatic-getpjloptions

Reads the PJL options from local (parallel, USB. serial, ...) or remote (only socket, LPD is not bi-directional) printers to standard output. They can be piped into foomatic-addpjloptions to add them to the database. Call the program without arguments for help.

foomatic-addpjloptions

Add the PJL options listed by a printer to the Foomatic database. The option list is read from a file or from standard input. The ID of the printer for which the options are has to be provided (option -p). You can add all PJL options or only the most important ones (-i). When you are adding the options from a file, you are asked whether the printer ID is correct, but you can turn this off if you want (-f). Call the program with the -h option to get help.

Note: The program needs the three files foomatic-templates/pjl*.xml

Example for making available the PJL options of the networked HP LaserJet 4050 (Foomatic ID: HP-LaserJet_4050), hostname printer6, port 9100:

Remove the "native" PJL options from the database

rm -f grep -li "pjl" db/source/opt/*.xml

Remove the options from a former PJL option poll on the same printer

rm -f foomatic-db/opt/pjl-HP-LaserJet_4050-*

Get the PJL options from the printer

foomatic-getpjloptions printer6 9100 | foomatic-addpjloptions -p HP-LaserJet_4050

Move the XML files into the database

foomatic-kitload -k foomatic-db/

Set up printer queue

foomatic-configure -n LaserJet4050 -c socket://printer6:9100/
-d pxlmono -p HP-LaserJet_4050

Instead of using "foomatic-configure" you can also generate the PPD file:

./foomatic-ppdfile -d pxlmono -p HP-LaserJet_4050 > lj4050.ppd

and set up the queue manually as described on http://www.openprinting.org/

For CUPS you can for example do:

lpadmin -p LaserJet4050 -E -v socket://printer6:9100/ -P lj4050.ppd

foomatic-kitload

This program installs a foomatic data kit into the local data library. It takes a -k option, where is the toplevel directory of a foomatic driver "kit". A "kit" is a selection of XML source files arranged exactly as in the source/ section of the master database (ie, opt/ driver/ printer/ subdirs). Gutenprint foomatic-generator produces exactly such a kit.

Foomatic-kitload is moderately paranoid about kits: the kit must contain at least one of printer/ driver/ and opt/; the kit must contain only files ending in .xml, the kit cannot be the local library itself, etc. But it does not inspect the contents of the kit files in any way.

foomatic-printjob

See USAGE for more info.

This program implements all the logic for controlling the dynamic elements of queues. In other words, jobs. It'll submit them, provide status on them, cancel them, etc. This provides an easy way for application authors to print in a spooler and driver neutral way.

foomatic-compiledb

This program will run around and generate combo data for all valid printer/driver combinations (or for selected drivers). The data is put into one directory and it is generated in a format specified by the user (PPD files or printer/driver combo XML files).

compile_db takes a -j# flag: it will run that many compute processes in parallel. You should run compile_db with a -j flag to specify how many processes to run concurrently (Gratuitous feature: you can add more processes in the middle without conflict! Just run another with -f until they all finish).

Generally, compile_db should just not be necessary except for people who want to distribute sets of configuration files. foomatic-ppdfile and especially foomatic-configure will automagically compute just what they need at runtime.

foomatic-combo-xml

The Foomatic accelaration engine written in C, it computes printer/driver combo XML files or the printer overview XML file in less then two seconds (on a crappy 128MB/350MHz machine). foomatic-compiledb needs less than three minutes for its job on a two-processor 1GB/1GHz machine. The printer/driver combo XML files are computed around 600 times faster than with the pure Perl programs of the beginning of the XML Foomatic. In addition, foomatic-combo-xml does not need more than 10 MB of memory.

The program is called by the Foomatic Perl library, but can also be called stand-alone, call the program without command line options to know how to use it.

foomatic-combo-xml does not need any XML parsing libraries, to make it faster and less memory-consuming, the XML files are somehow "manually" parsed.

foomatic-perl-data

The XML-to-Perl translator, also written in C. This program reads the XML files of the Foomatic database and translates them into Perl data structures, so that the Perl scripts can access the data.

The intention of this program is to not need the many non-standard Perl XML libraries which would make the installation of Foomatic very awkward. Now only the libxml C library is needed, a library which ships with most distributions of free operating systems. One can use either libxml 1.x (1.8.17 and newer) or 2.x, but 2.x is recommended.

Without any C helper programs the following problems appeared:

• The thing was at least an order of magnitude slower than life under Postgres and Perl was. It took hours to run compile_db, and up to some minutes (at least a few seconds) to compile one combo. The first one took more time as the option cache loaded.

• Memory: compiledb compute processes peaked at about 150MB RAM. You could turn down the number of computations per process, but it never got much below 130MB.

• Due to the slowness of the Perl XML handling an on-disk cache was used. This lead to old files from the cache being used when one changed something in the database and forgot to delete the cache.

• Many non-standard Perl libraries were needed which made the installation of Foomatic rather difficult. Now only the libxml C library is needed. This library ships with every modern distro of GNU/Linux.

foomatic-fix-xml

Run this program if you have compiled foomatic-perl-data against libxml 1.x and you have old database entries with a leading blank line. libxml 1.x chokes on leading blank lines.

foomatic-cleanupdrivers

Removes all driver entries with empty driver command lines. This way frontends do not show printer/driver combos which do not work.

foomatic-preferred-driver

Sets a recommended driver for every printer which has no recommended driver entry or has one pointing to a driver which does not exist in the local Foomatic database (for example when you have removed a driver entry from the database which belongs to a driver which is not built into your Ghostscript).

foomatic-nonumericalids

This script changes all old cryptic numerical printer IDs from the old PostGreSQL time to clear-text printer IDs in the installed Foomatic database. The current "foomatic-db" has no numerical IDs any more (this script has been applied to it), but if you use and older Foomatic database (for example to match the of your distro) you can change the IDs with this script. With a translation table it is assured that one can still use the old IDs.

foomatic-replaceoldprinterids

Replaces references to old numerical or otherwise obsolete printer IDs in arbitrary files. By default it uses the db/oldprinterids file of the current Foomatic database as translation table, but you can use arbitrary translation tables. You can also give regular expressions (Perl) for the text surrounding the IDs. Do "foomatic-replaceoldprinterids -h" to know how to use it.

foomatic-ppd-to-xml

Generates a printer XML file from a given PPD file. This is for example used to make database entries for printers for which there is a manufacturer-supplied PPD file.

foomatic-printermap-to-gutenprint-xml

Updates the driver XML file for the Gutenprint driver to the state of the foomatic-printermap file in the Gutenprint source tree. Used to update the driver XML file for Gutenprint in the OpenPrinting database.

foomatic-ppd-options

Lists the options in a PPD file one the screen.

Filters

To be able to print with the PPD files and queues made with the stuff in this package, you need only the foomatic-rip filter provided by the "foomatic-filters" package.

foomatic-rip

See the documentation of the "foomatic-filters" package for more info.

This is a universal print filter which works with all printer spoolers auto-detecting the spooler from which it is called. Its job is to translate the incoming data (PostScript or PDF in most cases) to the printer's native language taking into account all option settings, either defaults or job-specific ones. It reads the PPD file assigned to the print queue, either a Foomatic-generated one or a manufacturer-supplied PPD file of a PostScript printer, uses the information to find the default option settings and to build the renderer's (usually Ghostscript, "cat" for PostScript printers) command line, and applies the user-supplied options. Then it builds the renderer's command line and passes the data through it. If the data is not PostScript or PDF, a pre-filter ("a2ps", "enscript", "mpage", ...) is added.

About the database

The database is provided by the "foomatic-db" package, additional database entries are in "foomatic-db-nonfree", drivers can also supply Foomatic XML files. "foomatic-db" is required for using the programs provided by this package.

There is a $libdir, somewhere (usually /usr/share/foomatic/). Underneath $libdir there are (Install "foomatic-db" at first and then this package. Then the $libdir will be auto-detected):

db/ - the database db/oldprinterids - translation table for old numerical printer IDs and for printer IDs which go changed db/kitload.log - list of third-party "kit" files, logged by foomatic-kitload db/source/ - "source" data, provided by humans, etc db/source/printer/.xml - printer-specific data, one per printer id db/source/driver/.xml - driver-specific data, one per driver name db/source/opt/.xml - option data, one file per option db/source/PPD/ - Ready-made PPD files, usually supplied by printer manufacturers for their PostScript printers.

You can edit the files whenever you want and regenerate the affected printer queues with foomatic-configure, there is no on-disk cache, the data is always directly derived from the source files. So your changes will be taken into account without any special steps.

Foomatic::DB API

This API isn't required, now that the data is an an easy-to-process format (nevermind the foomatic-configure language independent "API") for heathen users of non-Perl languages, but even for such dogs it's instructive to poke at how certain things are done:

get_driverlist get_printerlist get_printers_for_driver get_drivers_for_printer

These all return lists of printer id's or driver names. The get_foo_for_bar methods accept a printer id or driver name as appropriate; the frst two just return all and take no arguments.

get_overview get_overview_xml

This returns an overview listing of all printers, with ids, makes, models, functionaliy, drivers, etc. The various flavors return a Perl data structure or XML.

get_makes get_models_by_make

These return makes and models lists.

get_javascript2

This returns a JavaScript function that accepts two widget element names. If the first one is set to a value that euqals a known make, then the second one's choices are replaced with a set of models valued with printer IDs. We use this to make a "nested menu" out of two menu controls on a web page.

get_printer_from_make_model

This returns a printer id from a make and model

normalize normalizename

These are used for sorts to sort printer model names properly and also to do searches for printer models/IDs. normalize makes the input string all lower-case, turns a '+' tp 'plus', and removes all non-alphanumeric characters. normalizename turns all groups of digits to a zero-padded fixed-length number, so that printers with the same product line name (like "LaserJet") and different model numbers appear in correct numerical order. In addition, normalizename also applies normalize.

get_combo_data_xml

This returns the combined printer/driver data for a particular combination. Arguments are driver and printer id.

The "combo" operation is less trival than it looks; be careful when messing with it. It took us hours to get right... Currently, it is implemented in the foomatic-combo-xml.c C accelerator.

get_printer_xml get_printer get_driver_xml get_driver

These return the information in the printer info or driver info database files. The *_xml functions produce XML, the others Perl data structures.

find_printer

This function returns Foomatic printer IDs to match a given search term. The search term can be manufacturer and model, separated by a space or a '|', an IEEE-1284 device ID of a printer, manufacturer, model, Foomatic printer ID, or parts of any of the mentioned items.

getdat

This returns a Perl data structure of all the data for a given printer/driver combo. It contains a description of printer capabilities, all options, choices, and ranges valid for this particular combo. It is used to build the PPD files, but can also be used by Perl frontends. It takes driver and printer ID arguments; just like get_combo_data_xml

getppd

This returns the spooler-independent PPD file for foomatic-rip and for applications and clients. It takes no arguments; instead you must call getdat first, and they'll then magically find that result.

getdocs getexecdocs get_summarydocs

For some reason there are three functions which return documentation about job options for particular printer/driver pairs. There's also a fourth one inside foomatic-rip (invoked by the "docs" option).

These work the same way as getppd; you call getdat first.

Once, these worked if you called getdat with only a driver; in that case it sort of documented it for all printers at once. This is sort of incomplete, especially what with PJL arguments in the world. Grant also probably broke it in the xml rewrite. Till has rewritten getexecdocs to produce documentation for a given printer driver pair, it provides the data presented on the "Execution Details" pages of OpenPrinting.

get_libdir

Returns the library directory.

Dependencies

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") packages. It is recommended to install these packages before you install this package. Then the paths to their components get auto-detected during the build of this package.

"wget" (from www.gnu.org) is really a standard tool which nearly every distribution includes.

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.

The versions 1.8.17 and 2.4.19 of libxml are tested, 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).

Using libxml 2.x is highly recommended.

You need libxml 2.x, aclocal (in the "automake" package in some distros), and autoconf when you want to compile Foomatic from the BZR repository.

See the USAGE file for compilation details.

Data

There are three main source datafiles (printers, drivers, and options; annotated examples:

printer/HP-LaserJet_4000.xml

The printer file contains information specific to a particular

printer.

<laser />

<!--not "color"-->
<resolution>

  <dpi>
    <x>1200</x>
    <y>1200</y>
  </dpi>
</resolution>

<consumables>

  <comments>
    <en>toner</en>
  </comments>

  <!--one or more "partno" elements.-->
</consumables>

<!--no known parport probe information-->

<i>1200x1200 dpi only possible with Windows drivers,
600x600 can be reached w/o particular software.
The difference is visible, but only slightly, so
the Functionality got "Mostly"<p></i><p>

Do the following:<p>

Set the resolution on the front panel to "Prores 1200", not
to "Fastres 1200". When you use CUPS with HPs PPD file, turn
off "Fastres 1200" in the printer configuration
options.<p>

Try the generic PostScript PPD file which comes with KUPS 1.0 or newer.
</en>

<ev_driverval>612 792</ev_driverval>

<constraints>
 <constraint sense="true">
  <driver>ml85p</driver>
  <arg_defval>na</arg_defval>
 </constraint>
 <constraint sense="true">
  <make>HP</make>
  <model>DeskJet 1000C</model>
  <driver>pnm2ppa</driver>
  <arg_defval>na</arg_defval>
 </constraint>
 <constraint sense="false">
  <make>HP</make>
  <model>DeskJet 820C</model>
  <driver>pnm2ppa</driver>
  <arg_defval>na</arg_defval>
 </constraint>

 # lots more...

</constraints>

...

</enum_vals>

o PageSize
o InputSlot
o MediaType
o InkType
o Duplex
o PrintoutMode
o Resolution
o REt
o Dither
o FastRes
o Economode
o ...

o Resolution
o REt
o Dither
o FastRes
o Economode
o ...

o Gamma
o Brightness
o Contrast
o Density
o Saturation
o Cyan
o Magenta
o Yellow
o ...

o Stapling
o Binding
o Cutting
o Booklet
o ...