NAME

ppr - submits a file to the PostScript print spooler


SYNOPSIS

ppr [switches] [filename]


DESCRIPTION

This command is used to submit files to the PPR spooling system. If filename is omitted, the file is read from standard input.

Informative Switches

--version
print the PPR version information.

--help
print help.

Designating the Destination

-d destname
selects the printer or group of printers to print on. See also the section ``ENVIRONMENT''.

-I
This option is obsolete in PPR version 1.40 and later. It was formerly used to insert the options from the queue's switchset at the point it appeared in the command line. Starting in version 1.40 the switchset options are always parsed before the options on the command line.

For instructions for setting switchset options, see the ppad switchset and ppad group switchset options.

User Identification

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.

-f string
specifies the name of the user for whom the job is to be printed. This name will appear on banner pages and in queue listings.

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.

-R for
-R ignore-for
A privileged user (as defined for the -f switch) may use -R for to instruct PPR to use the information in ``%%For:'' lines in the document to determine who the job is being printed for. The information in the ``%%For:'' line will override any information specified by a -f switch.

-u [yes, no]
controls whether the username or the real name is used to identify jobs in the queue listings and on banner pages. The default is -u no, thus the real name is used. The -u yes option causes the Unix user name to be used instead.

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.

--charge-to string
indicates the account to which the cost of printing the job should be charged. The charge accounts are managed with the utility ppuser. If there is no charge for printing on the selected printer, then this switch will have no effect.

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

-X string
--proxy-for string
With this switch, you can provide a string which identifies a user (possibly on a remote machine) for which the submitting user is acting as proxy. This string will be stored with the job. You can later use the --proxy-for switch with the same identifier string with ppop when deleting or performing subsequent operations on the job. If you supply a different string to ppop, it will refuse to carry out the operation. This feature is mainly used by servers such as Samba and lprsrv which accept jobs over the network.

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.

-a
This switch turns on authcode mode. In authcode mode, document ``%%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.

-A
indicates that a priviledged user (as defined for the -f switch) has pre-authorized the job. This switch should be used in conjunction with the -f switch or the --charge-to switch. Currently, the -A switch is used only by papsrv. The switches -a and -A are mutually exclusive.

This switch will be removed in a future version of PPR.

Feedback to the User

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.

-m method
--responder method
Specifies the method which should be used to send responses to the user who submitted the job. Available methods include, write, samba, and xwin. The default is read from the environment variable PPR_RESPONDER if it is defined, otherwise the default is followme.

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''.

-r address
--responder-address address
Specifies the address which is to be passed to the responder program. The default value is read from the environment variable PPR_RESPONDER_ADDRESS if it is defined, otherwise the default is the name of the user who invoked ppr, which is appropriate for the default responder which is followme. The exact correct format for this parameter depends, of course, on the responder that is being used.

--responder-options list
This switch specifies the list of options to be passed to the responder. The default value is read from the environment variable PPR_RESPONDER_OPTIONS if it defined, otherwise the default is an empty option list.

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:

printed=no
This option instructs the responder to do nothing when the message is that the job has been printed. This is supported by most of the responders.

canceled=no
This option instructs the responder to do nothing if the message indicates that the job was canceled. This is supported by most of the responder.

timeout=seconds
This option instructs the responder to remove its message after the indicated number of seconds. Currently this is supported only by the xwin responder and then only when xmessage is available.

A responder will simply ignore options it does not understand.

-e none
Don't user stderr or responder to report errors which occur at the time the job is submitted. (Report errors only by means of the exit code of ppr(1).)

-e stderr
Report errors on stderr if they occur at the time the job is submitted. This is the default.

-e responder
Report job submission errors by responder if the responder is not set to ``none''.

-e both
Report job submission errors with both stderr and responder.

-e hexdump
Always try to force the banner page on and print a one page hex dump when no filter is available to convert the input file to PostScript.

