MAGICFILTER(5)MAGICFILTER(5)NAMEmagicfilter - format of printer description files.
DESCRIPTION
The printer description files are simple m4 macro files that are merged
with a template-file inside magicfilter to produce a list of rules for
printing out files of various types.
PRINTER DESCRIPTION FILES
A printer description file provides macro definitions for magicfilter
to merge with its built-in configuration file. The macros that magic‐
filter 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 print‐
ing.
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 Lan‐
guage.
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 Ghost‐
Script. This (or PS_OPTIONS, if you're using some sort of gs
script) is needed to print most formats on non-postscript print‐
ers.
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 print‐
ing.
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 fil‐
ter 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 pro‐
cessing and output that is plain text. Also note that HAN‐
DLE_TEXT does not use the same sort of argument that PRINTER
does; PRINTER expects a command (like lpr -Pfoolp) while HAN‐
DLE_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 sec‐
tion 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 char‐
acter are ignored. A line may be continued onto the next line by end‐
ing the line in a backslash (\).
For ambiguous matches, the first match is used. Hence, the most spe‐
cific 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 suf‐
fix 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 facil‐
ity; 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 mes‐
sage 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 gen‐
erate 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 dae‐
mon 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 exter‐
nal 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 pro‐
grams 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 com‐
mand line as $FILE).
HINTS
Using the pipe facility together with zcat or gunzip lets you transpar‐
ently print compressed files.
The pbmplus or netpbm collections of image conversion utilities contain
a large number of very useful external filter programs.
You will probably want to examine the sample configuration files
included with the magicfilter distribution before creating your own.
Note that the .def files are processed by m4 so you need to pay atten‐
tion to what they contain if you write your own. In particular, you
should carefully avoid using constructs that look like m4 macros and
you need to use the escapes \{ for (, \} for ), \- for ', and \+ for `.
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.)
BUGS
Currently, there is no protection against the pipe or fpipe facilities
going into an infinite loop.
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.
The documentation for the reject action lies when it says that it
attempts to send mail to the person who sent the rejected job.
AUTHOR
H. Peter Anvin <hpa@zytor.com>, David Parsons <orc@pell.chi.il.us>
SEE ALSOprintcap(5), lpr(8), dvips(1), grog(1), gs(1), gzip(1), troff(1).
2002/12/14 Version 2.3.h MAGICFILTER(5)
