MAGICFILTER(5)							File Formats Manual						    MAGICFILTER(5)

NAME

       magicfilter - 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  mag-
       icfilter 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.  You need to have this for every printer, because even PostScript
	      capable printers need to run ghostscript to handle PDF files.

       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(HANDLE_TEXT,`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.

   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/share/printconf/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 end-
       ing 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/sbin/printers/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 "" 04

       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 is set to the values of the user, host and indent options passed to magicfilter.  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 avail-
	      able, 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 mul-
	      tiple 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).

HINTS

       Using the pipe facility together with zcat or gunzip lets you transparently 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.

BUGS

       Currently, there is no protection against the pipe or fpipe facilities going into an infinite loop.

AUTHOR

       H. Peter Anvin <hpa@zytor.com>, David Parsons <orc@pell.chi.il.us>

SEE ALSO

       printcap(5), lpr(8), dvips(1), grog(1), gs(1), gzip(1), troff(1).

February 2000							   Version 2.0.0						    MAGICFILTER(5)