-e dishexdump (being phased out)
-e no-hexdump
Discourage the use of a hex dump as described above. This is the default. Hex dump will be used only as a last resort, when -e none has been used or -e responder has been used and -m none has been used as well. In other words, it will only be used when there is no other way to report the problem.

--commentary integer
This option indicates that, while this job is being printed, the responder should be used to send commentary on the printer's behavior. The commentary will be limited to those categories respresented by the integer.

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.

Banner and Trailer Pages

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.

-b [yes, no, dontcare]
Specifies the user's preference as to whether or not a banner page is printed. The default is ``dontcare''.

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.

-t [yes, no, dontcare]
This parameter indicates the user's preference as to trailer pages. The default is dontcare. As with banner pages, this option is a statement of preference, not an order. The spooler will ultimately make its own decision, possibly taking the user's stated preference into account.

Diagnostic Messages

PPR is capable of generating a number of messages which describe potential problems with the contents of a PostScript print job.

-w [log, stderr]
indicates where warning messages about irregularities in the input file should be displayed. By default, they are displayed on stderr, but if you use the switch -w log, they are placed in the print job's log file and will appear on the banner page if one is printed. A print job's log file may be displayed with the command ppop log jobname.

-w [severe, peeve, none]
sets the warning level. Warnings indicate erroneous or suspicious features of the input file, especially its Document Structuring Convention comments. If the warning level is set to none, no warnings are issued. If it is set to peeve, every possible warning is issued. If it is set to severe (the default), warnings are issued only when the error is one PPR probably cannot correct.

-G string
--gab string
This switch will cause PPR to print out various helpful information as it runs. It is primarily intended as an aid in tracking down problems.

The currently recognized values for string are:

infile:autotype
This will display information about automatic file type detection process.

infile:filter
This will display the name of of each filter that is run on the input file as well as the arguments which are passed to the filter.

infile:editps
This will displays information about the actions enabled by the -H editps option.

structure:nesting
This will displays information about nestable Document Structuring Convention structures such as procedure sets, files, and documents.

structure:sections
This will cause ppr to print as it enters each section of a Document Structuring Convention compliant document.

media:matching
This will cause ppr to print messages as it attemps to find matches for the document's media requirements in the media database. (The media database is a list of possible paper sizes and their names. It is manipulated with the ppad media commands.)

Media and Bin Selection

Under some circumstances, PPR can identify the media (type of paper) which a document requires and select the proper paper tray.

-D mediumname
sets the default medium. The default medium is used to print documents which do not specify what media they require. This is really a default default since certain comments in the document may be used the modify the ``default'', resulting in the selection of a different medium. For example, if the -D letter switch is used but a ``%%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.

-B boolean
-B true enables and -B false disables automatic bin selection. By default, automatic bin selection is enabled. Automatic bin selection will only work if bins are defined for the printer. Bins are defined with the ppad bins series of commands.

Selecting Printer Features

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.

-F ``feature name''
--feature ``feature name''
This option inserts PostScript setup code for printer features. Since feature names, such as ``*PageSize A4'' contain asterisks and spaces, they should be quoted to get them through the Unix shell.

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.

--ripopts list
This option takes a space separated list of options for an external RIP. If no external RIP is being used, this will have no effect. This option exists in order to support certain features of Foomatic as a RIP. See <http://www.linuxprinting.org> to learn about Foomatic.

--features
If you use this option, ppr won't accept a job for printing. Rather it will list all of the printer features in the selected printer's PPD file. It will also list the -F or --feature options needed to select them. For example:
        $ 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.

-K true
If this option is selected, code between ``%%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.

-K false
Don't keep feature code not in PPD file. This is the default. It is generally assumed that if the feature is not described in the PPD file it does not exist in the printer in question. That being so, attempting to invoke it could result in an error.

-R duplex:
The -R duplex: family of options controls the mechanism which PPR uses to determine if an incoming was intended to be printed in duplex mode or simplex mode and if in duplex mode, which variant of duplex mode. It does this by looking for DSC comments which mark the PostScript code that controls duplexing or which request the insertion of such code.

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.

