papif(8)

NAME
papif, papof - printer system input and output filters for printing to AppleTalk LaserWriters

DESCRIPTION
papif and papof are input and output filters, respectively, for the Berkeley line printer spooling system (see the section "Line Printer Spooling System" below for definition of these terms and some explanation), that print to a LaserWriter (or other PostScript printer) attached to an AppleTalk network (see CAP(8)). papif is actually the "formatted text" input filter, but may also be used to "backend" other input filters. papof simply creates a PostScript format banner page for use by papif.

papif has functionality similar to that of pscomm in Adobe's TranScript package. TranScript provides support for spooling to a LaserWriter via a serial line. papif can be used in most cases as a replacement for pscomm when a printer is attached to AppleTalk instead of a serial line.

When papif is used in conjunction with TranScript, two special TranScript filters psrv and pstext may be used to reverse the order in which pages are printed and convert plain text files to PostScript, respectively. If pstext is used papif decides to invoke pstext if the first two characters in the file are not the PostScript magic sequence "%!". If psrev is used, then the first 11 characters must be "%!PS-Adobe-". All files conforming to the Adobe Document Structuring Convention (required for psrv to work properly) must start with that sequence. papif will work properly even if the input is a pipe.

A particular printer is established as usable under the Berkeley line printer spooling system by installing an entry in /etc/printcap (see printcap(8)). Unfortunately, there is no printcap entry field that allows one to easily specify the NBP entity name of the AppleTalk printer (the name that shows up in Chooser). To bypass this problem, papif translates the UNIX printer name to the NBP entity name by the use of a lookaside file called "cap.printers". The format of cap.printers is described in the section "cap.printers format", below.

The Berkeley line printer daemon does not pass the UNIX printer queue name as an argument to printing filters. papif needs to know which UNIX printer queue it is servicing, so it can map to the NBP entity name via cap.printers. papif will determine the printer queue name from any of these methods:

    1)  It will use the value passed by a "-P" or "-p" command line option. This can be arranged by creating a shell script to be specified in the /etc/printcap file as the "if" filter. This script would in turn just call papif, passing all the arguments it received from lpd, plus the "-P printer-name" argument. The shell script can either have a fixed value for the "-P" switch or try to figure it out. For example, lpd always forks off the input filter in the spool directory of the printer, so if the spool directory has a name matching the UNIX printer name, then this value could be used - this is the method used by TranScript. If the system already has TranScript or is licensed for TranScript, then the shell scripts provided with TranScript are very good.

    2)  If argv[0] (the name it is invoked by on the command line) is neither papif nor psif, then that name will be used as the printer queue name. This can be arranged, for example, by renaming papif to the queue name, or making a hard or symbolic link with the queue name, and then specifying that name as the "if" filter in the /etc/printcap file.

    3)  The PRINTER environment variable can be set to the queue name, for example, by an "if" shell script filter.
If none of these methods is used to set the printer queue name, then papif will assume that the NBP entity name is "LaserWriter Plus:LaserWriter@*" (LaserWriter named "LaserWriter Plus" in the local zone). See the section "Example printcap entries" for an example printcap entry.

If the printer name ends in -dup* (e.g. has a name such as lw-dup or lj-duplex), and papif was compiled with the DUPLEXMODE option, papif will assume that this printer has the capability to print on both sides of a page. The printer is then directed (by the addition of some PostScript code) to use this ability.

ARGUMENTS

papif accepts the following arguments, most of which are supplied by the printer system daemon, lpd:

-n <user name>
    is a standard lpd argument specifying the user name.

-h <host name>
    is a standard lpd argument specifying the name of the host from which the print job was submitted.

-c, -x, -y, -i, -w
    are standard lpd arguments which are ignored.

-L  is a Rutgers added option to specify landscape mode printing.

-P <UNIX printer name>
    is a TranScript compatible option that specifies the UNIX printer name.

-2  directs the printer to print this job in 2-sided mode. Only use this if your printer has the hardware to support this. This switch only exists if papif has been compiled with the DUPLEXMODE feature.

