psplpr(1) · carta

NAME

psplpr - printing frontend and filter for PostScript files

SYNOPSIS

psplpr [ -x opt-prefix ] [ --version ] [ --help ] [ --ppdpath ] [ --lpr ] [ --lp ] [ -z, --show [ all ] [ list | long ] [ constraints ] [ --verbose ] [ -q, --quiet ] [ --silent ] [ --warn ] [ --nodsc ] [ --stripdsc ] [ --stripcomments ] [ --globps ] [ --dontglobps ] [ --standard ] [ --conformant ] [ --safer ] [ --special ] [ -o, --output filename ] [ --prepend ] [ -k, --kind, --type type ] [ --dontincfeatures ] [ --dontchgfeatures ] [ --delfeatures [ totally ] ] [ -a, --dftfeatures ] [ --nodftfeatures ] [ -u, --feature keyword[=value] [ param=value ... ] ] [ spooler-options ] [ file ... ]

DESCRIPTION

psplpr is a program that acts as a frontend to the system printer spooler or as a filter for printing PostScript files on PostScript aware printers. Its main task is to preprocess input files in order to add code for accessing various printer features as described in a PostScript Printer Description (also known as PPD) file.

The program accepts the options of the available system printer spoolers. psplpr recognizes some of these options and parses them. Unknown options are passed directly to the system printer spooler. If both lpr(1) and lp(1) were available on the system when psplpr was configured, it looks in the nevironment for a PSPLPR_PRINTER, PSPLPR_LPDEST, PRINTER or LPDEST variable to determine which one to use, choosing lpr(1) by default. (But note that if the -P option of the lpr(1) spooler is used, this spooler will be automatically selected, even if it is not installed on the system.) If the system printer spooler selected by psplpr is invalid, cat(1) is used instead.

Because PPD files are mostly useful to modify PostScript files before printing them, psplpr handles the filtering options of the BSD lpr(1) printer spooler. All filters except the input filter (specified by the if capacity in the printcap file) are first run by psplpr which then works on their output, which must be PostScript code. This output must also conform to Adobe's Document Structuring Conventions (DSC). If it does not, then psplr will handle it as if the --prepend option had been used.

psplpr looks for the printer name on the command line (by looking at the printer in the -Pprinter option of lpr(1) or in the -d printer option of lp(1)) or in the PSPLPR_PRINTER, PRINTER or LPDEST environment variables if necessary (see ENVIRONMENT section below). Once the name of the printer is known it looks for the printer entry in the printcap file and extracts the ty string property which yields the type of the printer (see section PRINTCAP CAPABILITIES below). For example a printcap entry for one of the printers on the author's machine is:

    bjc600|bjc|Canon BJC-600 printer using Ghostscript:\
        :lp=/dev/lp1:\
        :sd=/var/spool/bjc600:\
        :lf=/var/spool/bjc600/logfile:\
        :af=/var/spool/bjc600/acct:\
        :if=/usr/local/lib/ghostscript/filt/gsif:\
        :df=/usr/local/bin/psdvi:\
        :ty=Canon BubbleJet Color 600:

and gives Canon BubbleJet Color 600 for the printer type. psplpr uses the given type to find a PPD file for the printer. If the ty capability is not found but the PRINTER_TYPE or PPD environment variables are set, psplpr will use their content as the printer type (or as the path of the PPD file to use if the variable value is an absolute path). If no type can be determined, psplpr will consider this an error unless a PPD file is not needed (i.e. if no option requiring looking at a PPD has been used), in which case it will simply pass its input to the system spooler if it is not given a specific type.

The type of the printer is used to look for a PPD file along the path specified by the PPDPATH environment variable, which is a list of colon-separated directories (see ENVIRONMENT section below). The PPD file will be looked in each of these directories (and the loale directories that may be found under them) under the name made by concatenating the type of the printer (with slash characters translated to percents) and the .ppd suffix. If no file is found, then other lookups will be made with different names: the second try is made after having changed all spaces to underscores in the printer type, and a third try is made after having changed all underscores to spaces. If the printer type name is less than 8 characters long, then a case-insensitive lookup with the original name will be done too. For each lookup, if the name exist in a ppd.dir file, the alternate name will be tried too. If all lookups fail, psplpr will complain about not being able to find a PPD file for the given printer type.

Once a PPD file has been found, psplpr parses it and extracts the features supported by the printer. Then it inserts the code appropriate for selected features in the input files. The resulting code is then sent to the system printer spooler.

OPTIONS

-x opt-prefix: Change psplpr option names by prefixing them with opt-prefix (which should be a single character) for short options and with opt-prefix- for long options. For example if opt-prefix is the x character then the -u and --feature options are changed to -xu and --x-feature respectively. The -x option itself is changed too. This option should not be used except if the psplpr options conflict with the ones of your system printer spooler.

--version: Print a version string on standard output and exit.

--help: Give help for calling psplpr, including usage and meaning of options.

--ppdpath: Print the path used to find PPD files and exit.

--lpr: Use the lpr(1) system printer spooler or cat(1) if it is not installed. Also get the default printer from the PRINTER environment variable.

--lp: Use the lp(1) system printer spooler or cat(1) if it is not installed. Also get the default printer from the LPDEST environment variable.

-z, --show [ all ] [ list | long ] [ constraints ]

Print the name of the PPD file used followed by a lexically sorted list of the printer features along with informations like their type and default values, then exit (all other psplpr options are ignored). If the all optional argument is not given, do not list features from sections that are not currently handled (see section CAVEATS AND BUGS below). The list looks like this:

    *BitsPerPixel
        PickOne, *BitsPerPixel=24
        16, 24, 32, 8, None
    *ManualFeed
        Boolean, *ManualFeed=False
        False, True
    *Resolution
        PickOne, *Resolution=360x360dpi
        180x180dpi, 360x360dpi, 90x90dpi

The name of the feature is indicated on the first (non indented) line. The second line gives all valid values for the feature. The third line gives the type of the feature (where PickOne means that the values are mutually exclusive and Boolean that the feature is a boolean indicator) and the default value of the feature.

If the list optional argument is given, print a list in a form that may be easily parsed, for example to build an interface for selecting features. The list gives for each feature, in that order, the name of the feature, its type, its default value, and then a list of values, one per line. The feature and values may have alternate names shown in parenthesis (in such a case the alternate name is the one that should be presented to the user). Each feature entry is terminated by a dot on a line by itself. This list looks like this:

    *BitsPerPixel (Print Depth), PickOne, 24,
        16 (16bpp)
        24 (24bpp)
        32 (32bpp)
        8 (8bpp)
        None (1bpp)
    .
    *ManualFeed (Manual Feed), Boolean, False,
        False (No)
        True (Yes)
    .
    *Resolution (Resolution), PickOne, 360x360dpi,
        180x180dpi (180dpi)
        360x360dpi (360dpi)
        90x90dpi (90dpi)
    .

If the long optional argument is given instead, print a longer list including alternate names for the options and informations about the order and precedence of the features. This long list looks like this:

    *BitsPerPixel (Print Depth)
        Type
            PickOne
        Order Dependency
            AnySetup 50
        Valid Values
            16 (16bpp)
            24 (24bpp)
            32 (32bpp)
            8 (8bpp)
            None (1bpp)
        Default
            24
    *ManualFeed (Manual Feed)
        Type
            Boolean
        Order Dependency
            AnySetup 50
        Valid Values
            False (No)
            True (Yes)
        Default
            False
    *Resolution (Resolution)
        Type
            PickOne
        Order Dependency
            AnySetup 50
        Valid Values
            180x180dpi (180dpi)
            360x360dpi (360dpi)
            90x90dpi (90dpi)
        Default
            360x360dpi

The Order Dependency heading indicates when the code for the feature should be output, and its precedence (a lower precedence means the code will be output before code with greater precedence). It is got from an *OrderDependency entry in the PPD file or from a guess. The Valid Values heading gives alternate names for the features values in parenthesis. These names are accepted by psplpr n addition to the regular names.

Except with the list option, some fields may be marked with (Unspecified) which means that the value was not given in the PPD file but rather guessed by psplpr. It is up to the user to decide whether to trust this guess or not.

If the constraints keyword is given, constraints for each feature are listed too.

--verbose: Print informations about the actions of psplpr while it does its work. The informations are printed on the standard output or on the standard error if the standard output is used to print the PostScript document.

-q, --quiet: Do not complain while producing the output. This means that warning about ignored features will not appear anymore.

--silent: Do not print anything, even warning or error messages. Also negate the effect of any previous --verbose option.

--warn: Do not exit on error but continue after issuing the error message as a warning to the user.

--nodsc: Do not put DSC comments in the output. The code will still be output, of course, but without the DSC %%Begin(End)Feature: comments. Generation of %%IncludeFeature: comments is suppressed too.

--stripdsc: Strip DSC comments so that they do not appear in the output. DSC comments are also not output by psplpr. This option is useful if the system printer spooler does have problem with DSC comments but the file was generated with such comments so that psplpr could take advantage of them. This option should not be used if later processing of the document is expected.

--stripcomments: Strip all comments so that they do not appear in the output. This option should not be used if later processing of the document is expected.

--globps: Read the entirety of a section (like the setup, or a page) before handling it and reoutputing its code. This means that if DSC comments setting or requesting features that are embedded anywhere in the section will correctly be output in the correct order at the beginning of the section, before the other code. If the input does not appear to be DSC conformant this option is automatically turned on.

--dontglobps: Prevent the automatic setting of the --globps option for input that does not appear to be DSC conformant. This option can be used to save memory (remember that the whole section, for example a page that may be several megabytes long, is stored in memory) when one knows that no features do appear anywhere in sections.

--standard: Refrain from producing DSC comments that are not part of the DSC specification. (See section DOCUMENT STRUCTURING CONVENTIONS below.)

--conformant: Do not handle non-conformant DSC comments in the document, nor do produce these comments even if the --standard option is not used. (See section DOCUMENT STRUCTURING CONVENTIONS below.)

--safer: Bracket code generated from the PPD file within code handling eventual errors.

--special: Do special treatment of some features. See section SPECIAL FEATURES HANDLING below.

-o, --output filename: Act as a filter, printing on the given file (or the standard output if filename is -) instead of piping the document to the system printer spooler.

--prepend

Prepend the code for the features to the output, after a

%!

line indicating a PostScript file. The code that is output tries to redefine the showpage PostScript procedure to setup the printer correctly before printing a page. This option may be useful when handling input that do not conform to the DSC requirements (though it may not produce correct output for features which have an *OrderDependency of PageSetup). It is strongly recommended not to use it in other cases, and it will effectively make a DSC conformant file look like a non-conformant one when used. Note that the input will still be normally processed after the code for the features have been output.

-k, --kind, --type type: Set the printer type to use, or the path of the PPD file to read if type is an absolute path to a file. This option overrides the ty capability in the printcap file if it is present.

--dontincfeatures: Do not process DSC comments %%IncludeFeature: which are normally processed by replacing the requested feature by the appropriate code for the printer.

--dontchgfeatures: Do not process DSC comments %%Begin(End)Feature: which are normally processed by replacing the actual code for the feature by the appropriate code for the printer.

--delfeatures [ totally ]: Process DSC comments %%Begin(End)Feature: by replacing them with a %%IncludeFeature: comment (thus making the resulting PostScript document portable) unless the totally optional argument is supplied or the --nodsc option is used. In addition to that, removes the %%IncludeFeature: comments if the totally optional argument is supplied. Note that this option takes effect only if the --dontchgfeatures option is used or if an unknown feature is found.

-a, --dftfeatures: Select all default printer features. This is the same as using the --feature option asking for all default features. Features that are selected with this option are overriden by features specified on the command-line. (Be warned that if you do not use the --delfeatures option your selected features may be overriden by some features already selected in a non-portable document.)

--nodftfeatures: Suppress the selection of default printer features. Useful to override the _nxfinalform printer capability on the command line.

-u, --feature keyword[=value] [ param=value ... ]

Select one of the printer features. The value is optional only for boolean features, in which case the feature is defined to be True. Case is significant in keyword and value. The keyword may be specified with or without its leading star: *MediaType and MediaType control the same feature. It is an error to specify unknown values for keyword or value and it is an error too to request features that are conflicting, as defined by the *UIConstraints: declarations in the PPD file.

If the keyword starts with *Default (or just Default) then it means to select code for the indicated default value. In this case, no value can be given. This form of feature selection is especially useful when the PPD file gives default values which do not correspond to the default printer state. Though this should not be the case, it may be used for example to choose a default transfer function.

Some features take user-defined parameters, which can be supplied in the param=value arguments, as in

    --feature *CustomPageSize Width=12cm

If a parameter is not supplied, then its minimal legal value (as specified in the PPD file) is used. Parameters of type points can be expressed as a number followed by a measurement unit specification, which can be one of in (inches), cm (centimeters), mm (millimeters) or pt (points, default measurement unit).

RETURN CODES

psplpr exits with a status code of 0 if it succeeded. In case of problem, it prints one or more error messages and, if the --warn option is not used, exit with one of the following codes:

1: The invokation of psplpr is incorrect, options are not given with the expected syntax.

2: The PPD file (even under an alternate name as explained above) cannot be located in one of the directories specified by the PPDPATH environment variable.

3: The PPD file cannot be parsed sucessfully.

4: Some features that were requested are not provided by the printer, incorrect values for existing features are specified, or correct values for different features conflict.

5: The processing of the input files (and their piping to the system printer spooler) cannot be done.

PRINTCAP CAPABILITIES

The following printcap capabilities are used by psplpr:

ty=type: The type of the printer which is used to find the corresponding PPD file (see DESCRIPTION above for the rules used to find this file). Please note that the type must not start with a leading slash or dot character.

_nxfinalform: Output for this printer should contain code for all features. Same as using the --dftfeatures option on the command line.

SPECIAL FEATURES HANDLING

First of all, if a feature has no *OrderDependency: associated with it then it will be associated to the AnySetup section with a precedence of -100.

Most features are handled by simply getting the corresponding code from the PPD file and outputing it as is, eventually enclosed by DSC comments. Some features however get a special treatment, which is explained here.

*ManualFeed and *InputSlot: These features are considered mutually exclusive, meaning that if *ManualFeed is selected then *InputSlot will be automatically undefined by psplpr.

*Transfer

After the transfer function has been set, the page is erased to make sure that the new transfer function will be used starting with the current page (which is normally empty at the point where the code inserted). If we call the transfer function code newtransfer then the code that is output is:

    newtransfer erasepage

If the --special option has been specified, the new transfer function is instead concatenated to the existing one, with code like the following example:

    [
        newtranfer /exec load
        currenttransfer /exec load
    ] cvx settransfer erasepage

*ScreenProc

If a screenproc code is specified, screenfreq and screenangle values must also be obtained from *ScreenFreq and *ScreenAngle keywords in the PPD file. The code that is output is then:

    screenfreq screenangle screenproc setscreen

DOCUMENT STRUCTURING CONVENTIONS

The following comments of the DSC are used by psplpr:

%%IncludeFeature: keyword option: If the --dontincfeatures option is not used, this comment is replaced by the code enabling the correct option of the desired feature if it is defined for the printer.

%%Begin(End)Feature: keyword option: If the --dontchgfeatures option is not used, the code corresponding to this comment is replaced by code for the printer or by an appropriate %%IncludeFeature: comment if the printer does not support the requested option for feature or feature itself. If the --delfeatures option is used, this comment and the corresponding code are either replaced by the corresponding %%IncludeFeature: comment or simply suppressed.

%%EndProlog: Indicate the end of the file prolog. Features with an *OrderDependency of Prolog will be issued before this line.

%%BeginSetup: Indicate the beginning of the document setup. Features with an *OrderDependency of DocumentSetup or AnySetup will be issued right after this line.

%%BeginPageSetup: Indicate the beginning of the setup of a specific page of the document. Features with an *OrderDependency of PageSetup will be issued right after this line for every page.

When a document is not DSC conformant, psplpr will try to guess where to issue code for the different parts of the setup. It may fail and produce an incorrect document, and it will in no case convert a non-conformant document into a conformant one.

As a special feature, psplpr will produce a small PostScript document when getting no input. This document looks like:

    %!PS-Adobe-3.0
    %%Title: Dummy PostScript Document
    %%Creator: psplpr version 1.2.2
    %%CreationDate: Sun Mar  3 23:14:21 MET 1996
    %%For: Yves Arrouye
    %%BoundingBox: 0 0 0 0
    %%Pages: 0
    %%EndComments
    %%BeginProlog
        Prolog features...
    %%EndProlog
    %%BeginSetup
        DocumentSetup features...
    %
        AnySetup features...
    %%EndSetup
    %%Page: 0 0
    %%BeginPageSetup
        PageSetup features...
    %%EndPageSetup
    %%EOF

if DSC comments are not disabled. If they are, then the features are still output in the order above, but without comments, and the first line of the output does not indicate conformance with the DSC.

psplpr extends the DSC specification with the following comment, produced unless the --standard option is used:

%%Begin(End)Param: keyword param

The PostScript code enclosed by this comment supplies the value to use for the param parameter of keyword. (Actually, the PostScript code must be a single value of the type specified by the keyword param entry in the PPD file.) Supposing that the used PPD file contains the following entries:

    *CustomPrintColors True: "
      1 dict dup /PrintColors
      3 -1 roll put setpagedevice"
    *End
    *ParamCustomPrintColors Colors: 1 int 0 15

then some code setting up the use of *CustomPrintColors may look like:

    %%BeginFeature: *CustomPrintColors True
    %%BeginParam: *ParamCustomPrintColors Colors
    7
    %%EndParam
      1 dict dup /PrintColors
      3 -1 roll put setpagedevice
    %%EndFeature

When psplpr will parse a file containing such comments, it will use them to supply the correct values to the replacement code for the printer actually used. (Note: this is not done at the moment!)

Unless the --conformant option is used, psplpr will recognize %%Begin(End)PaperSize: papersize or %%PaperSize:papersize comments and treat them as if it found %%Begin(End)Feature: *PageSize papersize or %%IncludeFeature: *PageSize papersize instead. Such comments, which are not part of the DSC, are generated and or recognized by a number of tools.

CAVEATS AND BUGS

The encoding of the PPD files is actually treated as native encoding, which means that hexadecimal substrings should be used to specify ISO Latin 1 characters on systems where this not the default.

The PPD files are not entirely parsed, and there is absolutely no guarantee that the actual parsing is correct for all the valid PPD files one can produce. Parsing fully compliant with Adobe recommendations will be added as soon as possible. (One can use the --show option to get an indication of features actually recognized by psplpr in a PPD file.)

The JCLSetup and ExitServer types of *OrderDependency are not handled. The first one should be handled by the printing system because it does not specify PostScript code. The second one may eventually be handled by psplpr by preparing a separate job to print.

The input is changed in a single pass, so psplpr is not able to enforce constraints when processing DSC comments for feature inclusion or definition.

Features with parameters are not correctly transformed because there is no way to tell which values were used for the parameters. Such features will thus get default values for their parameters.

The psplpr program is not a Document Manager (in Adobe's terminology). It simply adds PostScript code for the use of the some of the printer features but does not control its correct initialization, does not try to optimize the printer's memory or printing time, does not manage resources by itself (but instead calls includeres(1) if it can access it), etc.... Such additions would be useful but in a bigger tool.

It should be possible to use psplpr as a simple filter (with the --stdout option) in a printcap-specified print filter on a system that supports passing extraneous informations to its filters, but this has not been tested yet.

The exit status of the system printer spooler is not trapped and handed to the user in case of error. This should be done for better handling of problems.

Because the program is somewhat simplistic and may eventually output wrong code, it should provide a --secure option to bracket code it outputs in order to guarantee that the operand and dictionaries stack are not changed when setting a feature.

If you print files in formats other than PostScript, then the filters must be described in the local printcap file, and accessible on the local host. (I do not know whether this is a requirement for the system spooler too.)

On a NEXTSTEP system one should have a PRINTER variable defined even if the system does not manage printers this way. The /etc/printcap must also be synchronized when changes to the printers definitions are made in NetInfo. This can be done by deleting the file and then issuing a command like

    nidump printcap domain >>/etc/printcap

for all domain where the /printers directory is not empty.

psplpr should be able to parse filtering options for the lp(1) printer spooler and to call the appropriate filters as it does for lpr(1). (Please email the author sources for such a spooler if you want that to be taken care of.)

ENVIRONMENT

(Note: environment variables like PRINTER_TYPE and PPD with the uppercase name of the printer prepended are always preferred to the default names for this variables. For instance, the LP_PRINTER_TYPE variable will be preferred to PRINTER_TYPE for the lp printer.)

PPDPATH: Colon-separated list of directories under which to look for PPD files (locale subdirectories under these directories will be seached too). If an entry in this list is empty, it will be replaced by the default path. On a NEXTSTEP system (determined by looking for its system library directory) the default path comprises the directories ~/Library/PrinterTypes, /LocalLibrary/PrinterTypes and /NextLibrary/PrinterTypes; on other systems it comprises all share/ppd, share/postscript/ppd, share/ghostscript/ppd, lib/ppd, lib/postscript/ppd, lib/ghostscript/ppd and ppd directories found under ~, /usr/local and /usr, followed by the /lib/ppd and /lib/postscript/ppd in that order, where ~ is the home directory of the user invoking psplpr.

PPD: Older name for the PRINTER_TYPE environment variable. If this variable is kept, it should only be used to give a path to a PPD file.

PRINTER_TYPE: Default type of printer, or path to a PPD file. This will be used if the printer has no ty capability defined in its entry in the printcap file

PRINTCAP: Printer capabilities entry (not recommended) or path to the printer capabilities database. On systems with NetInfo, this variable should not be set.

PRINTCAP_NIDOMAIN: On systems with NetInfo, indicate the domain that should be queried to get the printers capabilities. Defaults to . (local domain) if unset.

PPD: Type to use when looking for a PPD file, or path to the PPD file to use. If this variable is set to a non-null value its value is used even if a ty capability exists for the printer in the printcap file.

PSPLPR_OPTIONS: Options for psplpr that are used as if they were at the start of the list of options supplied on the command line.

PRINTER: Printer name for lpr(1). It must correspond to an entry in the printcap file. If not set, defaults to lp.

PSPLPR_PRINTER: Preferred printer name for lpr(1). If set, then psplpr will set the PRINTER environment variable to its value before calling the system printer spooler.

LPDEST: Printer name for lp(1). It must correspond to an entry in the printcap file. If not set, defaults to lp.

PSPLPR_LPDEST: Preferred printer name for lp(1). If set, then psplpr will set the LPDEST environment variable to its value before calling the system printer spooler.

LINGUAS: A space-separated list of locales to be tried in order. If this variable exists, it overrides any choice made by one of the standard locale variables. (On a NEXTSTEP system, this variable is ignored, the order of languages to try being set with Preferences.)

LANGUAGE, LC_ALL, LC_MESSAGES,LANG: Preferred locale to use. These variables are read in the order given until a non-null value is found for one of them. (On a NEXTSTEP system, these variables are ignored, the preferred language being set with Preferences.)

FILES

/etc/printcap: Printer capabilities database. On systems with NetInfo, the contents of this file are supersed by the output of the nidump(8) command (see section ENVIRONMENT above).

AUTHOR

Yves Arrouye <[email protected]>

VERSION

Version 1.2.2, 3 July 1996.

HISTORY

psplpr was formerly known as plpr(1), his name having been changed to better indicate it working on PostScript files.

NOTES

PostScript is a registered trademark of Adobe Systems Incorporated.