ppr - submits a file to the PostScript print spooler
ppr [switches] [filename]
This command is used to submit files to the PPR spooling system. If filename is omitted, the file is read from standard input.
For instructions for setting switchset options, see the ppad switchset and ppad group switchset options.
PPR attempts to keep track of which user submitted which job. The name of the user will be printed on any banner pages that are printed. It may also be displayed on a printer's display panel while the job is being printed. It may also be useful for printer accounting purposes as the user's name will appear in the print log if the print log is enabled.
This switch only has an effect if the user who invokes ppr is a privileged user or the -a switch is used. For this purpose a privileged user is defined as the user ``ppr'', a the user with the id 0 (``root''), or a user who is listed in ``/etc/ppr/acl/pprprox.allow''. (For compatibility older versions of PPR, members of the group ``pprprox'' are also privileged users.)
(If ppr is invoked by a non-priviledged user without the -a switch, then the -f switch is silently ignored and the name which will appear in queue listings and banner pages will be either the user name from /etc/passwd or the comment field from /etc/passwd. See the -u switch.)
If the -R for switch or the -a switch is used then the first ``%%For:'' line in the document will override the -f switch.
Prior to version 1.30 of PPR, if the first character of the -f switch argument was ``-'' then the -f switch could be overridden by a ``%%For:'' line within the document. This feature has been removed. Use the -R for or -a switch to achieve a similiar result.
If this option is true (the default) when -a is used, then the real name field from the ppuser database will be used in queue listings. For example, if the command is:
$ ppr -d aardvark -a
and the document header contains the line ``%%For: chappell'' and the real name for the ppuser account ``chappell'' is ``David Chappell'', then the cost of printing the job will be charged to ``chappell'' but ``David Chappell'' will appear in the queue listing and on the banner page. On the other hand, if the command is:
$ ppr -d aardvark -a -u yes
then the cost will be charged to ``chappell'' and ``chappell'' will appear in the queue listing and on the banner page.
If there is a charge and this switch is ommited, then the name of the account to charge to is taken from one of the following sources: the name of the Unix user who invoked ppr, the value from a -f switch, or the value from a ``%%For:'' line if the -R for or -a switch has caused it to be read. Possibilities later in this list will override those earlier in the list.
This switch is provided so that a full user name such as ``David Chappell'' may appear in the queue listing while the cost is charged to a terse user name such as ``chappell''. If a terse user name will be appearing in the queue listing then this switch is unnecessary. Below are two example command lines. In the first the --charge-to switch is used, in the second it is unnecessary because we have using the terse name in the queue listing.
$ ppr -d aardvark -f "David Chappell" --charge-to chappell
$ ppr -d aardvark -f chappell
The string usually takes the form user@host.
It might be useful to explain that the English word ``proxy'' means a person who acts as the authorized representative of another. The Unix user who runs ppr in order to submit a job for another is acting as that one's proxy. The --proxy-for option is used to record the identity of the user for whom the proxy is acting.
%%For:
''
comments override the ppr -f switch. Only in authcode mode can an
ordinary user use the -f switch or a ``%%For:
'' line in the document to
specify a user name other than the one in /etc/passwd which cooresponds
to his UID. In authcode mode PPR uses the authcode (password) provided in a
``%TCHCTAuthCode:'' comment line to verify the identity of the user.
This switch will be removed in a future version of PPR.
This switch will be removed in a future version of PPR.
After PPR accepts a print job it attempt to keep the user who submitted it informed about its progress. If something goes wrong as the job is being submitted, it may have the option of printing an error message on stderr. But, if messages to stderr will not reach the user some other method must be employed. Also, once the job has been accepted, stderr can no longer be used. The switches described in this section control how PPR sends messages to the submitting user.
Of course, sucessfully sending a method to a user requires more than selecting an appropriate response method. One must also have the user's address. By default, the address will be the username. If a particular responder requires some other kind of address, you will have to supply it using the -r switch (described below). In the description below responders which require or can accept an address other than the username are noted.
The method followme (which is the default) is not a real method at all. It instead it is a codeword for whatever method and address the user indicated by the responder address has registered using the ppr-followme command. If the user has not used ppr-followme to register a current responder, then write is used with the address unaltered.
The method write causes the message to be written to the user's terminal if he is logged in. If he is not logged it, this responder method daisy chains to the mail method. The default address is usually appropriate. If it is desired to send the message to a user other than the one who invoked ppr, the -r switch may be used to specify a user name.
The method mail causes the notification to be address is the name of the user who invoked ppr. If the desired address is not the username of the user who invokes ppr, it should be indicated with the -r switch.
The obsolete method errmail causes a response to be sent by email, however the response if discarded if it mearly indicates that the job is done. This responder is simply the mail method with a default option of ``printed=no''. This responder will be removed in a future version of PPR.
The value netsend is for use with LAN Manager X. LAN Manager X is a port of OS/2 Lan Manager 2.0 to Unix. LAN Manager's net send command is used to send the message. The name of the client to receive the message should be specified by means of the -r switch.
The method samba causes the notification to be sent by means of the messaging facilities of the LAN Manager compatible Unix server known as Samba. (See http://www.samba.org/.) The name of the client to receive the message should be specified with the -r switch. This responder accepts an option os=. The value should be obtained from Samba's %a. For instructions for setting Samba up to use PPR, see the ppr2samba.8 manpage.
The method xwin causes the notification to be sent to an X-Windows display. The display must be specified with the -r switch. This method will not work if the user ``ppr'' is not allowed to connct to the X display. The ppr-xgrant command (see the ppr-xgrant.1 manpage) can be used to grant the necessary permission. This responder uses xmessage(1), wish(1) or in a pinch xterm(1) to display the message. The message will look much neater if xmessage or wish is available. This responder has an option ``timeout=''. This parameter specifies that the message should disapear after the indicated number of seconds if the user does not dismiss it manually. The ``timeout='' option will not work if the reponder is forced to use xterm.
The method pprpopup causes the notification to be sent to the PPR popup program. PPR Popup is a Tcl/Tk script designed to be on computers in a public area such as a computer lab. The PPR popup program is primarily part of a mechanism whereby users are required to enter their names each time they print. However it can also receive responder messages.
The method audio causes a voice announcement to be made. If the address
is in the form ``smith.pc.trincoll.edu:15009'', then PPR Popup on the
indicated machine will be contacted and asked to download and play the
message. If the address begins with ``/dev/'' then it will be played through
the indicated sound device on the local machine, assuming that the user
``ppr'' has write access to that device. (Playing on a server audio device is
accomplished by invoking an operating system specific audio-play command.
See the function speach_play_many_local()
in
/usr/lib/ppr/lib/speach_play.pl to add support for your operating
system.) The responder option ``voice='' may be used to specify a set of audio
files to build the message from. The default is ``voice=male1''. Currently,
no alternate audio files exist, so this option has no practical effect.
With the exception of the methods followme and none, the -m parameter actually specifies the name of the program in /usr/lib/ppr/responders/ which should be executed to notify the user. A description of the operation of a responder program may be found in the document ``The PPR Hacker's Guide''.
These options are name=value pairs. Not all options will be supported by all responders. Responders will ignore options they do not understand. The reference section for the the -m switch describes the options understood by each responder.
If more than one --responder-options switch is used, all of their arguments will be combined to form the final set of responder options.
Common responder options include the following:
A responder will simply ignore options it does not understand.
ppr(1).)
If this option is not specified, then the value is read from the environment variable PPR_COMMENTARY. If that environment variable is not defined, then a value of 0 (which requests no commentary) is used.
The integer is the sum of certain numbers which designate the catagories of commentary desired. These values are not yet documented.
PPR is capable of printing both banner and trailer pages. Each print queue can either require, encourage, discourage, or prohibit banner and trailer pages. The user who is submitting a job may express a preference. The requirements of the queue and the user's expressed preference are used to make the descision.
The spooler will not always defer to the user. For instance, banner pages can be required on certain printers and prohibited on others. Such settings are made with the ppad flags command.
PPR is capable of generating a number of messages which describe potential problems with the contents of a PostScript print job.
The currently recognized values for string are:
Under some circumstances, PPR can identify the media (type of paper) which a document requires and select the proper paper tray.
%%BeginFeature: *PagesSize
Legal
'' comment appears in the document, then the ``legal'' medium will be
selected because it though it 8.5 by 14 inches rather than 8.5 by 11 inches
it all the other attributes of ``letter''.
Also, notice that since the -D switch sets a default, it will have no effect when the document contains a ``%%Media:'' line. Some PPR filters will emmit ``%%Media:'' lines if they are used with the ``mediatype='', ``mediacolor='', or ``mediaweight='' options.
ppad bins
series of commands.
Most PostScript printers have special features or equipment which the user may wish to employ. Two of the most common examples are extra input trays and duplex printing.
The features available for a certain printer are described in its PostScript Printer Description (PPD) file. In order for PPR to invoke printer features, it must have a copy of the correct PPD file and the PPD file must be selected using the ``ppad ppd'' command.
Begining with PPR version 1.40, a second syntax for feature names is accepted. In this syntax ``*PageSize A4'' would become ``PageSize=A4''.
The code to invoke a feature is extracted from the PPD file for the printer on which the document is printed. Since it is not possible, at the time the job is submitted, to know absolutely which printer it will be printed on, no error message will be generated if the PPD file for the printer does not contain the requested feature.
If the printer's PPD file does not contain code for the requested feature,
an ``%%IncludeFeature:
'' comment will be inserted instead, in the forlorn
hope that some mysterious piece of software between PPR and the printer
will be able to insert the code.
There is an exception to the rule stated above. If N-Up printing has been selected, PPR may attempt to synthesize missing feature code for selecting page sizes. (In other words, it will use heuristics to generate plausable code.) This is done because even if the printer can't accept a certain paper size and hence not have a command for it, the N-Up routines will be able to represent it by a rectangle on the physical page.
A feature which is commonly selected with the -F switch is duplexing:
$ ppr -d adshp4m -F '*Duplex DuplexNoTumble'
Paper input trays are another example:
$ ppr -d adshp4m -F '*InputSlot Upper'
And now for an obscure note about the -F switch. If you uses this switch to invoke a *PageSize or *Duplex option, a cooresponding option will be automatically prepended to the filter options. This is in addition to the default filter options for the queue and those that you choose with the -o switch. This prevents the filter from fighting with the rest of PPR about what the pagesize will be. It also allows the filter to change the page formatting in consideration of the fact that the output will be printed in duplex. For example, the lp filter will leave extra space in the left margin of odd numbered pages and in the right margin of even numbered pages. This makes binding the pages easier. If you don't know what this paragraph means, don't worry about it. This is just another way that PPR tries to make things easier for you by managing its default behavior to do what you would expect.
$ ppr -d myprn --features PageSize -->Letter --feature PageSize=Letter Legal --feature PageSize=Legal A4 --feature PageSize=A4 Envelope #10 --feature PageSize=Env10 PageRegion -->Letter --feature PageRegion=Letter Legal --feature PageRegion=Legal A4 --feature PageRegion=A4 Envelope #10 --feature PageRegion=Env10 InputSlot Tray 1 --feature InputSlot=Upper Tray 1 (Manual) --feature InputSlot=ManualFeed --> Tray 2 --feature InputSlot=Middle Tray 3 --feature InputSlot=Lower Tray 4 --feature InputSlot=LargeCapacity Envelope Feeder --feature InputSlot=Envelope Duplex -->Off (1-Sided) --feature Duplex=None Flip on Long Edge (Standard) --feature Duplex=DuplexNoTumble Flip on Short Edge --feature Duplex=DuplexTumble
Suppose we want to print from tray 3. From the above list we know that the proper command is:
$ ppr -d myprn --feature InputSlot=Lower
Why are the paper trays refered to in an inconsistent manner? The names on the left are the ones chosen by the printer manufacturer. There is likely a big ``3'' printed on the front of tray 3. However, the command you must use to select it uses standardized PPD file naming. Under the standardized scheme for PPD files, tray use names such as ``Upper'', ``Middle'', and ``Lower''.
The crude arrows which appear next to certain options indicate that these options are the defaults. More precisely, the arrows indicate that the PPD file says these are the defaults. It may be that someone has used the printer's control buttons to change the defaults, so don't trust them completely.
If a group is selected rather than a single printer, the options described in the PPD file belonging to the first member of the group will be displayed.
%%BeginFeature:
'' and
``%%EndFeature
'' comments is simply copied if replacement code is not found
in the PPD file. The exception is duplex code. Any duplex code which is
not defined in the PPD file is removed regardless of the setting of the
-K switch.
For example, if ppr sees this in the file:
%%BeginFeature: *Duplex DuplexNoTumble <</Duplex true /Tumble false>> setpagedevice %%EndFeature
it will conclude that the document is 'wants' to be printed in duplex mode.
PPR makes two uses of this knowledge. The first is that it uses it to coorelate the number of pages (printed sides) in the job with the number of sheets of paper that will be needed to print those pages. For example, a nine page job printed in simplex will require nine sheets of paper but in duplex it will require only five sheets. This can be important if you are charging money for use of the printers.
The second thing it does with the information is try to make sure that the job is not trying to trick it by pretending to be turning on duplex mode but really turning on simplex mode. PPR can't completely prevent this, but it can make it more difficult by inserting its own code to set the duplexer to the ostensible mode. This code is inserted at the very end of the document setup section.
Note that each of these options implies an assumption about the duplex mode or actually sets the default. This assumption or default will be used to automatically create default filter options. This is discussed more fully in the sections for the -F and -o options.
Simplex is ``soft'' in this case in that a document which includes code to invoke duplex mode but omits the cooresponding DSC comments will turn on duplex mode without PPR's knowledge. In such a case, PPR would log the consumption of more sheets of paper than were actually consumed and the user would be overcharged.
Similiarly, a document could contain this devious code:
%%BeginFeature: *Duplex DuplexNoTumble <</Duplex true /Tumble false>> setpagedevice %%EndFeature % Ha! We can change our mind! <</Duplex false /Tumble false>> setpagedevice
would fool PPR into thinking the job was going to come out in duplex when it would really come out in simplex. Thus the user would be undercharged.
Note that -n implies -R ignore-copies. If you intend the value specified with -n to be only a default, then put -R copies after -n to turn that feature back on.
Note that if the copy count is specified with -n, then -R ignore-copies is implied. If you want to set a default number of copies but to allow comments in the job to override it, then you must put -R copies after -n in order to turn this feature back on.
Some jobs have defects which can confuse PPR. The features described in this section are useful in diagnosing and dealing with such problems.
Here are the hacks currently available hacks:
If you put the -H transparent switch in a PPRParms: line of an AppleTalk queue description in papsrv.conf then you must use the line QueryFontCache: false as well. If you do not then the Macintosh client will generate code which requires font download services which are not provided in -H transparent mode.
%%BeginDocument:
'' and
``%%EndDocument
'' comments. Some programs which generate PostScript,
including many which run under MacOS ommit these. This is a serious offense
since it results in DSC comments which substantially misrepresent the
structure of the job. PPR, acting on this false information may rearange
the parts of the job incorrectly. This hack tries to deal with this
situation by relying on the fact that most EPS files end with the line
``%%EOF
''. If however, the EPS file does not end with such a line, the use of
this hack will probably make matters worse.
The file /usr/lib/ppr/editps/editps.conf contains the information PPR needs to select an editps filter. The format of this file is still in a state of flux and is not yet documented.
The option --editps-level (described below) can modify the operation of the editps hack.
The editps hack is the only one that is on by default.
The levels are roughly defined as follows:
PPR has a resource cache. A PostScript resource is a section of PostScript code which forms a font, a procedure set, an encoding map or certain other objects of general utility.
Some fonts and other resources come with PPR, with your operating system, and with other software. Fonts should be listed in PPR's font index. PPR also comes with a static cache which is found in /usr/share/ppr/cache.
PPR can also build up a dynamic cache of resources saved from previous jobs. This dynamic cache is stored in /var/spool/ppr/cache. When using papsrv and LaserWriter 8.x, this can be used to reduce the time Macintosh clients spend transmitting fonts to PPR. For this reason when papsrv invokes ppr, it sets certain options to enable caching behaviour. The options are --cache-store=uncached, --strip-cache=true, and --cache-priority=high.
%%IncludeResource:
'' comments if identically
named and version numbered resources are already in the cache or are being
copied from the job into the cache. Doing so can save disk space in the
spool area. The default value is false.
Enabling this feature could cause problems if various jobs give the same name to resources which are really different from one another. For this reason, this feature is off by default.
Many PostScript printers also have interpreters for other printer languages. PPR has the ability to spool jobs in non-PostScript langauges. However, most of the PPR options will have no effect on non-PostScript jobs.
At present, PPR does not attempt to determine if the printer it is about to send a non-PostScript job to is capable of interpreting it. A future version will consult the PPD file and turn the job away from printers which are not capable of interpreting its language.
%%Title:
'' line in document, unless
the option -R ignore-title is also used.
If this switch is ommited and a file name is specified on the ppr command line (rather than reading from stdin), the file name will be the default title. In cases where the filename is meaningless, such as when it is a temporary file created by Samba, it is advisable to use the option -C ``'' or --title ``'' to make the default a blank title.
%%Title:
'' lines in
the job. This has the effect of making a title specified with --title a
firm title rather than a default title. The default is -R title.
%%Routing:
'' line. The final routing instructions string will
appear on the ``%%Routing:
'' line which is sent to the printer and on the
banner page. This string is free-form. It is intended to contain
instructions to help an operator send the print job to the person who
printed it, but it may be used for other purposes as well.
%%Routing:
'' line from the job and, if
one is found, use its value to replace the value set with -i or
its long form, --routing. This is the default behavior.
%%Routing:
'' lines in the job. The
routing instructions message set with -i or its long form, --routing,
will be used.
%%EOF
''. The absence of a
%%EOF
comment may indicate that the job is truncated. This can be used
when accepting jobs from Macintosh computers. If the user cancels printing
before the entire job has been transmitted, this option would prevent it
from being printed. QuickDraw GX, however, ommits the %%EOF
comment, so
using this option would cause all jobs prepared by QuickDraw GX to be
discarded.
%%EOF
'' (default).
This feature might be used to require the user to fill out a job ticket or supply a username and password before the job is accepted for printing.
The path is the path of a CGI script in PPR's web interface that the user should load in order to
answer the question. An example would be cgi-bin/job_public.cgi
. PPR will send messages to the
user's responder instructing it to load this page into a web browser. These messages will be repeated
at intervals until the question is canceled with the command ppop modify
jobname question=
command. The CGI script should cancel the question once it has received a satisfactory answer. It will
then likely release the job.
The supplied path will be assembled into a complete URL, including method, host, and port as well as a query string which defines the variables jobname, magic_cookie, and title. The jobname and title should be used by the CGI script to generate text which will help the user to idenfity the job. The CGI script should store the magic_cookie in a hidden field of the form which the user uses to answer the question. That way it will be passed back in the response to the question. The CGI script should use the magic_cookie as the argument to ppop's --magic-cookie option thereby ensuring that only answers from the party to whom the question was sent have any effect.
This option is new and somewhat experimental. Currently it will only work with the pprpopup responder.
The pages to be printed should be indicated by listing their numbers separated by spaces or commas. Ranges may be indicated by using two numbers separated by a hyphen.
The order in which the pages are specified is of no importance. They will always be printed in order. Nor will specifying the same page twice have any more effect than specifying it once.
If the input file is not a PostScript file, PPR can generaly detect this. Hopefully, PPR will have a filter at its disposal which it can use to convert the job to PostScript. The switches described in this section control such filtering.
Most of the possible input types are described in the ppr-filters.1 manpage. If you run the command ppr --help | grep -- -T you will get a complete list of the supported input file types.
With version 1.32, the -T switch can also accept a MIME type as its argument. The MIME type will be automatically converted to the PPR type name. The list of known MIME types is rather short. There is presently no way to read the list of known MIME types except by examining the source code.
Note that the filter options which you supply with the -o switch are in addition to those that are supplied automatically. The full list of options is formed by combining the options implied by the -F and -R switches, the queue's default filter options and the options which you supply with one or more -o switches.
The default filter options are derived from the PPD file or files and may be seen by running ppad show, ppad group show, or ppad alias show) for printers, groups, and aliases respectively. To learn how the implied options are implied, see the sections about the -F and -R options. They do the implying.
If two name value pairs assign different values to the same name, the last one prevails. That means that filter options specified with the -o switch can override the default options and the implied options.
Options which should apply to only one filter should have the filter name and a hyphen prepended. For example:
$ ppr -d aardvark -o 'dvipsconfig=hp4 fortran-width=132 pr-width=80'
This will pass the option ``dvipsconfig=hp4'' to all filters, pass ``dvipsconfig=hp4 width=132'' to the fortran filter, and pass ``dvipsconfig=hp4 width=80'' to the pr filter.
If you find the forgoing confusing or are having trouble figuring out a problem related to filter options, you should use the --gab infile:filter option to enable debugging messages. These messages will show the implied, default, and user-supplied options and then show the final set of options passed to the filter.
The filters supplied with PPR and the options they understand are listed in the ppr-filters.1 manpage.
Basically, there are two ways of printing a marked-up file: We can print it as is, or we can pass it through a formatter to produce a typeset document. The --markup option controls which method is used. The --markup option has no effect if the input file is not contain marked-up text.
The --markup option can have the following values:
%%ProofMode:
'' line in the document. If the ProofMode is ``NotifyMe'', then
PPR will arrest the job if all of the requirements which it places on the
printer can not be met. See ``PostScript Language Reference
Manual Second Edition,'' pages 664 and 665.
If the -d switch is not use, ppr will consult the environment variable PPRDEST to determine the printer to print on. If PPRDEST is not defined, then ppr will look for the environement variable PRINTER. If PRINTER is not defined either, ppr will attempt to send the job to the destination ``default''.
If the -m switch is not used to choose a responder then the responder name will be read from the environment variable PPR_RESPONDER. If PPR_RESPONDER is not defined, then ``write'' will be used.
If the -r switch is not used to specify a responder address then the responder address will be read from the variable PPR_RESPONDER_ADDRESS. If PPR_RESPONDER_ADDRESS is undefined then the name of the user who invoked ppr will be used.
If the --responder-options switch is not used then the responder options will be read from PPR_RESPONDER_OPTIONS. If PPR_RESPONDER_OPTIONS is not defined then the option list will be empty.
Exit codes for ppr are defined in the source code file include/ppr_exits.h.
Furthur information can be found in the ppr-filters.1 manpage, the ppop.1 manpage, the ppad.8 manpage, which are part of the
PPR Reference Manual.
In addition you may wish to consult
Installing and Using PPR,
PPR, a PostScript Print Spooler,
and
The PPR Hackers Guide
PPR was written at Trinity College during 1993--2003. It was first released to the public on 26 April 1995.
David Chappell, Trinity College Computing Center, Hartford, Connecticut.
PPR has trouble dealing with documents which are printed partially in duplex and partially in simplex.
Currently, automatic bin selection can only select one media type per document.