-R duplex:softsimplex
This is the default. In this mode, ppr reads the comments and takes note of the duplex mode, but it trusts the job to set the duplex mode to the what it says it is setting it to. Using this mode while charging for printing is not recomended since overcharging is likely and cheating is less difficult.

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.

-R duplex:simplex
Look for duplexing comments, but if none are found, assume that simplex printing is intended and turn duplexing off. on.

-R duplex:duplex
Look for duplexing comments, but if none are found, assume that duplexing (specifically the no-tumble or long-edge variant) is intended and turn it on.

-R duplex:duplextumble
Look for duplexing comments, but if none are found, assume that duplexing (specifically the tumble or short-edge variant) is intended and turn it on.

-R ignore-duplex
Ignore the possibility of duplex mode. No comments will be examined, and unless there is an -F *Duplex option on the command line that turns on duplex mode, ppr will assume that the job will naturally be printed in simplex mode and charge accordingly.

Number of Copies

-n integer
--copies integer
Print the specified number of copies. PPR may or may not use the printer's multple copies feature.

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.

-n collate
--copies collate
Using this option requires PPR to print collated copies, i.e. 1,2,3,1,2,3,1,2,3 rather than 1,1,1,2,2,2,3,3,3. Note that for input files with certain characteristics PPR will print collated copies whether or not you use this option.

-R copies
-R ignore-copies
If -R copies is in effect, PPR will read any copy count which appears in a document ``%%Requirements:'' comment and print that many copies. The default is -R copies.

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.

Troublesome Jobs

Some jobs have defects which can confuse PPR. The features described in this section are useful in diagnosing and dealing with such problems.

-H hack_name
--hack hack_name
This switch enables or disables certain features known as ``hacks''. These hacks are generally of dubious value and can in certain cases be harmful. All but -H editps are off by default. Using the -H switch with a hack name as its argument turns on the hack. Using the -H switch with ``no-'' immediatly followed by the hack name reverses an -H switch earlier in the line which turned it on.

Here are the hacks currently available hacks:

keepinfile
This hack causes ppr to store and keep a copy of the origional input file for as long as the job remains in the queue. Normally ppr stores only a highly processed version of the input file. The purpose of this feature is to allow a troubleshooter to examine the origional input in cases where it would have otherwise been lost, such as a job received over a network connexion. The file is stored in the jobs directory along with the files which make up the processed job. The file's name is the full job id with ``-infile'' appended to it. Note that the input file is stored before it has been run through any filters so the stored file may not be a PostScript file.

transparent
This hack implies keepinfile. When this hack is enabled, rather than re-assembling the file from the processed queue files and sending it to the printer, PPR simply copies the saved input file to the printer. Using this hack largely defeates the purpose of using PPR since none of the advanced features will work. This hack is provided for testing purposes since a job which PPR mangles may print correctly with this hack. However, since automatic input type conversion, protocol conversion, printer feature code insertion, and font downloading will by bypassed, using this hack with jobs which print correctly may cause them to print incorrectly or not at all.

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.

badeps
When an Encapsulated PostScript file is included in a larger PostScript document, it should be bracketed by ``%%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.

editps
This hack comes into play when the input file is in PostScript format. Some applications which generate PostScript make serious errors. Sometimes these errors need to be corrected before PPR can correctly parse the file. Using this hack instructs PPR to invoke an appropriate correction filter, if it has one.

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.

--editps-level n
This option controls the degree of modification performed by the -H editps option. The number n must be between 1 and 10 inclusive. The default is 1. Each editps filter described in editps.conf has a minimum level defined. The filter will be considered usable only if the level set with --editps-level is at least as high as the minimum level for the filter.

