ppr.1


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.

This man page also describes the filters which PPR can invoke in order to convert the input file to PostScript. A number of filters are supplied with PPR. These include a line printer filter, a Fortran carriage control filter, and a dot matrix printer language filter. Other filters are available if certain common Unix programs such as Troff, TeX, and NetPBM are available. The filters are described in the section for the -T switch.

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 switch is replaced by the value of the switchset macro for the selected destination. The switchset macro for a printer is defined with the command ``ppad switchset'', for a group with the command ``ppad group switchset''. Since the switches to insert are read from the printer's or group's configuration file, the printer or group must be specified with the -d switch before the -I switch appears on the command line. If no switchset is defined for a printer or group, the -I switch has no effect.

The switchset macro is useful in cases where ppr is not invoked directly. For example, PPR's LPR/LPD server lprsrv invokes ppr with the -I switch. If you have a printer called ``chipmunk'' and want to make a special queue for it which always makes booklets you can define a group which contains only one member:

$ ppad group add chipbook chipmunk

and then set a switchset for the ``chipbook'' group:

$ ppad group switchset chipbook -s booklet

When this has been done, if remote machines print to the queue ``chipbook'' through lprsrv, the `` -I '' switch, which lprsrv puts in the command line when invoking ppr, will be expanded to `` -s booklet ''.

Remember though, that the switchset macro is only effective if -I occurs somewhere in the ppr command line. For example:

$ ls -l /usr/bin | ppr -d chipbook -I

will print a booklet, but

$ ls -l /usr/bin | ppr -d chipbook

will not.

.

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 privledged user or the -a switch is used. For this purpose a privleged user is defined as the user ``ppr'', a the user with the id 0 (``root''), or a user who is a member of a group called ``pprprox''.

