PRINTER DESCRIPTION FILES

A printer description file provides macro definitions for magicfilter to merge with its built-in configuration file. The macros that magicfilter needs are as follows

define(Vendor,`Vendor')dnl

This is the company that makes the printer in question (not needed for generic filters, like the postscript filters.)

define(Printer, `Printer')dnl

This is a short description of the printer. For a specific printer, it is the name of the printer (eg: 600 DPI LaserJet 4 series with Postscript ) and for a generic printer, it's a description of what the printer is (eg: 600 DPI PostScript-only printer )

define(DPI,`DPI')dnl

This is the dots per inch that the printer is capable of printing.

define(POSTSCRIPT,`true')dnl

This is set to true if the printer handles PostScript, false otherwise.

define(PCL,`true')dnl

This is set to true if the printer handles H-P PCL.

define(PJL,`true')dnl

This is set to true if the printer handles H-P Printer Job Language.

define(PCL5E,`true')dnl

This is set to true if the printer supports PCL5E.

define(DEVICE,`device')dnl

This is the device name to use when filtering through GhostScript. This (or PS_OPTIONS, if you're using some sort of gs script) is needed to print most formats on non-postscript printers.

define(TEXT,`false')dnl

Set this to false if your printer cannot handle text, but must have it formatted in some way. PostScript-only printers require this, and use pstext or enscript to format plain text for printing.

define(PRINTER,`command')dnl

This option makes magicfilter send all printer-ready output (see HANDLE_TEXT, below, for the exception to this rule) to command for printing instead of just dumping the printer-ready output to stdout. This is useful when you wish to use a networked printer but your printer server software doesn't allow you to put a filter on a remote printer.

define(HANDLE_TEXT,`action command')dnl

If the printer needs any special processing to do text, it will be set here. This is used on H-P printers, for example, to spit out PCL reset codes before printing out plain text. NOTE that HANDLE_TEXT overrides PRINTER -- this is so you can redirect output to different printer devices for output that needs processing and output that is plain text. Also note that HANDLE_TEXT does not use the same sort of argument that PRINTER does; PRINTER expects a command (like lpr -Pfoolp) while HANDLE_TEXT expects an action followed by a command (like filter 'printer reset' 'page flush'), and that the action must be one of filter, ffilter, cat, or pipe. Any other action is very likely to result in a printer filter that takes a lot of time to reject your printer jobs.

THE CONFIGURATION FILE

The configuration file is used by magicfilter to redirect various types of data to the various conversion utilities. The configuration file is fed to m4 along with the printer description file mentioned in the section above, and is parsed by magicfilter to figure out what can be printed to a file. The unformatted printer description file (/usr/local/etc/magicfilter.cf), or a internal default template is an m4 sourcefile that contains a sequence of lines of the form:

/pattern/ action/hint/ arguments

where the /pattern/ is compared against what file (1) reports as the filetype, action is what should be done with it, /hint/ (optionally) tells magicfilter what format the processed file is, and arguments are passed to the action.

Blank lines and lines with a hash mark (#) as the first nonblank character are ignored. A line may be continued onto the next line by ending the line in a backslash (\).

For ambiguous matches, the first match is used. Hence, the most specific match should always be placed first in the file. There is no default pattern -- if the file type is not matched, magicfilter will reject the print request. If you wish a default pattern, you can use an empty pattern to do something like:

// pipe /usr/local/libexec/magicfilter/textonly

To use Ed Lim's textonly program to print the file out after a little paranoia to make sure that it's not a binary.

FACILITIES

magicfilter provides the following options for the facility field in the configuration file:

cat [prefix [suffix]]

Copy the input to the output without any conversion, like the cat command. If the optional prefix and suffix strings are specified, they are transmitted to the printer immediately before and after the data itself. The prefix and suffix strings can include escape sequences like \e (escape) To specify a suffix without a prefix, specify an empty prefix string enclosed in double quotes (i.e. "").

text [prefix [suffix]]

Copy the input to the output, but add carriage return characters before every line feed and form feed character in the file, and a line feed-form feed sequence at end of file. The prefix and suffix arguments are treated the same way as for the cat facility; the suffix, if present, is added after the final line feed-form feed sequence.

postscript

Same as the text facility, except add an ASCII EOT (Ctrl-D) character to the end of the data. This lets a PostScript printer know that the end of the job has been reached. This is functionally equivalent to the command

text "" \004

ignore

Ignore the job; do not provide any output whatsoever.

reject message

Same as the ignore facility, but attempt to send an email message to the user who submitted the job to inform that a job has been rejected and why.

filter command

Run the given command, feeding it the input data, and sending the output data to the printer. The environment variables LPUSER, LPHOST, and LPINDENT are set to the values of the user, host and indent options passed to magicfilter. To get around the way some filters ( ghostscript) promiscuously mix output and error messages when they direct their output to stdout, setting the magic cookie ${FIFO} in the argument list of a filter ( for postscript, -sOutputFile=${FIFO}) will cause magicfilter to generate a fifo and copy from that fifo to stdout, redirecting the stdout from the filter to stderr instead. Since the command is fed to /bin/sh it may contain shell special characters, and the sequences $LPUSER, $LPHOST, and $LPINDENT can be used to access the values of the passed environment variables. If the lpd daemon on the system is LPRng, the following environment variables are also available, see the OPTIONS section for details: LPCLASS, LPFORMAT, LPJOB, LPCOPIES, BANNERNAME, PRINTER, LPQUEUE, LPACCT, and ZOPT.

pipe command

Same as the filter facility, except that the output data is fed back into magicfilter for reprocessing. This is used for external filter programs which themselves do not produce a format that the printer can accept, but which can be futher processed to obtain such a format.

ffilter command

fpipe command

Same as the filter and pipe facilities, respectively, except that the input is written to a temporary file before being fed to the filter program given by command. This is useful for programs which require seekable input, such as dvips, or which need to do multiple passes over an input file, such as grog. The environment variable FILE is set to the name of the temporary file (and, like the other ones, it can be accessed on the command line as $FILE).