The levels are roughly defined as follows:

  1. Only enough editing is done to ensure that any file which would print if simply transmitted unmodified to the printer will print through PPR. This editing may include inserting a ``%%PageOrder: Special'' comment or the adjustment of the position of the ``%%Trailer'' comment but it will not do major editing.

  2. At this level, procedure definitions may be moved out of the script and into the prolog in order to achieve page indenpendence.

  3. At this level, the PostScript code will be subjected to close scrutiny in order to abtain information to place in additional DSC comments. This might be done in order to identify jobs or portions of jobs that require a color printer.

  4. At this level, the filter has an intimate knowledge of the generated code and performs major modifications such as optimizing it for size or speed.

Resource Handling

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.

--cache-store [none, unavailable, uncached]
This directive controls which resources found in the submitted job are saved in the resource cache. If it is set to uncached, then all resources (or rather resources of all categories for which there is a cache directory in /var/spool/ppr/cache) which are not already in the cache are saved in the cache. If it is set to unavailable then the resource is saved only if it doesn't exist elsewhere such as in the font index. If it is set to none then no resources are added to the cache (with the minor exception of of those Macintosh dual mode fonts which are already partially cached).

--strip-cache [true, false]
-S [true, false]
This option controls whether when the job is placed in the queue, PPR will strip out PostScript resources such as fonts and procedure sets and temporarily replace them with ``%%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.

--strip-fontindex [true, false]
The default for this option is false. If this is option is set to true and a font which is sent as part of the job is listed in the font index, then it is stripped out and later replaced with the one listed in the font index.

--strip-printer [true, false]
The default for this option is false. If this option is set to true and a resource, such as a font, which is sent as part of the job is already in the printer, it is stripped out just before the job is sent to the printer.

--cache-priority [auto, low, high]
This directive determines where PPR looks first when it is asked to insert a resource or when it replaces one it stripped out. The default is auto. If the setting is high then the resource cache will be searched before the font index. If it is low then the resource cache will be searched after the font index. If it is auto then the priority will be set to low,unless one or more resources were stripped out of the job with the expectation of restoring them from the cache, in which case it will be high.

Other Printer Languages

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.

--passthru list
This experimental option has been removed. See ppad passthru and ppad group passthru for the replacement.

Miscelaineous

-C string
--title string
These options both do the same thing. They specify a default document title. The default title can be overridden by ``%%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.

-R ignore-title
-R title
The option -R ignore-title causes ppr to ignore ``%%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.

--lpq-filename
Specifies the name of the origional input file. This switch is used by lprsrv because otherwise ppr would not know what the file's name was on the origionating node.

-i string
--routing string
Specifies an routing instructions string. This string will override any found on a ``%%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.

-R routing
This option instructs PPR to read ``%%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.

-R ignore-routing
This option instructs PPR to ignore ``%%Routing:'' lines in the job. The routing instructions message set with -i or its long form, --routing, will be used.

-q integer
Sets the priority of the print job. Default priority is 20, range is 0 (most urgent) to 39 (least urgent).

--hold
Indicates that the job should be placed in the held state as soon as it enters the queue. (This might be used if a printer were under the strict control of an operator and no jobs were to be printed until approved by the operator. If the job were received through a network server such as lprsrv or papsrv then the use of this switch could be forced.)

-Z true
Silently discard jobs which do not end with ``%%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.

-Z false
Don't discard jobs which do not end with ``%%EOF'' (default).

-U
This switch causes PPR to unlink (delete) the file which it prints as soon as the file has been copied to the queue. Samba print commands should use this option.

--show-jobid
Causes the job ID to be printed when the job is submitted. If the job is broken up into parts (using the -Y option), multiple job IDs are printed, one per line.

--show-long-jobid
Same as --show-jobid but the job IDs is printed in long format.

--print-id-to-fd integer
The numberic part of the job ID is sent to the indicated file descriptor. The job ID is formatted as as ASCII integer followed by a linefeed. Only one job ID is printed, even if the job is broken up into subjobs. This is used by the IPP server.