-p <program name>
    is a TranScript compatible option that specifies the program name.

-r  is a TranScript compatible option that says never to invoke the page reversal filter.

-k  specifies that DDP checksums are not to be used, the field is set to zero.

<accounting file name>
    An argument without a leading hyphen (-) is assumed to be the accounting file name.

-d <debug args>
    is used to specify the CAP library debugging arguments. (No spaces allowed between the -d and the flags). See CAP(3) for valid flags.

In addition, a number of environment variables may be set to modify papif operating parameters. Most of these can and should be customized when compiling papif (cf. installation instructions) rather than at runtime. The LOCAL CONFIGURATION section, below, should specify the values that have been compiled into papif at this site. The first group are TranScript compatibility options (e.g. used by TranScript). Most of these options are "binary" in that setting them to 0 means off and non-zero means on.

BANNERFIRST
    if set, says to print the banner first.

BANNERLAST
    If set, says to printer the banner last. BANNERFIRST overrides BANNERLAST.

CHARGEBANNER
    is a papif specific binary option. If set, banner pages will be charged to the user if accounting is being done.

Note if you wish to define banner pages as on, you must have an "of" output filter defined in /etc/printcap that presents a ".banner" file in PostScript format. CAP includes a filter papof that accomplishes this. You should also be able to use the standard TranScript filter for this as well.

VERBOSELOG
    If set, tells papif to be a little more verbose in its logging. This is the default.

REVERSE
    a string containing the location of the page reversal filter. This is a standard part of TranScript.

PSTEXT
    a string containing the location of the text filter that translates plain text to PostScript. This is a standard part of TranScript.

Here are a number of non-TranScript options settable in the environment.

ADOBE_STRUCTURED
    PAPIF has a minimal understanding of the Adobe Systems Document Structuring Conventions (to wit, it understands the "%%EOF" marker). Setting ADOBE_STRUCTURED to be true implies that it should try to interpret the incoming document.

IDLESTUFF
    Some sites have reported seeing an "idle" bug where papif doesn't do anything while the LaserWriter is idle. You can define "IDLESTUFF" when compiling papif to enable some code to get around this problem. Note: with the new release of papif, this problem shouldn't be there anymore, but it is included just in case.

SFLOWQ, RFLOWQ
    papif has a settable "Send Flow Quantum multiplier" called SFLOWQ that tells how many packets it should be sending in a single write. This should be set to 1 (maximum 8) if there are problems with the FastPath or LaserWriter dropping packets. RFLOWQ is the same thing but in the other direction. You can probably leave it set to 8 (the maximum).

ATPRESPONSETIMEOUT
    specifies the ATP response cache timeout in ticks (1/4 second intervals). (Note: zero is infinity: it never times out). This is used to extend the time that a response from the LaserWriter may take.

WATCHTIME
    specifies the minimum interval in seconds that will take place before papif polls the LaserWriter for its status (and updates the status file in the spool directory). Zero implies that no status watching should be done.

DEBUG
    if set, tells papif that is should print out debugging information giving the state of the environment variables, etc.

STRIPCONTROLD
    if set, tells papif that it should map control-d's to a line feed. Danger: this may cause problems with binary files.

MAPCRTOLF
    if set, tells papif that it should map carriage returns to line feeds. This option is useful when printing Macintosh files. (It is preferrable to make lwsrv do this mapping if possible). Danger: this may cause problems with binary files.

CAPPRINTERS
    a string containing the name of an alternate cap.printers file for mapping printer queue name to LaserWriter NBP network name.

JOBOUTPUT
    a string containing the name of a file to get a copy of the papif logging messages. This is useful when using lp and the TranScript interfaces under a System V style machine.

BANNER
    a string containing the name of a banner file other than ".banner". This is useful when using lp and the TranScript interfaces under a System V style machine.

DOACCT
    if set, turns on page accounting. No accounting will be done even if set unless an accounting file is specified as an argument to papif (e.g., the "af" field is set in /etc/printcap).

