"Fossies" - the Fresh Open Source Software Archive

Member "foomatic-filters-4.0-20160212/README" (12 Feb 2016, 17311 Bytes) of package /linux/misc/foomatic-filters-4.0-20160212.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 4.0.17_vs_4.0-20160212.

    2 Foomatic 4.0.17
    3 ===============
    6 foomatic-filters
    7 ----------------
    9 Filter scripts used by the printer spoolers to convert the incoming
   10 PostScript data into the printer's native format using a
   11 printer/driver specific, but spooler-independent PPD file.
   13 http://www.openprinting.org/
   15 This README contains mainly info for developers. See the file USAGE if
   16 you want to know how to use Foomatic.
   19 Copying
   20 -------
   22 This package is free software and can be redistributed and/or modified
   23 under the terms of the GNU General Public License; either version 2 of
   24 the License, or (at your option) any later version.
   27 Authors
   28 -------
   30 Till Kamppeter <till.kamppeter@gmail.com>
   31 Lars Uebernickel <larsuebernickel@gmx.de>
   32 Grant Taylor <gtaylor@picante.com>
   33 Helge Blischke <h.blischke@acm.org>
   36 Bugs
   37 ----
   39 If you spot a data error or any other bug, please report it on the
   40 OpenPrinting bug tracking system:
   42 http://bugs.linux-foundation.org/
   44 Choose "OpenPrinting" as the product and "foomatic-filters" as the component.
   47 Intro
   48 -----
   50 For getting Foomatic PPD files for this version, go to
   52 http://www.openprinting.org/
   54 See the README file of "foomatic-db-engine" for a (more or less)
   55 complete overview of Foomatic.
   57 User discussion happens on:
   59 http://forums.openprinting.org/list.php?34
   61 Developer mailing list:
   63 https://lists.linux-foundation.org/mailman/listinfo/printing-foomatic
   66 Supported printing systems/spoolers
   67 -----------------------------------
   69 CUPS     - Common Unix Printing System (http://www.cups.org/)
   70 SOLARIS  - Solaris LP (lpsched)
   71 LPD      - Line Printer Daemon (Does this have a home page anywhere?)
   72 LPRng    - LPR - New Generation (https://sourceforge.net/projects/lprng/)
   73 GNUlpr   - An enhanced LPD (http://sf.net/projects/lpr, development stopped)
   74 PPR      - Page PRinter spooler (http://ppr.sourceforge.net/, development
   75            stopped)
   76 PDQ      - Print, Don't Queue (http://pdq.sf.net/, development stopped)
   77 CPS      - Coherent Printing System (http://www.tww.cx/cps.php, development
   78            stopped)
   79 ---      - Direct, spooler-less printing (http://www.openprinting.org/)
   81 As most of the supported printing systems are not actively developed
   82 any more, support for them will be removed in a later version of
   83 foomatic-rip. This can even happen before 5.x. For now their support
   84 is deprecated and there were only few tests done during the
   85 development of foomatic-rip 4.x. So be prepared that there are bugs
   86 (patches welcome). Testing were mostly done with the de-facto standard
   87 CUPS and spooler-less.
   90 What is in this package?
   91 ------------------------
   93 This package contains only two programs, its man pages, and a test
   94 suite. The programs arw foomatic-rip and beh (Backend Error
   95 Handler). foomatic-rip is the main
   96 PostScript/PDF-to-printer's-native-language filter and beh is a CUPS
   97 backend wrapper for fine-tuning how a CUPS queue should behave on
   98 failure of its backend.
  100 foomatic-rip works with all spoolers and always uses PPD files for
  101 printer/driver capabilities info. Manufacturer-supplied PPDs (in most
  102 cases of of PostScript printers) can be used, too.
  104 foomatic-rip is now written in C, in contrary to Perl in Foomatic
  105 3.x. This allows foomatic-rip to link directly with
  106 libraries. foomatic-rip currently uses only the standard
  107 libraries. The functionality of the former foomatic-gswrapper is now
  108 integrated into foomatic-rip, so the foomatic-gswrapper is not needed
  109 any more.
  111 beh is still written in Perl and does not need anything else than a
  112 Perl interpreter. It is only for use with CUPS.
  114 The test/ subdirectory contains a test suite, originally developed for
  115 the distribution compliance tests of the LSB. It also serves as a
  116 regression test for further development of foomatic-rip. To execute
  117 the test, go into that directory and run "./testfoomaticrip" as root
  118 (as normal user the test series #13, CUPS queues, will not work) and
  119 you test the foomatic-rip installed on your system. You can modify the
  120 testing configuration by the variables in the beginning of the
  121 script. The test suite will not get installed with the "make install"
  122 command.
  124 The main directory contains the source code of foomatic-rip, beh, and
  125 the infrastructure for building and installing the package. It also
  126 contains the documentation.
  129 Dependencies
  130 ------------
  132 To build this package you need a C compiler, and its standard libraries.
  134 To run beh a Perl interpreter (5.6.0 and newer) is needed.
  136 To connect to remote printers in non-CUPS printing environments, you
  137 need additional connectivity software (as "rlpr", "nc", "smbspool',
  138 ...).
  141 How does it work?
  142 -----------------
  144 foomatic-rip is a filter which takes PostScript or PDF (and for
  145 non-CUPS operation also certain other formats which will get converted
  146 to PostScript) from standard input and translates it to the printer's
  147 native language. The resulting data is usually directed to standard
  148 output, but depending on the spooler abnd its configuration it can
  149 also be directed to elsewhere. The information how to do this
  150 translation it gets from a PPD file, from command line options,
  151 environment variables, and spooler configuration files.
  153 foomatic-rip does the following steps to do its work:
  156 Spooler auto-detection
  158 At first, foomatic-rip reads its command line and a certain assortment
  159 of environment variables. With this information it determines from
  160 which spooler it was called, since every spooler calls its filter(s)
  161 with different command lines and different information supplied via
  162 environment variables.
  165 Gathering all information to execute the print job
  167 Next step after figuring out what the spooler is, is collecting the
  168 information about the print job which was not found in the first
  169 step. Now the knowledge of which spooler is used is taken into account
  170 for interpreting the information.
  173 Reading the PPD file
  175 In one of the previous steps we have found the name of the PPD file
  176 assigned to the print queue currently in use. Now the PPD file is read
  177 to get all information needed to build the renderer's (Usually, the
  178 renderer is Ghostscript, when no renderer is needed, as for a
  179 PostScript printer, "cat" is used) command line, the available
  180 options, their default values, and how to apply them. After having
  181 parsed the PPD file we have a renderer command line and a list of
  182 options with the range of possible settings and a default setting. For
  183 LPRng, LPD, GNUlpr, and spooler-less printing we get also the
  184 so-called postpipe here, defining a shell command line into which
  185 foomatic-rip should direct its output. If no postpipe is found, the
  186 output data goes to standard output. The postpipe allows to print to
  187 destinations which are not directly supported by the spooler.
  190 Applying user-supplied settings
  192 All option settings which the user has supplied on the command line
  193 are checked whether they are valid (option exists, choice in range)
  194 and then applied to the list of default settings, replacing the
  195 defaults by the values given by the user. The options not mentioned on
  196 the command line keep their default values from the PPD file.
  199 Check for the "docs" option
  201 foomatic-rip accepts a special option which is not defined in the PPD
  202 file, the "docs" option. When the user supplies it, he wants to print
  203 a listing of all options available for the printer/driver combo in
  204 use. So the incoming data on standard input is discarded and a
  205 sub-process for generating the option listing in plain text form is
  206 launched. Standard input of the main process is connected to the
  207 output of the sub-process. Now the main process behaves as the option
  208 listing would be the job which the user has sent.
  211 Print files
  213 With some spoolers the jobs to be printed are supplied in files.
  214 In this case we close standard input and open the file on the
  215 standard input handler. This way the following steps read from the
  216 file instead of from standard input. The rest of the foomatic-rip
  217 process is repeated for every input file, to print them one after the
  218 other.
  221 Raw queue
  223 When we have a raw queue, all the rest of the incoming data is
  224 directly passed to standard output or to the postpipe now. The
  225 following steps will be omitted then.
  228 Print the job
  230 Jobs are usually expected to be sent in PostScript or PDF format
  231 (handling of other formats in non-CUPS environment will be shown
  232 later). PostScript is the standard format for print jobs under Unix
  233 and Linux for many years. Currently, we are on the way to move to PDF
  234 as standard format
  235 (http://www.linuxfoundation.org/en/OpenPrinting/PDF_as_Standard_Print_Job_Format).
  236 Therefore we accept both formats. In most cases Ghostscript is the
  237 renderer which understands both formats equally. So we do not convert
  238 PDF to PostScript if either the renderer command line starts with "gs
  239 ..." as then Ghostscript is the renderer and no pre-processing of
  240 incoming PostScript happens or we have a dedicated commad line
  241 prototype for PDF defined in the PPD file
  242 ("*FoomaticRIPCommandLinePDF:" keyword). In addition there must be no
  243 option at all which is implemented by inserting active PostScript code
  244 (not only comments starting with "%") into a PostScript input data
  245 stream.  If these criteria are not fulfilled, the PDF job will be
  246 converted to PostScript.
  248 After all the preparation, and if the job is PostScript the data
  249 stream is examined for traces of option settings supposed to be
  250 applied to the renderer's command line or to the JCL (Job Command
  251 Language, for example PJL) header which is sent to the printer before
  252 the renderer's output is sent.  PPD-aware applications and spoolers
  253 stuff option settings directly into the file, they do not necessarily
  254 send PPD options by the command line. There is also stuffed in
  255 PostScript code to apply option settings given by the command line of
  256 the printing command ("lpr", "lp", ...) and to set the defaults given
  257 in the PPD file.
  259 Examination strategy: We read lines from standard input until the
  260 first %%Page: comment appears and save them as @psheader. This is the
  261 page-independent header part of the PostScript file. The PostScript
  262 interpreter (renderer) must execute this part once before rendering
  263 any assortment of pages. Then pages can be printed in any arbitrary
  264 selection or order. All option settings we find here will be collected
  265 in the default option set for the RIP (Raster Image Processor,
  266 renderer) command line.
  268 Now the pages will be read and sent to the renderer, one after the
  269 other. Every page is read into memory until the %%EndPageSetup comment
  270 appears (or a certain amount of lines was read in the case that there
  271 is no %%EndPageSetup). So we can get option settings only valid for
  272 this page. If we have such settings we set them in the modified
  273 command set for this page.
  275 If the renderer is not running yet (first page) we start it with the
  276 command line built from the current modified command set and send the
  277 first page to it, in the end we leave the renderer running and keep
  278 input and output pipes open, so that it can accept further pages. If
  279 the renderer is still running from the previous page and the current
  280 modified command set is the same as the one for the previous page, we
  281 send the page. If the command set is different, we close the renderer,
  282 re-start it with the command line built from the new modified command
  283 set, send the header again, and then the page.
  285 After the last page the trailer (%%Trailer) is sent.
  287 The output pipe of this program stays open all the time so that the
  288 spooler does not assume that the job has finished when the renderer is
  289 re-started.
  291 Non DSC-conforming documents will be read until a certain line number
  292 is reached. Options for the renderer's command line or the JCL header
  293 appearing later will be ignored. This means that option settings in
  294 the page headers will not be taken into account.
  296 If options are implemented by PostScript code supposed to be stuffed
  297 into the job's PostScript data we stuff the code for all these options
  298 into our job data, So all default settings made in the PPD file (the
  299 user can have edited the PPD file to change them) are taken care of
  300 and command line options get also applied. To give priority to
  301 settings made by applications we insert the options's code in the
  302 beginnings of their respective sections, so that sommething, which is
  303 already inserted, gets executed after our code. Missing sections are
  304 automatically created. In non-DSC-conforming files we insert the
  305 option code in the beginning of the file. This is the same policy as
  306 used by the "pstops" filter of CUPS.
  308 If CUPS is the spooler, the option settings were already inserted by
  309 the "pstops" filter (both PPD defaults and user-supplied options), so
  310 we don't insert them again. The only thing we do is correcting
  311 settings of numerical options when they were set to a value not
  312 available as choice in the PPD file, As "pstops" does not support
  313 "real" numerical options, it sees these settings as an invalid choice
  314 and stays with the default setting. In this case we correct the
  315 setting in the first occurence of the option's code, as this one is
  316 the one added by CUPS, later occurences come from applications and
  317 should not be touched.
  319 If the input data is PDF then we do not search for options in the data
  320 stream nor do we try to insert settings, as this is not forseen by
  321 PDF. As told above, data in PDF format is only passed on as PDF if
  322 there are no options in the PPD file which are implemented by
  323 PostScript code to be embedded in the data stream. All options are
  324 command line or JCL options. If there are page-dependent option
  325 changes we always restart the renderer with the changed JCL and
  326 command line options. We tell the renderer by command line options
  327 which pages he has to print.
  329 If we are in a non-CUPS environment and the input is neither
  330 PostScript nor PDF (if there is no "%!" after $maxlinestopsstart
  331 lines) a file conversion filter (input format -> PostScript) will
  332 automatically be applied to the incoming data, so that we will process
  333 the resulting PostScript here. This way we have always PostScript data
  334 here and so we can apply the printer/driver features described in the
  335 PPD file. For the file conversion filter two subprocesses are started,
  336 the task of the first one is to pass the already buffered lines into
  337 the filter and then to continue reading standard input (without
  338 parsing the data) to pass the rest of the job to the filter. The
  339 second subprocess is the filter itself, getting its standard input
  340 from the first subprocess and the giving its standard output to the
  341 main process. This way the main process has again PostScript as its
  342 standard input.
  344 Supported file conversion filters are "a2ps", "enscript", "mpage",
  345 "paps", and spooler-specific filters. All filters convert plain text to
  346 PostScript, "a2ps" also other formats. The conversion filter is always
  347 used when one prints the documentation pages, as they are created
  348 as plain text, when CUPS is the spooler "pstops" is executed after
  349 the filter so that the default option settings from the PPD file and
  350 CUPS-specific options as N-up get applied. On regular printouts one
  351 gets always PostScript or PDF when CUPS is the spooler and PostScript
  352 in the case of PPR, so the filter is only used for regular printouts
  353 under LPD, LPRng, GNUlpr, PDQ, or without spooler.
  355 The main process keeps always parsing the PostScript input or feeding
  356 through the PDF input, it launches the renderer in one subprocess and
  357 launches an additional subprocess for bracketing the renderer's output
  358 with the JCL commands and putting the resulting data to standard
  359 output or to the postpipe.
  362 Overview of the subprocesses
  363 ----------------------------
  365 To do the filtering without loading the whole file into memory we work
  366 on a data stream, we read the data line by line, analyse it to decide what
  367 filters to use and start the filters if we have found out which we need.
  368 We buffer the data only as long as we didn't determine which filters to
  369 use for this piece of data and with which options.
  371 foomatic-rip splits into up to 6 parallel processes to do the whole
  372 filtering (listed in the order of the data flow):
  374    KID0: Generate documentation pages (only jobs with "docs" option)
  375    KID2: Put together already read data and current input stream for
  376          feeding into the file conversion filter (only non-PostScript
  377          and "docs" jobs)
  378    KID1: Run the file conversion filter to convert non-PostScript
  379          input into PostScript (only non-PostScript and "docs" jobs)
  380    MAIN: Prepare the job auto-detecting the spooler, reading the PPD,
  381          extracting the options from the command line, and parsing
  382          the job data itself. It analyses the job data to check
  383          whether it is PostScript and starts KID1/KID2 if not, it
  384          also stuffs PostScript code from option settings into the
  385          PostScript data stream. It starts the renderer (KID3/KID4)
  386          as soon as it knows its command line and restarts it when
  387          page-specific option settings need another command line
  388          or different JCL commands.
  389    KID3: The rendering process. In most cases Ghostscript, "cat"
  390          for native PostScript printers with their manufacturer's
  391          PPD files.
  392    KID4: Put together the JCL commands and the renderer's output
  393          and send all that either to STDOUT or pipe it into the
  394          command line defined with $postpipe.