Foomatic
--------

Grant Taylor <gtaylor@picante.com>
http://www.linuxprinting.org/foomatic.html

This is the Foomatic package.  These programs run on data from the
website www.linuxprinting.org, and allow for interesting printer
configuration things to happen.

The code here amounts to the all the configuration file generators on
the website, plus a few other experimental ones, and a basic API for
using the data.  There is no code (yet) for automagical installation
of printers or the like.

Basic features:

 - Support for CUPS, PDQ, and various strains of LPD, including LPRng.

 - Transparent support for all known styles of free software printer
   driver.

 - Support for all sorts of driver options, in all spoolers.

 - Support for PJL printer-specific options (like duplexers!), in all
   spoolers.

 - A completely data-driven design.  Data entered into the website is
   instantly visible to this software for use in all spoolers.

 - A self-documenting feature in all systems.

 - GPL licensing for this software, and "LGPL-spirit" licensing for
   the database.  See http://www.linuxprinting.org/about.html

 - A flagrant lack of comments, and an embarassing disregard for Perl
   elegance or convention.

 For a user's-eye view of the system and a bit of background, examine
 the three documentation pages and the whitepaper.  All are pointed to
 by http://www.linuxprinting.org/foomatic.html


Installation:

 The data is normally stored on your system to prevent millions of
 database hits on the central site.  To create this local cache and
 install the software, check that you like the LIBDIR suggested atop
 the Makefile and then do:

  make install

 This will copy the programs to the library directory and use wget to
 fetch the library data from the LinuxPrinting.org website.

 Note that you will also need the Perl module LWP::UserAgent
 installed; this is part of the CPAN kit libwww-perl, available from
 CPAN or with most free Unix distributions.


Code Overview:

 The code consists of one central Perl objecty module, plus two
 spooler back-end scripts, and assorted utility scripts:

  PHTDBPUB.pm

    This is the guts of the system.  Included are methods for snarfing
    data from the website, constructing configuration files for the
    various spoolers, building two (weirdly similar?!) flavors of
    documentation summary, and so forth.

  *IMPORTANT* cupsomatic and lpdomatic are mostly(tm) the same code
  after the initial option parsing stuff.  Changes *must* be made in
  both places.  Obviously, someone should figure out a mechanism to do
  this better.  I just wanted them each to be a single-file download
  for installation simplicity.

  cupsomatic

    This is a standalone script which runs as a backend filter under
    CUPS.  It accepts preprocessed Postscript from CUPS, and generates
    printer-specific data.  This will include processing
    non-postscript style options (like ints or floats, or PJL
    options).

  lpdomatic

    This is a standalone script which runs as an if= filter under
    LPD.  It supports a few different ways of getting options from the
    user, including an ugly job class hack, the -o option supported by
    VA's LPD.

  mfomatic

    This is a filter script which works together with my modified
    version of magicfilter.  This is the best thing to use to get
    Foomatic functionality with LPRng.  LPD users can use it, but will
    be unable to select option values.  See README.FIRST in the
    distribution from http://www.linuxprinting.org/download/magicfilter/

  list-printers

    This is an example script which obtains the "overview" listing of
    all printers and iterates over them, printing the possible
    make/model/driver combos.  This is uninteresting in itself, but
    the script is a nice little example.  To get further information
    about a printer/driver pair, you'd use the driver name and the
    printer's 'id' number as arguments to PHTDBPUB::getdat().

  make-datafile

    This is a program which takes options for driver and printer id,
    and prints a cups, lpd, pdq, or magicfilter configuration file
    (selected with the -t option).  See `make-datafile -h'.

 People wanting automagic generation of interesting configuration file
 subsets may implement this easily by examining make-datafile and
 list-printers and constructing a suitable hybrid Perl script.  Please
 run such things against local data files; churning on
 LinuxPrinting.org's get_data.cgi script in particular is mean.

 It is probably a bit difficult to figure out what is going on; the
 data structures are not entirely trivial, and they are not really
 declared anywhere, since this is Perl.  Fortunately, you can see what
 these structrues are by viewing various interesting URLs:

 http://www.linuxprinting.org/get_over.cgi

   This is the same as data/00-overview.foo

   This is the overview (ie, getoverview()).  It is a simple list of
   printers, grouped by make, with each having a list of drivers and a
   little bit of extra data.  I have other data not actually thrown
   in; ask if you want something else.

 http://www.linuxprinting.org/get_data.cgi?driver=foo&printer=123

   This is the same as data/foo-123.foo (which will be a symlink to
   the English-named foomatic data file for this printer and driver
   pair).

   This is the data for a printer/driver combo (ie, getdat()).  It
   contains more info about the printer and driver, plus everything
   about how to run the driver itself, including all the option
   information.  Substitute the driver name for foo and the printer's
   numeric id (aka recnum aka poid) for 123.

Dataset Versioning

 There is a rudimentary "branching" mechanism available for the data.
 I can create a branch of the database at any time (against any time
 in history; I just establish a live Postgres database from a nightly
 pg_dump'ed snapshot).  This branch gets a version "tag".

 For all editing tools (the cgi scripts under restricted/ on the
 website) you may append the CGI argument tag=foo to operate on
 branch/snapshot "foo".  Everything there works, as do get_data and
 get_over.  The normal show_printer.cgi and show_driver.cgi scripts do
 not support tagged views.

 Example: 
 http://www.linuxprinting.org/restricted/edit_printer.cgi?tag=test-1.0

 The PHTDBPUB module also supports tags properly.  If you construct a
 PHTDBPUB object using PHTDBPUB->new('tag'=>'foo') you will be
 operating on the foo branch.  This works for both web-accessed data
 (using get_over.cgi and get_data.cgi) AND for local library files
 (which will be expected to be in $libdir/data-foo).

 Branches may be edited using the web tools or my local scripts (like
 the stpdata import script) going forward, just like a branch in a
 version control system.  Unlike version controlled code, there are no
 automatic merge tools to bring branch changes forward into the
 "mainline"; this has to be done by hand.

 Branches exist to help driver authors produce driver-specific subsets
 which track multiple outstanding driver versions.  Branches might
 also be useful for distributions to track shipped software, but
 distributions should probably treat branches as read-only to avoid
 headaches from the manual merges.

Portability:

 On the www.linuxprinting.org website, the same PHTDBPUB is used, but
 some things need to come straight out of the database instead of from
 the web server (or there would just be loops!).  Thus we have:

  PHTBD.pm

    This file, not included, overrides the data accessing functions
    with methods that query my Postgres database directly.  The
    website thus uses the standard code in PHTDBPUB, but obtains the
    data directly from the database.


Contributing:

 See http://www.linuxprinting.org/contributing.html

 See the linuxprinting.foomatic.devel discussion forum at
 http://www.linuxprinting.org/newsportal/

 See the SourceForge bugtracker at http://foomatic.sourceforge.net/

 See the file TODO