(If ppr is invoked by a non-privledged 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 ignorefor
A privledged 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
With this switch, you can provide a principal identifier. This string will be attached to the job. You can later use the -X switch with the same identifier string with ppop in order to delete or perform other operations on the job. If you supply a different string to ppop, it will refuse to carry out the operation. This is mainly used by daemon processes which accept jobs over the network.

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

-A
indicates that a privledged user (as defined for teh -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.

.

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 responder
Specifies the method which should be used to send responses to the user who submitted the job. Typical values include ``write'', ``mail'', ``samba'', and ``none''. The default is read from the environment variable PPR_RESPONDER if it is defined, otherwise the default is ``write''.

The value ``write'' causes the message to be written to the user's terminal if he is logged in, and to be sent by mail is he is not. 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 value ``mail'' causes the notification to be sent by email. The default address is the name of the user who invoked ppr. The address may be change by means of the -r switch.

The value ``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 responder with a default option of ``printed=no''.

The value ``netsend'' causes LAN Manager network messages to be used. The name of the client to receive the message should be specified by means of the -r switch. The sample LAN Manager print processor does this.

The value ``samba'' causes the notification to be sent by means of the messaging facilities of the LAN Manager compatible Unix server Samba. The name of the client to receive the message should be specified with the -r switch. For an example of how this is done, see the ``print command'' described in the ppr2samba(8) man page.

The value ``xwin'' causes the notification to be sent to an X-Windows display. The display must be specified with the -r switch. This will not work if the user ``ppr'' can not open the display. The xpprgrant command, described in the xppr man page, can be used to grant the necessary permission. If xmessage is available, this responder implements timeout=.

The value ``atalk'' causes the notification to be sent to a Macintosh program such as ``Messages'' which comes with CAP60 or ``Broadcast''. (The first supported message receiver discovered on the Macintosh will be used.) In order for this responder to work, you must have CAP and the appropriate Unix programs to dispatch messages to Macintosh's. The CAP60 distribution includes a program called ``macto'' in the contrib/Messages directory which will send messages to a Macintosh system extension called ``Messages'' which is also included with CAP60. The configuration file /etc/ppr/atalk.conf indicates which Unix programs are available to send messages to Macintoshs. It is also necessary to start the Appletalk Map Daemon /usr/ppr/bin/atalkmapd.

The value ``pprpopup'' causes the notification to be sent to the PPR popup program for MS-Windows 95. The PPR popup program is a Tcl/Tk script designed to be on a MS-Windows 95 machine 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. When a job is received through Samba and the samba_submitter program is used as the ``print command'', the samba_submitter program attempts to open a connexion to the PPR popup program on the client and requests it to ask the user for his name. If the transaction is sucessful, samba_submitter will subsequently run ppr with the -m pprpopup switch. Thus the PPR popup program will also be used to inform the user of what happened to his job.

The value ``audio'' causes a voice announcement to be made. If the address is in the form ``smith.pc.trincoll.edu:15009'' then the announcement will be played through the Tcl/Tk script mentioned in the previous paragraph. If the address begins with ``/dev/'' then it will be played through a sound card on the local machine. As supplied, program /usr/local/bin/play is used to acomplish this. If you wish to substitute another program, you must edit /usr/ppr/lib/play_local.pl. 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 value ``none'', the -m parameter actually specifies the name of the program in /usr/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 "PPR, a PostScript Print Spooler".

-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 write. The exact correct format for this parameter depends, of course, on the responder that is being used.

--responder-options
This switch specifies the list of options to be passed to the responder. These options are name=value pairs. Not all options will be supported by all responders. Responders will ignore options they do not understand. The section for the -m switch describes the options understood by each responder.

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

.

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.

-t [yes, no, dontcare]
this parameter indicates the user's preference as to trailer pages. The default is dontcare. As with banner pages, the spooler will ultimately make its own decision.

.

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
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
display information about file auto type detection.

infile:filter
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.

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

structure:sections
causes ppr to print a message as it enters each section of a Document Structuring Convention compliant document.

.

.

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 medianame
sets the default media. The default media 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 media. For example, if the B<-D letter> switch is used but a ``%%BeginFeature: *PagesSize Legal'' comment appears in the document, then the media type ``legal'' will be selected because it is 8.5 by 14 inches but has all the other attributes of ``letter''.

-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''
inserts PostScript setup code for printer features. Since feature names almost always contain spaces and asterisks, they should be quoted to get them through the Unix shell. 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 it 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. (If N-Up printing has been selected, PPR may attempt to synthysize missing feature code for selecting page sizes. This is on the theory that though the printer may not be able to accomodate a certain paper size and hence not have a command for it, it may still be represented by a rectangle on a physical page.)

A feature which is commonly invoked by this command is duplex:

$ ppr -d adshp4m -F '*Duplex DuplexNoTumble'

Paper input trays are another example:

$ ppr -d adshp4m -F '*InputSlot Upper'

-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:softsimplex
These and the following options cause ppr to look for comments in the file which may indicate the desired duplex mode. `` -R duplex:softsimplex '' is the default. In this mode, ppr reads the comments and alters its page counting if comments which indicate code which turns duplexing on are found, however it does not insert simplex invocation code if it finds no duplex comments. Simplex is ``soft'' in this case in that a document which includes code to invoke duplex mode will go unnoticed and turn on duplex mode without PPR's knowledge.

-R duplex:simplex
Reads duplex comments, if none found, force simplex mode. If duplex ``on'' comments are found, PPR turns duplexing off itself anyway for good measure.

-R duplex:duplex
Same as above, but duplexing (long edge duplexing) is the default. PPR turns duplexing on itself so that is will be harder for to pretend to be printing in duplex while they are really printing in simplex.

-R duplex:duplextumble
same as above, but tumble duplexing (short edge duplexing) is the default.

-R ignoreduplex
Ignore the possibility of duplex mode. Without this switch, PPR reads ``%%BeginFeature: *Duplex'' comments in order to determine whether the document is printed in simplex or duplex mode.

.

Number of Copies

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

-n collate
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.

-R copies
Read any copy count which appears in the document comments and print that many copies.

.

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
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 of them 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 available in PPR version 1.30:

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 and printer feature code insertion will by bypassed, using this hack with jobs which print correctly may cause them to not print correctly if at all.

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.

.

-S [true, false]
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 the one being stripped out can be put in the cache. Doing so can save disk space in the spool area. The default value is true.

This feature could cause problems if you have a driver with an incorrect resource name. For instance, certain HP printer drivers for Macintoshes have a procedure set which is labeled as the standard LaserWriter procedure set but is not. When this mislabeled procedure set is stripped out and replaced with the standard LaserWriter procedure set at print time, the job may fail and be arrested. If you encounter this problem, you should put a ``PPRParms: -S false'' line in the papsrv configuration file. (See papsrv.conf(5).

.

Miscelaineous

-C string
Specifies a default document title. The default title can be overridden by ``%%Title:'' line in document.

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 ``'' to make the default a blank title.

--ignore-dsc-title
This switch causes ppr to ignore ``%%Title:'' lines in the job. This has the effect of making a default title specified with -C a firm 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
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.

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

.

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

-p string
This switch can specify a subset of the documents pages to be printed. The string is a set of name=value pairs. If a pair appears more than once, the last instance is considered the valid one. These are the currently supported pairs:

even=boolean
Indicates whether or not even numbered pages should be printed. The default is true.

odd=boolean
Indicates whether or not odd numbered pages should be printed. The default is true.

start=ordinal
Indicates the first page which should be printed. Of course, if the setting of even or odd prevents it, the indicated page will not be printed and printing will start at the first qualifying subsequent page.

stop=ordinal
Indicates the last page which may be printed. As with start, the settings of even and odd can affect this. Setting this to zero means to print to the end of the document. (Which, not suprisingly, is the default.)

.

.

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
The -T option manually overrides PPR's automatic file type detection. This may be necessary if for some reason the automatic detection arrives at an erroneous result.

Whether the type is automatically detected or is specified manually with the -T switch, if the input file is not PostScript, it must be converted to PostScript. This is done by means of filters. The filters programs are stored in /usr/ppr/lib. They have names consisting ``filter_'' followed by the file type name. For example, the filter for files of type ``dvi'' is /usr/ppr/lib/filter_dvi.

If the desired filter does not exist, the job will be rejected. Some filters are supplied with PPR and will always be present. These include the filters for types ``lp'', ``lp_autolf'', ``dotmatrix'', ``fortran'', and ``pr''; others depend on filter programs that are not distributed with PPR. These include the filters for ``tex'', ``dvi'' ``ditroff'', ``cat4'', ``pcl'', ``jpeg'', ``gif'', ``tiff'', ``sunras'', ``cif'', ``plot'', and ``wp''.

When a filter is not supplied with PPR, it may be necessary to create one, possibly in the form of a shell script which invokes programs such as TeX, Dvips, Troff, Groff, or PBMPlus.

When PPR is installed, a script called ``/usr/ppr/install/setup_filters''. is run. This script looks for some potential filter programs and builds filter scripts to run them. If you add programs which can be used as filters after PPR is installed, you should log in as ``ppr'' and run /usr/ppr/install/setup_filters again.

-T lp
indicates that input file is formated for a line printer or is unformatted ASCII text. You might use -T lp to print a listing of a PostScript program since otherwise, PPR would send it directly to the printer where it would be executed.

This filter supports many -o options. These are described in the section which describes the -o switch.

The default value for the ``charset='' option is ``ISOLatin1''.

This filter supports the gutter= option which specifies an amount to be added to the margin on the side on which the paper will be bound. The effect of the gutter= option is influenced by the setting of the duplex= option. With duplex=undef , the gutter= option has no effect. With duplex=none the gutter is added to the left hand margin. With duplex=notumble the gutter is added to one of the long edge margins, the left one on odd numbered pages, the right one on even numbered pages. With duplex=tumble the gutter width is added to a short edge margin, the top one on odd numbered pages, the bottom one on even numbered pages.

This filter supports the orientation= option. If no orientation= option is used or orientation=auto is used, then the orientation will be decided upon automatically.

If the orientation is to be decided automatically, then the descision is based upon the parameters landscape_lentrigger and landscape_asptrigger. These parameters are described in detail in the section for the -o switch.

-T lp_autolf
indicates that the input file is formated for a line printer that automatically performs a line feed on carriage return or is unformatted ASCII text that uses a single carriage return to indicate end of file. (This is the format of Macintosh text files.) This is nearly the same filter as for -T lp above and it supports the same options.

-T postscript
indicates that the input file is already in PostScript format and thus does not require filtering. Since no filter is invoked, the filter options have no effect.

-T pcl
indicates that the input file is in HP PCL format. The current distribution of PPR does not have a PCL to PostScript converter so this option will not work unless you provide one. If you provide one, you should install it as /usr/ppr/lib/filter_pcl.

-T dotmatrix
indicates that a generic dot matrix printer filter should be applied to the input file. This filter converts an Epson compatible printer language to PostScript. This includes the commands of the Epson LX-80, Epson FX-850, and NEC Pinwriter 6. The colour option of the Pinwriter 6 is emulated, colour output will be produced on colour PostScript printers. Partial support exists for the command sets of other printers but it has neither been completed nor tested. The proportionally spaced font of the Epson FX-850 is emulated using Courier.

Among the filter supported by this filter are ``noisy'', ``bin'', ``duplex'', and ``charset''. For a description of these options, see the description of the -o switch. The default value of the ``charset'' option is ``CP437''. This filter also supports the following options which are unique to the dotmatrix filter:

The -o ``emulation='' option sets specific emulation modes to more closely emulate specific printers. The recognized values are ``epson'', ``proprinter'', and ``p6''. The value ``epson'' means to interpret the commands as an Epson LX-80 or FX-850 would. The value ``proprinter'' means to emulate an IBM proprinter, but it has not been well tested and may be incomplete. The value p6 means to interpret the commands as an NEC Pinwriter 6 would and implies `` pins=24 '' as well. The default is ``emulation=epson''.

The -o ``pins='' option sets the emulator to mimic a 9 pin or a 24 pin printer. If `` pins=9 '' or `` pins=24 '' is not used, a 9 pin dot matrix printer will be emulated unless 24 pin commands are seen on the first pass through the input file. The motion commands are interpreted differently in 9 and 24 pin mode.

The -o ``perfskip='' option sets the perforation skip in lines. The default is 0.

The -o ``narrowcarriage='' option sets 8 inch line narrow carriage emulation to true or false. When it is true, text printed at the left margin will be printed 0.25 inch from the left hand edge of the sheet.

The -o ``xshift='' option specifies an amount to shift the page image right. The units are 72ths of an inch.

The -o ``yshift='' option specifies an amount to shift the page image down. The units are 72ths of an inch.

-T pr
indicates that the job should be passed through pr before being printed. After it is passed through pr it is passed through PPR's line printer emulator. This instance of the -T switch does not truly indicated the type of the input file, it is just a convenient way to get files formated and printed.

It is assumed that the file you print is compatible with your system's version of pr. The file name or the string specified with the -C switch will be used as the title. The -o option ``width='' specifies the value for pr's -w switch and ``length='' specifies a value for pr's -l option. Since, after being processed by pr, the file is passed through the ``lp'' filter, lines will be wrapped at the length specified by the -o width= switch. All of the other ``lp'' filter options will work with this filter as well.

-T fortran
indicates that the input file employs Fortran carriage control. This filter uses the -o options ``width='' and ``length=''.

-T troff
indicates that the input file is Troff source. If you have Troff or Groff, /usr/ppr/install/setup_filters will build a filter in the form of a shell script which invokes one of them.

The filter script supplied with PPR assumes that the document uses the man macro package. The filter does not have any options. If you need more elaborate Troff processing, you should create your own, improved version of /usr/ppr/lib/filter_troff.

-T cat4
indicates that the input file is formated for a CAT/4 phototypesetter. This is an old Troff output format. No such filter is provided with PPR. If you write one, you should install it as /usr/ppr/lib/filter_cat4.

-T ditroff
indicates that the input file is in Ditroff (Device independent Troff) output format. This is the format of the output file produced by modern versions of Troff as well as Groff. If you have Groff's PostScript filter or Troff's dpost and postreverse, PPR will build a shell script called ``/usr/ppr/lib/filter_ditroff'' to act as the filter. This filter does not have any options.

-T dvi
indicates that the input file is in TeX DVI format. The /usr/ppr/install/setup_filters script will create the necessary filter script ``/usr/ppr/lib/filter_dvi'' if it finds DVIPS.

If the -o ``noisy=yes'' option is used, this filter will allow DVIPS and MetaFont to print their running commentary output to stderr, otherwise, they run silently.

By default, this filter automatically generates a config file for DVIPS. The automatically supplied -o options ``mfmode='', ``freevm='', and ``resolution='' are used to generate the DVIPS configuration file.

The -o ``dvipsconfig='' option can override the automatic generation of a DVIPS configuration file. The value of the option is passed to dvips with dvips's -P switch.

-T tex
indicates that the input file is TeX or LaTeX source. This option requires TeX, LaTeX, and Perl 4 or 5.

If TeX or LaTeX fails, the log is printed instead of the document. If the -o ``noisy=yes'' option is used, this filter will allow TeX, LaTeX, DVIPS, and MetaFont to write their running commentary output to stderr, otherwise, they run silently. Since this filter passes its output to the DVI filter, all the other options supported by the DVI filter are supported by this filter as well.

-T wp
indicates that the input file is a WordPerfect document. This will only work if /usr/ppr/lib/filter_wp is present, executable, and is a suitable filter. No such filter is supplied with PPR.

-T texinfo
indicates that the input file is in GNU Texinfo format. A filter script supplied with PPR will be installed if texi2dvi is in the PATH when /usr/ppr/install/setup_filters is run. This filter has no options of its own, but it invokes the DVI filter, so the DVI filter's options may be used.

-T rtf
indicates that the input file is in Rich Text Format. No filter for this format is supplied. If you write one you should install it as ``/usr/ppr/lib/filter_rtf''.

-T jpeg
indicates that the input file is a JPEG picture file. If -o ``colour=yes'' or -o ``colour=yes'' option is used with and the other picture format filters, the picture will not be converted to grayscale. (The ``colour='' option is among the automatically generated default filter options, so you don't have to enter it on the command line unless you want to force the filter to generate grayscale output for a colour printer or colour output for a grayscale printer.)

Most of the picture format filters are shell scripts which call the PBM utilities and the independent JPEG group's utilities.

-T gif
indicates that the input file is a GIF picture file. PPR's filter for this format uses the NetPBM utilities.

-T tiff
indicates that the input file is a TIFF file. PPR's filter for this format uses the NetPBM utilities.

-T sunras
indicates that the input file is in Sun raster format. PPR does not provide a filter for this format.

-T plot
indicates that the input file is in the format of the output of the Berkeley plot library. A sample filter in the form of a shell script is provided. It calls plot2ps.

-T CIF
indicates that the input file is in CalTech Intermediate Form graphics language. No filter for this format is supplied. If you write one, you should install it as ``/usr/ppr/lib/filter_cif''.

-T bmp
indicates that the input file is in Microsoft Windows BMP format. A shell script which calls NetPBM utilities is provided.

-T xbm
indicates that the file is an X-Windows bit map. The filter is a shell script which calls NetPBM utilities.

-T xpm
indicates that the input file is an X-Windows pixel map. The filter is a shell script which calls NetPBM utilities.

-T xwd
indicates that the input file is an X-Windows window dump. The filter is a shell script which calls NetPBM utilities.

-T pnm
indicates that the input file is a Portable Bit Map, Portable Gray Map, or Portable Pixel Map. The filter is a shell script which calls NetPBM utilities.

-T png
indicates that the file is in Portable Network Graphics format. This is a new format and PPR does not have a filter for it yet.

.

-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 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. If multiple -o switches may be used, each instance simply adds additional 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 ``width=132'' to the fortran filter, and pass ``width=80'' to the pr filter.

Here is a complete list of the -o options. No filter supports all of these options. (The filters which support each option are named in parentheses.)

noisy=boolean
instructs the filter to print debugging messages or to refrain. Some filters (lp, lp_autolf, pr, dotmatrix) will indicated which options they do not understand from among those that appear after ``noisy=yes''.

(Supported by: lp, lp_autolf, pr, tex, texinfo, dvi, dotmatrix, and fortran at the very least)

colour=boolean
sets filters to produce colour or grayscale. This option is provided automatically as a default filter option.

(Supported by: dotmatrix, all picture format filters)

freevm=positive_integer
indicates the printer's free virtual memory in bytes. This option is automatically provided as a default filter option.

(Supported by: tex, texinfo, dvi)

mfmode=number
indicate the MetaFont mode to be used to generate fonts for this printer. This options is automatically provided as a default filter option.

(Supported by: tex, texinfo, dvi)

level=positive_integer
sets the PostScript LanguageLevel for generating code. At the time of this writing, the correct value for all existing PostScript implementations is either 1 or 2. This option is provided automatically as a default filter option.

(Supported by: dotmatrix, most if not all of the image format filters)

dvipsconfig=name
sets the argument for DVIPS's -P switch, overriding the default which is to use an automatically generated configuration file.

(Supported by: dvi, tex, texinfo)

resolution=positive_integer
sets the resolution for code generation to positive_integer DPI. This option is automatically provided as a default filter option. (tex, texinfo, dvi, most if not all of the image filters)

width=integer
sets the maximum width of the page in columns.

(Supported by: fortran, pr, lp, lp_autolf)

length=integer
sets the length of the page in lines.

(Supported by: fortran, pr)

mincolumns=integer
sets the minimum number of columns to be provided on the page. Even if the document requires fewer columns than this, the type size will not be reduced beyond the point required to achieve the specified number of columns. The default for this parameter is generally 70, but the default may vary from filter to filter.

(Supported by: lp, lp_autolf, pr)

tabwidth=integer
sets the number of columns between tab stops. The default is 8.

(Supported by: lp, lp_autolf, pr)

pdeflines=integer
sets the number of portrait mode lines per page for files which do not contain form feeds.

(Supported by: lp, lp_autolf, pr)

ldeflines=integer
sets the number of landscape mode lines for files which do not contain form feeds.

(Supported by: lp, lp_autolf, pr)

minlines=integer
maxlines=integer
these two parameters affect how many lines of vertical space is provided on the page. If the shortest page in a document is shorter than minlines, pages are made minlines long, resulting in white space at the bottom of every page. If the longest page is longer than maxlines, all pages are made maxlines long, with the result that some pages are split into two or more pages.

(Supported by: lp, lp_autolf, pr)

pmlm=dimension
pmrm=dimension
pmtm=dimension
pmbm=dimension
these set the minimum left, right, top, and bottom margins respectively for portrait mode.

(Supported by: lp, lp_autolf, pr)

lmlm=dimension
lmrm=dimension
lmtm=dimension
lmbm=dimension
these set the minimum left, right, top, and bottom margins respectively for landscape mode.

(Suported by: lp, lp_autolf, pr)

gutter=dimension
The amount to be added to the margin on the binding edge of the paper. In simplex mode this is the left hand side. In duplex mode this is the left hand side of odd pages and the right hand side of even pages. In duplex tumble mode this is the top side for odd pages, the bottom side for even pages.

(Supported by: lp, lp_autolf, pr)

landscape_lentrigger=positive_integer

landscape_asptrigger=real
These options control when the line printer emulating filters switch from portrait to landscape mode. If the page length is unknown (because the file contains no form-feeds), landscape mode is selected if the maximum line length exceeds landscape_lentrigger. If the page length can be determined, landscape mode is selected if the maximum line length divided by the page length exceeds the value of landscape_asptrigger.

The default values for landscape_lentrigger and landscape_asptrigger depend on the paper size, margins, gutter width, and other parameters such as char_height and char_width. For letter size paper with margins of half an inch or so, landscape_lentrigger is about 114 and landscape_asptrigger is about 1.75.

(Supported by: lp, lp_autolf, pr)

fontnormal=fontname
fontbold=fontname
The PostScript name of the font to be used for printing normal and bold text. For example, ``ppr -o 'fontnormal=Times-Roman fontbold=Times-Bold''. As a general rule only fixed width fonts will yield satisfactory results.

(Supported by: lp, lp_autolf, pr)

charwidth=real
charheight=real
These options inform the filter of the size of the fonts selected. These will normally only have to be used if the ``fontnormal='' or ``fontbold='' options are used. The dimensions are expressed as a decimal fraction of the point size. For example, a typical setting for Courier is -o 'charwidth=0.6 charheight=1.0' .

(Supported by: lp, lp_autolf, pr)

charset=name
sets the character set. The options are ``Standard'' ``ISOLatin1'', and ``CP437''.

(Supported by: dotmatrix, lp, lp_autolf, pr)

pagesize=pagesize_name
This sets the page size to be used. Appropriate values will be inserted in the ``%%DocumentMedia:'' comment in an attempt to select paper of the specified size. The size names are the same as those which appear in *PageSize lines in a printer's PPD file. Typical values are ``letter'' and ``a4''. This parameter is not case-sensitive.

(Supported by: lp, lp_autolf, pr)

orientation=orientation
This sets the orientation of the lines on the printed page. Valid settings are portrait, landscape, and auto. Filters which cannot automatically determine whether portrait or landscape is most appropriate should treat auto as equivelent to either portrait or landscape.

(SUpported by: lp, lp_autolf, pr)

duplex=mode
This causes a filter to attempt to select the duplex mode. Do not confuse this with the -R duplex: series of switches which attempt to determine what duplex mode a document wants as well as setting default duplex modes. Duplex modes set with the -o duplex= switch will override defaults set with the -R duplex: switch. Legal values for the -o duplex= switch are:

duplex=undef
Do not attempt to influence the duplex mode.

duplex=none
Attempt to select simplex mode.

duplex=tumble
Attempt to select tumble duplex mode.

duplex=notumble
Attempt to select no tumble duplex mode.

Duplex modes set with the duplex= option will be overriden by duplex options set with the -F switch.

(Supported by: lp, lp_autolf, pr).

mediatype=type
This sets the media type field in the ``%%DocumentMedia:'' comment. By default this field is left empty. Typical values for this field as suggested in the ``PostScript Language Reference Manual, Second Edition'', page 659 are ``19HoleCerlox'', ``3Hole'', ``2Hole'', ``ColorTransparency'', ``CorpLetterHead'', ``CorpLogo'', ``CustLetterHead'', ``DeptLetterHead'', ``Labels'', ``Tabs'', ``Transparency'', and ``UserLetterHead''. The value of the mediatype= option should be considered case-sensitive.

For example, to run a file through the Unix pr program and then print it on 3 hole paper:

$ ppr -d chipmunk -T pr -o 'mediatype=3Hole' myfile.txt

(Supported by: lp, lp_autolf, pr)

mediaweight=real
This sets the weight field in the ``%%DocumentMedia:'' comment. The value should be a real number. The units are grams per square metre. The default is 0 which means no specific weight is requested.

(Supported by: lp, lp_autolf, pr)

mediacolour=colour_name
mediacolor=colour_name
A filter may use this option to set the colour field in the ``%%DocumentMedia:'' comment. Typical values are ``white'', and ``blue''.

(Supported by: lp, lp_autolf, pr)

pins=9
pins=24
sets the Dotmatrix filter to emulate a 9 or 24 pin printer.

(Supported by: dotmatrix)

emulation=emulation_name
sets the make or model of printer to emulate. The choices are ``epson'', ``proprinter'', and ``p6''.

(Supported by: dotmatrix)

perfskip=positive_integer
sets the number of lines to skip at the ``perforation''.

(Supported by: dotmatrix)

narrowcarriage=boolean
sets narrow carriage (8 inch) dotmatrix printer emulation.

(Supported by: dotmatrix)

xshift=integer
yshift=integer
specify an amount to shift the page image to the right and up respectively. The units are 72ths of an inch.

(Supported by: dotmatrix)

.

.

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 predict whether a Macintosh will 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, 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.


FILES

PPR(1) uses the directories /var/spool/ppr/queue, /var/spool/ppr/jobs, and /tmp. It increments the number in /var/spool/ppr/.nextid. It writes to the FIFO /var/spool/ppr/PIPE. It may deposit files in the subdirectories of /var/spool/ppr/cache.


DIAGNOSTICS

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


SEE ALSO

the ppop manpage (1), the papsrv manpage (5), the lprsrv manpage (8), the papsrv manpage (8), the pprd manpage (8), the ppad manpage (8), the ppuser manpage (8) ppr2samba(8), ``PPR, a PostScript Print Spooler'', ``Installing and Using PPR''.


HISTORY

PPR was written at Trinity College during 1993, 1994, 1995, and 1996. 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.