PSJOBHEADER
    if set, specifies a file that contains PostScript code to be sent to the printer before the print job. Uses include manipulating printer features such as duplex mode, paper tray control and so on (this option must be specified at compile time by enabling the PSJOBHEADER option at Configure time).

Line Printer Spooling System
Technically, an output filter is used to massage output from a filter. However, papof only accepts the banner from lpd and converts it to PostScript for use by the input filter.

An input filter takes certain types of input and has the responsibility for actually sending it to the printer. Common types of input are formatted text ("if"), graphics (plot(3x)) input ("gf"), etc. papif was originally designed as the "if" or formatted text input filter and hence its name. It can also be used in combination with other programs, such as those provided with Adobe's TranScript package that take a particular type of input and convert them into PostScript format by simply piping the output of those "filters" into papif. In other words, papif can be used as the "active" backend for various filters. Its role is equivalent to that of pscomm in the TranScript package.

Example printcap entries
A printcap entry for a system without TranScript would look something like:

      ps:LaserWriter:A sample LaserWriter printer:\ # printer name
	 :lp=/dev/ps:\			# spool device
	 :sd=/usr/spool/lpd/ps:\	# spool directory
	 :pl#72:pw#85:\		# page length and width
	 :sf:\				# suppress form feeds
	 :lf=/usr/adm/ps-errs:\	# log file
	 :af=/usr/adm/ps.acct:\	# accounting file
	 :if=/usr/local/lib/cap/ps:\	# input filter
	 :of=/usr/local/lib/cap/papof:	# output filter

The spool device (:lp=) is not used, but some systems may do locking on it, so it may need to be unique. Just create a unique null file. "/usr/local/lib/cap/ps" could be a copy of papif compiled with the defaults required or it could be a shell script as such:

	#!/bin/sh
	BANNERLAST=1
	PSTEXT=/usr/local/lib/ps/pstext
	export BANNERLAST PSTEXT
	# pass the printer name and the arguments lpd passed us
	/usr/local/cap/papif -P ps $*

papof is the supplied output filter. The accounting file and log file must be created by hand if accounting or logging is desired. The page length and width are probably only required if pstext is used.

A TranScript printer entry should be installed with the aid of TranScript. One point to be careful of is that TranScript's "psof" filter assumes that "sb" (or short banner) has been defined. papof works with "sb" on, but is designed for use without "sb" defined.

cap.printers format
Cap.printers is used to map UNIX printer queue names to LaserWriter NBP network names. It consists of a series of lines, each specifying a single mapping. Multiple lines may map the various aliases of a UNIX printer queue to the same NBP name. Lines beginning with the pound sign (#) are comment lines.

Each mapping line contains the "UNIX printer name" without spaces followed by an "=" character and the exact NBP entity name. There can be no extraneous spaces! Please note that due to a bug in the Apple "Namer" program, under certain conditions, a blank space may be added to the end of the name you set for the LaserWriter with that program. If that happens, this extra blank space must be included in the cap.printers entry (just before the ":"). It is best to use the CAP atlook program to confirm the exact printer NBP entity name. For example:
	ps=ALaserWriter:LaserWriter@SomeZone
See the sample cap.printers file in the papif distribution directory for more examples.

LP
papif should work with the appropriate shell script surrounding it under the UNIX System V "lp" spooling system. In particular, it is known to work under Release 1 of A/UX from Apple Computer. See the README file in the papif source directory for more information.

LOCAL CONFIGURATION

NOTES
papif TranScript is available under license from Adobe Systems Incorporated.

BUGS
papif has changed considerably since the idle code was added and the idle code may no longer work properly.

FILES
/etc/printcap
/etc/cap.printers	(location is settable)
.status	lpd status file
newstatus	papif status temporary file
.banner	lpd banner file

AUTHOR
Charlie C. Kim, User Services Group, Center for Computing Activities, Columbia University

SEE ALSO
CAP(3), CAP(8), printcap(8), lpd(8), lwsrv(8), atlook(1), transcript(8)