Defining a filter

When adding a new filter, you must define the characteristics of its use. To do this, issue the lpfilter command with arguments that specify the values of the following filter characteristics:

• the name of the filter (that is, a command name)

• the types of input it will accept

• the types of output it will produce

• the types of printers to which it will send jobs

• the names of specific printers to which it will send jobs

• the type of the filter (whether it is a fast filter or a slow filter)

• options

See the ``Adding a filter to the print service'' section for more information.

Filter definitions can be stored in a file or entered directly on the command line and have the following format:

   Command: command-pathname [options]
   Input types: input-type-list
   Output types: output-type-list
   Printer types: printer-type-list
   Printers: printer-list
   Filter type: fast or slow
   Options: template-list

lpfilter arguments

Item	Default
Command:	(no default)
Input types:	any
Output types:	any
Printer types:	any
Printers:	any
Filter type:	slow
Options:	(no default)

Default values define a flexible filter, so you probably have to supply at least the input and output type(s). When you enter a list, you can separate the items in it with blanks or commas, unless it is a template-list; items in a template-list must be separated by commas.

Each of these characteristics is described in the following paragraphs.

• Command: The full path of the filter program. If there are any fixed options that the program always needs, include them here.

• Input types: The list of file content types that the filter can process. The print service doesn't impose a limit on the number of input types that can be accepted by a filter, but most filters can take only one. Several file types may be similar enough so that the filter can deal with them. You can use whatever names you like here, using a maximum of 14 alphanumeric characters and dashes (not underscores). Because the print service uses these names to match a filter with a file type, follow a consistent naming convention. For example, if more than one filter can accept the same input type, use the same name for that input type when you specify it for each filter. These names should be advertised to your users so they know how to identify the type of a file when submitting that file for printing.

• Output types: This is the list of file types that the filter can produce as output. For each input type the filter will produce a single output type; the output type may vary, however, from job to job. The names of the output types are restricted to 14 alphanumeric characters and dashes.

  These names should either match the types of printers you have on your system or match the input types handled by other filters. The print service groups filters together in a shell pipeline if it finds that several passes by different filters are needed to convert a file. Try to find a set of filters that takes (as input types) all the different files your users may want printed and converts those files directly into types your printers can handle.

• Printer types: A list of printer types into which the filter can convert files. For most filters this list will be identical to the list of output types, but it can be different.

  For example, you may have a printer that is given a single type for purposes of initialization (see the ``Printer types'' section), but which can recognize several different types of files. In essence, this printer has an internal filter that converts the various types into one with which it can handle. Thus, a filter may produce one of several output types that match the ``file types'' that the printer can handle. Mark filter as working with that printer type.

  As another example, you may have two different models of printers that are listed as accepting the same types of files. However, due to slight differences in manufacture, one printer deviates in the results it produces. You label the printers as being of different printer types, say A and B, where B is the one that deviates. You create a filter that adjusts files to account for the deviation produced by printers of type B. Because this filter is needed only for those printer types, you list it as working only on type B printers.

  For most printers and filters, you can leave this part of the filter definition blank.

• Printers: You may have some printers that, although they're of the correct type for a filter, are in other ways not adequate for the output that the filter will produce. For instance, you may want to dedicate one printer for fast turnaround; only files that the printer can handle without filtering will be sent to that printer. Other printers, of identical type, you allow to be used for files that may need extensive filtering before they can be printed. In this case, you would label the filter as working with only the latter group of printers.

  In most cases, a filter works with all printers that accept its output, so you can usually skip this part of the filter definition.

• Filter type: The print service recognizes ``fast'' filters and ``slow'' filters. Fast filters are labeled ``fast'' because they incur little overhead in preparing a file for printing and because they must have access to the printer when they run. A filter that is to detect printer faults has to be a fast filter. A filter that uses the PRINTER keyword as a filter option must be installed as a fast filter.

  Slow filters are filters that incur a lot of overhead in preparing a file and don't require access to a printer. The print service runs slow filters in the background, without tying up a printer. This allows files that don't need slow filtering to move ahead; printers will not be left idle while a slow filter works on a file if other files can be printed simultaneously.

  Slow filters that are invoked by modes (via the -y option), must be run on the computer where the print request was issued. The print service can't pass values for modes to server machines. It can, however, match a file content type (specified after the -T option of the lp command) to a content type on a server machine. Therefore, to activate special modes on a server machine, you must specify content types that will allow the print service to match input types and output types.

• Options: Options specify how different types of information is transformed into command line arguments to the filter command. This information may include specifications from a user (with the print request), the printer definition, and the specifications implemented by any filters used to process the request.

  There are 13 sources of information, each of which is represented by a ``keyword.'' Each option is defined in a ``template,'' a statement in the following format:

     keyword pattern=replacement
  

  This type of statement is interpreted by the print service to mean ``When the information referred to by keyword has the value matched by pattern, take the replacement string, replace any asterisks it contains with the pattern specified or expand any regular expressions it contains, and append the result to the command line.''

  The options specified in a filter definition may include none, all, or any subset of these 13 keywords. In addition, a single keyword may be defined more than once, if multiple definitions are required for a complete filter definition. See ``Defining options with templates''.

When you gathered enough information to define the characteristics of your filter, you are ready to run the lpfilter command, using your data as arguments. Because there are so many arguments and because some of them may need to be entered more than once (with different values), we recommend you record this information first in a separate file and edit it, if necessary. You can then use the file as input to the lpfilter command and avoid typing each piece of information separately.

Defining options with templates

