.TH MAGICFILTER 5 "Version @VERSION@" "2002/12/14" \" -*- nroff -*-
.SH NAME
magicfilter \- format of printer description files.

.SH DESCRIPTION
The
printer description files are simple m4 macro files that are
merged with a template-file inside
.B magicfilter
to produce a list of rules for printing out files of various
types.

.SS PRINTER DESCRIPTION FILES
A printer description file provides macro definitions for
.B magicfilter
to merge with its built-in configuration file.  The macros that
.B magicfilter
needs are as follows
.IP
.TP
define(Vendor,`Vendor')dnl
This is the company that makes the printer in question (not needed
for generic filters, like the postscript filters.)
.TP
define(Printer, `Printer')dnl
This is a short description of the printer.  For a specific printer,
it is the name of the printer
.I (eg: "600 DPI LaserJet 4 series with Postscript" )
and for a generic printer, it's a description of what the printer is
.I (eg: "600 DPI PostScript-only printer" )
.TP
define(DPI,`DPI')dnl
This is the dots per inch that the printer is capable of printing.
.TP
define(POSTSCRIPT,`true')dnl
This is set to true if the printer handles PostScript, false otherwise.
.TP
define(PCL,`true')dnl
This is set to true if the printer handles H-P PCL.
.TP
define(PJL,`true')dnl
This is set to true if the printer handles H-P Printer Job Language.
.TP
define(PCL5E,`true')dnl
This is set to true if the printer supports PCL5E.
.TP
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.
.TP
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.
.TP
define(PRINTER,`command')dnl
This option makes
.B magicfilter
send all printer-ready output (see HANDLE_TEXT, below, for the
exception to this rule) to
.I 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.
.TP
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.
.B 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
.B does not
use the same sort of argument that
PRINTER 
does;  
PRINTER
expects a command (like 
.I lpr
.IR -Pfoolp )
while
HANDLE_TEXT
expects an action followed by a command (like
.B filter
.IR 'printer\ reset'\ 'page\ flush' ),
and that the
.B action
must be one of 
.IR filter ,
.IR ffilter ,
.IR cat ,
or
.IR pipe .
Any other action is very likely to result in a printer filter that
takes a lot of time to reject your printer jobs.
.SS THE CONFIGURATION FILE
The configuration file is used by
.B 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
.B magicfilter
to figure out what can be printed to a file.  The unformatted printer
description file
.IR (@confdir@/magicfilter.cf) ,
or a internal default template is an m4 sourcefile that
contains a sequence of lines of the form:
.PP
.I "/pattern/	action/hint/	arguments"
.PP
where the
.I /pattern/
is compared against what
.B file (1)
reports as the filetype,
.I action
is what should be done with it,
.I /hint/
(optionally) tells magicfilter what format the processed file
is, and
.I 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 (\e).

For ambiguous matches, the first match is used.  Hence, the most
specific match should always be placed first in the file.  There is
.B no
default pattern -- if the file type is not matched,
.B magicfilter
will reject the print request.  If you wish a default pattern, you
can use an empty pattern to do something like:
.PP
.NF
//	pipe	@filterdir@/textonly
.FI
.PP
To use Ed Lim's
.B textonly
program to print the file out after a little paranoia to make sure
that it's not a binary.
.SS FACILITIES
.B magicfilter
provides the following options for the
.I facility
field in the configuration file:
.TP
\fBcat\fR [\fIprefix\fR [\fIsuffix\fR]]
Copy the input to the output without any conversion, like the
.B cat
command.  If the optional
.I prefix
and
.I suffix
strings are specified, they are transmitted to the printer immediately
before and after the data itself.  The
.I prefix
and
.I suffix
strings can include escape sequences like \ee (escape)
To
specify a
.I suffix
without a
.IR prefix ,
specify an empty
.I prefix
string enclosed in double quotes (i.e. "").
.TP
\fBtext\fR [\fIprefix\fR [\fIsuffix\fR]] 
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
.I prefix
and
.I suffix
arguments are treated the same way as for the
.B cat
facility; the
.IR suffix ,
if present, is added after the final line feed-form feed sequence.
.TP
\fBpostscript\fR
Same as the
.B 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
.TP
.I " "
\fBtext\fR "" \e004
.TP
\fBignore\fR
Ignore the job; do not provide any output whatsoever.
.TP
\fBreject\fR \fImessage\fR
Same as the
.B 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.
.TP
\fBfilter\fR \fIcommand\fR
Run the given
.IR command ,
feeding it the input data, and sending the output data to the printer.
The environment variables
.BR LPUSER ,
.BR LPHOST ,
and
.B LPINDENT
are set to the values of the user, host and indent options passed to
.BR magicfilter .
To get around the way some filters (
.IR ghostscript )
promiscuously mix output and error
messages when they direct their output to stdout, setting the magic
cookie
.B ${FIFO}
in the argument list of a filter (
for postscript, 
.BI -sOutputFile=${FIFO} )
will cause
.B magicfilter
to generate a fifo and copy from that fifo to stdout,
redirecting the stdout from the filter to stderr instead.
Since the
.I command
is fed to
.I /bin/sh
it may contain shell special characters, and the sequences
.BR $LPUSER ,
.BR $LPHOST ,
and
.B $LPINDENT
can be used to access the values of the passed environment variables.
If the
.B lpd
daemon on the system is LPRng, the following environment variables are also
available, see the
.B OPTIONS
section for details:
.BR LPCLASS ,
.BR LPFORMAT ,
.BR LPJOB ,
.BR LPCOPIES ,
.BR BANNERNAME ,
.BR PRINTER ,
.BR LPQUEUE ,
.BR LPACCT ,
and
.BR ZOPT .
.TP
\fBpipe\fR \fIcommand\fR
Same as the
.B filter
facility, except that the output data is fed back into
.B 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.
.TP
\fBffilter\fR \fIcommand\fR
.sp -0.5
.TP
\fBfpipe\fR \fIcommand\fR
Same as the
.B filter
and
.B pipe
facilities, respectively, except that the input is written to a
temporary file before being fed to the filter program given by
.IR command .
This is useful for programs which require seekable input, such as
.BR dvips ,
or which need to do multiple passes over an input file, such as
.BR grog .
The environment variable
.B FILE
is set to the name of the temporary file (and, like the other ones, it
can be accessed on the command line as
.BR $FILE ).
.SH HINTS
Using the
.B pipe
facility together with
.B zcat
or
.B gunzip
lets you transparently print compressed files.
.PP
The
.B pbmplus
or
.B netpbm
collections of image conversion utilities contain a large number of
very useful external filter programs.
.PP
You will probably want to examine the sample configuration files
included with the
.B magicfilter
distribution before creating your own.
.PP
Note that the
.B .def
files are processed by
.B m4
so you need to pay attention to what they contain if you write
your own.
In particular, you should carefully avoid using constructs that
look like
.B m4
macros
and you need to use the escapes
.I \\\\{
for
.IR ( ,
.I \\\\}
for
.IR ) ,
.I \\\\-
for
.IR ' ,
and
.I \\\\+
for
.IR ` .
Failing to do that may result in unexpected things happening to
your printer (most likely nothing printing with no error messages
at all, but it's equally possible that the printer will print
something you don't particularly want it to print.)

.SH BUGS
Currently, there is no protection against the
.B pipe
or
.B fpipe
facilities going into an infinite loop.
.PP
.B Magicfilter
is developed with some fairly ancient and creaky printers, so many of the
fancier features supported here are less well tested than I would like.
.PP
The documentation for the
.B reject
action lies when it says that it attempts to send mail to the person
who sent the rejected job.
.SH AUTHOR
H. Peter Anvin <hpa@zytor.com>, David Parsons <orc@pell.chi.il.us>
.SH SEE ALSO
.BR printcap (5),
.BR lpr (8),
.BR dvips (1),
.BR grog (1),
.BR gs (1),
.BR gzip (1),
.BR troff (1).