--save
Keep the job in the queue after it has been printed. This option is accepted, but as of now it has no effect since the necessary backend code is missing.

--question <path>
This feature is used when we want the user to answer some question about the job before it is released for printing. Note that this option doesn't automatically hold the job, that should be done with the --hold option.

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.

N-Up and other Special PPR Features

-N integer
Print pages N-Up. The integer specifies the number of virtual pages to put on each side of the physical page.

-N noborders
Turns off N-Up borders.

-O string
Specifies a string to overlay diagonally in outline type across each page. Such a string might be ``Draft'' or ``Confidential''.

-s positive_integer
Set signature sheet count. This turns on signature printing. It also turns on 2-Up printing if N-Up is not on already.

-s booklet
This switch instructs PPR to format the document as a single signature having the minimum number of sheets required. This turns on signature printing. It also turns on 2-Up printing if N-Up is not on already.

-s both
-s fronts
-s backs
Indicate which part of each signature to print. The default is ``both'' which works best with a duplex printer. Using ``fronts'' and ``backs'' it is possible to print signatures on a simplex printer in two passes.

-Y string
This switch is for the new and still experimental job splitting feature. If you wish to learn about it, please examine the comments at the head of the source file ``ppr/ppr_split.c''.

--page-list string
This switch can be used to specify a subset of the documents pages which should be printed. Work on it is not yet complete. It should not be used when charging for printing since it doesn't yet take that into account.

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.

Input Filters

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.

-T type
--file-type type
The -T option manually overrides PPR's automatic file type detection. This may be necessary if for some reason the automatic detection system identifies a file incorrectly.

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.

-o string
This switch specifies a set of options which will be passed to the input filter. The string is appended to the default filter options. The string should take the form ``option1=value option2=value''. If the -o switch appears more than once on the command line, the options they specify are combined into a long list in the order of their appearance.

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.

--markup <option>
this option controls how markup language files are printed. A markup language is a plain text file with special codes added. Examples of markup langauges are Troff, TeX, HTML, SGML, and RTF.

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:

--markup format
If a text file is marked-up, it is passed through a formatting filter to produce a typeset document. If no formatting filter is available then the job will be rejected.

--markup lp
Files which are marked-up are passed through the lp filter. (As if the -T lp switch had been used.)

--markup pr
A marked-up file is paginated with pr and then passed through the lp filter. (As if the -T pr option had been used.)

--markup fallback-lp
This is the default. If an apropriate formatting filter is available it is used. If not, the effect is the same as that of --markup lp.

--markup fallback-pr
If an apropriate formatting filter is available it is used. If not, the effect is the same as that of --markup pr.

Proofmode and Printer Validation

-P notifyme
set ProofMode to ``NotifyMe''. This and the other -P switches override any ``%%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.

-P substitute
set ProofMode to ``Substitute''. With a ProofMode of ``Substitute'', PPR will substitute fonts and attempt to do without missing printer features such as duplexing.

-P trustme
set ProofMode to ``TrustMe''. With a ProofMode of ``TrustMe'', PPR will send the job to the printer even if some requirements or resources are missing. The assumption is that the document itself can compensate.

Internal Features

-Q string
When papsrv invokes ppr, it uses this switch to indicate what answer it supplied when asked if the printer has a TrueType font rasterizer. This value is used by ppr to know whether a Macintosh will probably download type 1 or type 42 fonts. This prediction is used when merging dual mode Macintosh fonts in the cache. The argument string may be any one of ``None'', ``Type42'', and ``Accept68K''.


ENVIRONMENT

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.


DIAGNOSTICS

Exit codes for ppr are defined in the source code file include/ppr_exits.h.


SEE ALSO

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


HISTORY

PPR was written at Trinity College during 1993--2003. It was first released to the public on 26 April 1995.


AUTHOR

David Chappell, Trinity College Computing Center, Hartford, Connecticut.


BUGS

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.