A template is a statement in a filter definition that defines an option to be passed to the filter command based on the value of one of the characteristics of the filter. A filter definition may include more than one template. Multiple templates may be entered on a single line and separated with commas, or they may be entered on separate lines, preceded by the Options: prefix.

The format of a template is as follows:

   keyword pattern=replacement

Let's look at an example of how an option is defined for a particular filter. Suppose you want to have the print service scheduler assign print requests to filters on the basis of the following criteria:

• If the type of OUTPUT to be produced by the filter is impress, then pass the -I option to the filter.

• If the type of OUTPUT to be produced by the filter is postscript, then pass the -P option to the filter.

   Options: OUTPUT impress=-I, OUTPUT postscript=-P

   "Options: OUTPUT impress=-I"
   "Options: OUTPUT postscript=-P"

Template keywords

The following 13 keywords are available for defining Options in a filter definition:

Keyword definitions and examples

Characteristic	keyword	Possible patterns	Example
Content type (input)	INPUT	content-type	troff
Content type (output)	OUTPUT	content-type	postscript
Printer type	TERM	printer-type	att495
Printer name	PRINTER	printer-name	lp1
Character pitch	CPI	scaled-decimal	10
Line pitch	LPI	scaled-decimal	6
Page length	LENGTH	scaled-decimal	66
Page width	WIDTH	scaled-decimal	80
Pages to print	PAGES	page-list	1-5,13-20
Character set	CHARSET	character-set	finnish
Form name	FORM	form-name	invoice2
Number of copies	COPIES	integer	3
Special modes	MODES	mode	landscape

To find out which values to supply for each type of template (that is, for the pattern and replacement arguments for each keyword), consider the following:

• The values for the INPUT and OUTPUT templates come from the file type that needs to be converted by the filter and the output type that has to be produced by the filter, respectively. They'll each be a type registered with the filter.

• The value for the TERM template is the printer type.

• The value for the PRINTER template is the name of the printer that will print the final output.

• The values for the CPI, LPI, LENGTH, and WIDTH templates come from the user request, the form being used, or the default values for the printer.

• The value for the PAGES template is a list of pages to be printed. Typically, it is a comma-separated list of page ranges, each of which consists of a dash-separated pair of numbers or a single number (such as
  1-6,8,10 for pages 1 through 6, 8, and 10). However, whatever value was given in the -P option to a print request is passed unchanged.

• The value for the CHARSET template is the name of the character set to be used.

• The value for the FORM template is the name of the form requested by the -f option of the lp command.

• The value of the COPIES template determines the number of copies made of the file. If the filter uses this template, the print service will reduce to 1 the number of copies of the filtered file it will have printed, since this single copy will really be the multiple copies produced by the filter.

• The value of the MODES template comes from the -y option of the lp command (the command used to submit a print request). Because a user can specify several -y options, there may be several values for the MODES template. The values will be applied in the left-to-right order given by the user.

The replacement part of a template shows how the value of a template is given to the filter program. It is typically a literal option, sometimes with the place-holder included to show where the value goes. The pattern and replacement can also use the regular expression syntax of ed(1) for more complex conversion of user input options into filter options. All of the regular expression syntax of ed(1) is supported, including the \( . . . \) and \n constructions, which can be used to extract portions of the pattern for copying into the replacement, and the &, which can be used to copy the entire pattern into the replacement.

The following examples show how this works.

Example: col filter

Suppose you already added a filter called col with the following definition:

   Input types:     N37, Nlp, simple
   Output types:    simple
   Command:         /usr/bin/col
   Options:         TERM 450 = -b, MODES expand = -x
   Options:         INPUT simple = -p -f

After you have ``registered'' this definition with the Print Service by entering it as input with the lpfilter command, users' print requests will be handled as follows:

• If a user enters the command
  
  lp -y expand report.dec10

  the filter command will be run with the following arguments:
  
  /usr/bin/col -x -p -f

• If a user enters the command
  
  lp -T N37 -y expand report.dec10

  the filter command will be run with the following arguments:
  
  /usr/bin/col -x

  Qualifier: The default printer is not of type 450.

• If a user enters the command
  
  lp -y expand -T 450 report.dec10

  the filter command will be run with the following arguments:
  
  /usr/bin/col -b -x

Example: dpost filter

The filter program is called /usr/lib/lp/postscript/dpost. It takes one input type, troff, produces an output type called postscript and works with any printer of type PS (for PostScript). You've decided that your users need give just the abbreviations port and land when they ask for the paper orientation to be portrait mode and landscape mode, respectively. Because these options are not intrinsic to the print service, users must specify them using the -y option to the lp command.

The filter definition would look like this:

   Input types: troff
   Output types: postscript
   Printer types: PS
   Filter type: slow
   Command: /usr/lib/lp/postscript/dpost
   Options: LENGTH * = -l*
   Options: MODES portrait = -op, MODES land = -ol

A user submitting a file of type troff for printing on a PostScript printer (type PS), with requests for landscape orientation and a page length of 60 lines, would enter the following command:

lp -T troff -o length=60 -y land -d any

Then this filter would be invoked by the print service to convert the file as follows:

/usr/lib/lp/postscript/dpost -l60 -ol -pl

Example: option template

You add the following option template to the previous example:

   Options:  MODES group\=\([1-9]\) = -n\l

into filter options

-nnumber

So if a user gives the following command

lp -y group=4

the dpost command would include the following option:

-n4

For additional examples, run the command

/usr/sbin/lpfilter -f filter -l

where filter is the name of the factory-installed PostScript filters. (For a list of PostScript filters, see ``PostScript printers''.)