   This document describes GNU a2ps 4.13, a converter from various
formats, included text, to PostScript converter, with pretty-printing
abilities.

   Copyright (C) 1988-1993 Miguel Santana Copyright (C) 1995-2000 Akim
Demaille, Miguel Santana

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "Copying" is included exactly as in the
original, and provided that the entire resulting derived work is
distributed under the terms of a permission notice identical to this
one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the author.

Input Options
-------------

 - Option: -a[PAGE RANGE]
 - Option: --pages[=PAGE RANGE]
     With no argument, print all the page, otherwise select the pages to
     print.  PAGE RANGE is a list of interval, such as `-a1': print
     only the first page, `-a-3,4,6,10-': print the first 3 pages, page
     4 and 6, and all the page after 10 (included).  Giving `toc'
     prints the table of content whatever its page number is.

     The pages referred to are the _input_ pages, not the output pages,
     that is, in `-2', printing with `-a1' will print the first virtual
     page, i.e., you will get half the page filled.

     Note that page selection does work with the delegations (see
     Your Delegations).

 - Option: -c
 - Option: --truncate-lines=BOOLEAN
     Cut lines too large to be printed inside the borders.  The maximum
     line size depends on format and font size used and whether line
     numbering is enabled.

 - Option: -i
 - Option: --interpret=BOOLEAN
     interpret tab and ff chars.  This means that `^L' jumps to a new
     (virtual) pages, `tab' advances to the next tabulation.

 - Option: --end-of-line=TYPE
     Specify what sequence of characters denotes the end of line.  TYPE
     can be:
    `n'
    `unix'
          `\n'.

    `r'
    `mac'
          `\r'.

    `nr'
          `\n\r'.  As far as we know, this type of end-of-line is not
          used.

    `pc'
    `rn'
          `\r\n'. This is the type of end-of-line on MS-DOS.

    `any'
    `auto'
          Any of the previous cases. This last case prevents the bad
          surprises with files from PC (trailing `^M').

 - Option: -X KEY
 - Option: --encoding=KEY
     Use the input encoding identified by KEY.  See Some Encodings,
     and the result of `a2ps --list=encodings' to know what encodings
     are supported.  Typical values are `ASCII', `latin1'... `latin6',
     `isoN' etc.

 - Option: --stdin=FILENAME
     Give the name FILENAME to the files read through the standard
     input.

 - Option: -t NAME
 - Option: --title=NAME
     Give the name NAME to the document.  Escapes can be used (see
     Escapes).

     This is used for instance in the name given to the document from
     within the PostScript code (so that `Ghostview' and others can
     display a file with its real title, instead of just the PostScript
     file name).

     It is *not* the name of the output.  It is just a logical title.

 - Option: --prologue=PROLOGUE
     Use PROLOGUE as the PostScript prologue for a2ps.  PROLOGUE must
     be in a file named `PROLOGUE.pro', which must be in a directory of
     your library path (see Library Files).  Available prologues
     are:

    `bold'
          This style is meant to replace the old option `-b' of a2ps
          4.3.  It is a copy of the black and white prologue, but in
          which all the fonts are in Bold.

    `bw'
          Style is plain: pure black and white, with standard fonts.

    `color'
          Colors are used to highlight the keywords.

    `diff'
          This style is meant to be used with the `udiff', `wdiff'
          style sheets, to underline the differences.  New things are
          in bold on a diff background, while removed sequences are in
          italic.

    `fixed'
          This style uses exclusively fixed size fonts.  You should use
          this style if you want the tabulations to be properly printed.

          There are no means to use a fixed size Symbol font, therefore
          you should not use the heavy highlighting style.

    `gray'
          Gray background is used for comments and labels.

    `gray2'
          Black background is used for comments and labels.

    `matrix'
          The layout is the same as `bw', but alternating gray and
          white lines.  There are two macros defining the behavior:
          `pro.matrix.cycle' defines the length of the cycle (number of
          white and gray lines).  It defaults to 6.  `pro.matrix.gray'
          defines the number of gray lines.  Default is 3.

    `ul'
          This style uses bold faces and underlines, but never italics.
          This is particularly meant for printing formatted man pages.

 - Option: --print-anyway=BOOLEAN
     force binary printing.  By default, the whole print job is stopped
     as soon as a binary file is detected.  To detect such a file we
     make use of a very simple heuristic: if the first sheet of the
     file contains more than 40% of non-printing characters, it's a
     binary file.  a2ps also asks `file(1)' what it thinks of the type
     of the file.  If `file(1)' answers `data', the file will also be
     considered as binary, hence not printed.

 - Option: -Z
 - Option: --delegate=BOOLEAN
     Enable delegation of some files to delegated applications.  If
     delegating is on, then a2ps will _not_ process the file by itself,
     but will call an application which handles the file in another
     way.  If delegation is off, then a2ps will process _every_ file
     itself.

     Typically most people don't want to pretty-print a PostScript
     source file, but want to print what describes that file.  Then set
     the delegations on.

     See Your Delegations for information on delegating, and
     option `--list=delegations' for the applications your a2ps knows.

 - Option: --toc[=FORMAT]
     Generate a Table of Contents, which FORMAT is an escape (see
     Escapes) processed as a PreScript file (see PreScript).  If
     no FORMAT is given (i.e., you wrote `--toc'), use the default
     table of contents shape (`#{toc}').  If the given format is empty
     (i.e., you wrote `--toc='), don't issue the table of contents.

     Note that it is most useful to define a variable (see Your Variables),
     for instance, in a configuration file:

          Variable: toc.mine \
          \\Keyword{Table of Content}\n\
          #-1!f\
          |$2# \\keyword{$-.20n} sheets $3s< to $3s> ($2s#) \
          pages $3p<-$3p> $4l# lines\n||\
          \\Keyword{End of toc}\n

     and to give that variable as argument to `--toc': `a2ps *.c
     --toc=#{toc.mine}'.

     Note too that you can generate only the table of content using
     `--pages':
          a2ps *.c --toc -atoc

Pretty Printing Options
-----------------------

   These options are related to the pretty printing features of a2ps.

 - Option: --highlight-level=LEVEL
     Specify the LEVEL of highlighting.  LEVEL can be
    `none'
          no highlighting

    `normal'
          regular highlighting

    `heavy'
          even more highlighting.  See the documentation of the style
     sheets (`--list=style-sheets') for a description of `heavy'
     highlighting.

 - Option: -g
     Alias for `--highlight-level=heavy'.

 - Option: -E [LANGUAGE]
 - Option: --pretty-print[=LANGUAGE]
     With no arguments, set automatic style selection on.  Otherwise,
     set style to LANGUAGE.  Note that setting LANGUAGE to `plain'
     turns off pretty-printing.  See Known Style Sheets, and the
     output of `--list=style-sheets' for the available style sheets.

     If LANGUAGE is `KEY.ssh', then don't look in the library path, but
     use the file `KEY.SSH'.  This is to ease debugging non installed
     style sheets.

 - Option: --strip-level=NUM
     Depending on the value of NUM:
    `0'
          everything is printed;

    `1'
          regular comments are not printed

    `2'
          strong comments are not printed

    `3'
          no comment is printed.

     This option is valuable for instance in `java' in which case strong
     comments are the so called documentation comments, or in `SDL' for
     which some graphical editors pollutes the specification with
     internal data as comments.

     Note that the current implementation is not satisfactory: some
     undesired blank lines remain.  This is planed to be fixed.

Output Options
--------------

   These are the options to specify what you want to do out of what
a2ps produces.  Only a single destination is possible at a time, i.e.,
if ever there are several options `-o', `-P' or `-d', the last one is
honored.

 - Option: -o FILE
 - Option: --output=FILE
     leave output to file FILE.  If FILE is `-', leave output to the
     standard output.

 - Option: --version-control=TYPE
     to avoid loosing a file, a2ps offers backup services.  This is
     enabled when the output file already exists, is regular (that is,
     no backup is done on special files such as `/dev/null'), and is
     writable (in this case, disabling version control makes a2ps fail
     the very same way as if version control was disabled: permission
     denied).

     The type of backups made can be set with the `VERSION_CONTROL'
     environment variable, which can be overridden by this option.  If
     `VERSION_CONTROL' is not set and this option is not given, the
     default backup type is `existing'.  The value of the
     `VERSION_CONTROL' environment variable and the argument to this
     option are like the GNU `Emacs' `version-control' variable; they
     also recognize synonyms that are more descriptive.  The valid
     values are (unique abbreviations are accepted):
    `none'
    `off'
          Never make backups (override existing files).

    `t'
    `numbered'
          Always make numbered backups.

    `nil'
    `existing'
          Make numbered backups of files that already have them, simple
          backups of the others.

    `never'
    `simple'
          Always make simple backups.

 - Option: --suffix=SUFFIX
     The suffix used for making simple backup files can be set with the
     `SIMPLE_BACKUP_SUFFIX' environment variable, which can be
     overridden by this option.  If neither of those is given, the
     default is `~', as it is in `Emacs'.

 - Option: -P NAME
 - Option: --printer=NAME
     send output to printer NAME.  See item `Printer:' and `Unknown
     printer:' in Your Printers and results of option
     `--list=defaults' to see the bindings between printer names and
     commands.

     It is possible to pass additional options to `lpr' or `lp' via the
     variable `lp.options', for more information see Pass Options to lpr.

 - Option: -d
     send output to the default printer. See item `DefaultPrinter:' in
     Your Printers.

PostScript Options
------------------

   The following options are related only to variations you want to
produce onto a PostScript output.

 - Option: --ppd[=KEY]
     With no argument, set automatic PPD selection, otherwise set the
     PPD to KEY.  FIXME: what to read.

 - Option: -n NUM
 - Option: --copies=NUM
     print NUM copies of each page

 - Option: -s DUPLEX-MODE
 - Option: --sides=DUPLEX-MODE
     Specify the number of sheet sides, or, more generally, the Duplex
     mode (see Glossary). The valid values for DUPLEX-MODE are:
    `1'
    `simplex'
          One page per sheet.

    `2'
    `duplex'
          Two pages per sheet, DuplexNoTumble mode.

    `tumble'
          Two pages per sheet, DuplexTumble mode.  Not only does this
     option require Duplex from the printer, but it also enables duplex
     features from a2ps (e.g., the margin changes from front pages to
     back pages etc.).

 - Option: -S KEY[:VALUE]
 - Option: --setpagedevice=KEY[:VALUE]
     Pass a page device definition to the generated PostScript output.
     If no VALUE is given, KEY is removed from the definitions.  Note
     that several `--setpagedevice' can be accumulated.

     For example, command

          ubu $ a2ps -SDuplex:true -STumble:true NEWS
          [NEWS (plain): 15 pages on 8 sheets]
          [Total: 15 pages on 8 sheets] sent to the default printer

     prints file `report.pre' in duplex (two sides) tumble (suitable for
     landscape documents).  This is also valid for delegated files:
          a2ps -SDuplex:true -STumble:true a2ps.texi

     Page device operators are implementation dependent but they are
     standardized.  See Page Device Options, for details.

 - Option: --statusdict=KEY[:VALUE]
 - Option: --statusdict=KEY[::VALUE]
     Pass a statusdict definition to the generated PostScript output.
     `statusdict' operators and variables are implementation dependent;
     see the documentation of your printer for details.  See
     Statusdict Options, for details.  Several `--statusdict' can be
     accumulated.

     If no VALUE is given, KEY is removed from the definitions.

     With a single colon, pass a call to an operator, for instance:

          a2ps --statusdict=setpapertray:1 quicksort.c

     prints file `quicksort.c' by using paper from the paper tray 1
     (assuming that printer supports paper tray selection).

     With two colons, define variable KEY to equal VALUE.  For instance:

          a2ps --statusdict=papertray::1 quicksort.c

     produces

            /papertray 1 def

     in the PostScript.

 - Option: -k
 - Option: --page-prefeed
     enable page prefeeding.  It consists in positioning the sheet in
     the printing area while the PostScript is interpreted (instead of
     waiting the end of the interpretation of the page before pushing
     the sheet).  It can lead to an significant speed up of the
     printing.

     a2ps quotes the access to that feature, so that non supporting
     printers won't fail.

 - Option: -K
 - Option: --no-page-prefeed
     disable page prefeeding.

Escapes
=======

   The escapes are some sequences of characters that will be replaced
by their values.  They are very much like variables.

Use of Escapes
--------------

   They are used in several places in a2ps:
_Page markers_
     Headers, footers, titles and the water mark (see Headings Options),
     in general to print the name of file, page number etc.
     On a new sheet a2ps first draws the water mark, then the content
     of the first page, then the frame of the first page, (ditto with
     the others), and finally the sheet header and footers.  This order
     must be taken into account for some escapes (e.g., `$l.', `$l^').

_Named output_
     To specify the generic name of the file to produce, or how to
     access a printer (see Your Printers).

_Delegation_
     To specify the command associated to a delegation (see Your Delegations).

_Table of Content_
     To specify an index/table of content printed at the end of the job.

_Variables in PostScript prologue_
     To allow the user to change some parameters to your prologues
     (see Designing PostScript Prologues).

General Structure of the Escapes
--------------------------------

   All format directives can also be given in format

   ESCAPE WIDTH DIRECTIVE

where
ESCAPE
     In general
    `%'
          escapes are related to general information (e.g., the current
          date, the user's name etc.),

    `#'
          escapes are related to the output (e.g., the output file
          name) or to the options you gave (e.g., the number of virtual
          pages etc.), or to special constructions (e.g., enumerations
          of the files, or tests etc.),

    `$'
          escapes are related to the current input file (e.g., its name,
          its current page number etc.),

    `\'
          introduces classical escaping, or quoting, sequences (e.g.,
          `\n', `\f' etc.).

WIDTH
     Specifies the width of the column to which the escape is printed.
     There are three forms for WIDTH
    `+PADDINGINTEGER'
          the result of the expansion is prefixed by the character
          PADDING so that the whole result is as long as INTEGER.  For
          instance `$+.10n' with a file name `$n'=`foo.c' gives
          `.....foo.c'.

          If no PADDING is given, ` ' (white space) is used.

    `-PADDINGINTEGER'
          Idem as above, except that completion is done on the left:
          `$+.10n' gives `foo.c.....'.

    `INTEGER'
          which is a short cut for `+INTEGER'. For example, escape
          `$5P' will expand to something like `   12'.

DIRECTIVE
     See Available Escapes.

Available Escapes
-----------------

   Supported escapes are:
`\\'
     character `\'

`\%'
     character `%'

`\$'
     character `$'

`\#'
     character `#'

`#?COND|IF_TRUE|IF_FALSE|'
     this may be used for conditional assignment.  The separator
     (presented here as `|') may be any character.  IF_TRUE and
     IF_FALSE may be defined exactly the same way as regular headers,
     included escapes and the `#?' construct.

     The available tests are:
    `#?1'
    `#?2'
    `#?3'
          true if tag 1, 2 or 3 is not empty.  See item `$t1' for
          explanation.

    `#?d'
          true if Duplex printing is requested (`-s2').

    `#?j'
          true if bordering is asked (`-j').

    `#?l'
          true if printing in landscape mode.

    `#?o'
          true if only one virtual page per page (i.e., `#v' is 1).

    `#?p'
          a page range has been specified (i.e., `#p' is not empty).

    `#?q'
          true if a2ps is in quiet mode.

    `#?r'
          true if major is rows (`--major=rows').

    `#?v'
          true if printing on the back side of the sheet (verso).

    `#?V'
          true if verbosity level includes the `tools' flag (see
          Global Options. option `--verbosity').

`#!KEY|IN|BETWEEN|'
     Used for enumerations.  The separator (presented here as `|') may
     be any character.  IN and BETWEEN are escapes.

     The enumerations may be:
    `#!$'
          enumeration of the command line options.  In this case IN in
          never used, but is replaced by the arguments.

    `#!f'
          enumeration of the input files in the other they were given.

    `#!F'
          enumeration of the input files in the alphabetical order of
          their names.

    `#!s'
          enumeration of the files appearing in the current sheet.

     For instance, the escapes `The files printed were: #!f|$n|, |.'
     evaluated with input `a2ps NEWS main.c -o foo.ps', gives `The
     files printed were: NEWS, main.c.'.

     As an exception, `#!' escapes use the WIDTH as the maximum number
     of objects to enumerate if it is positive, e.g., `#10!f|$n|, |'
     lists only the ten first file names.  If WIDTH is negative, then
     it does not enumerate the -WIDTH last objects (e.g., `#-1!f|$n|,
     |' lists all the files but the last).

`${VAR}'
     value of the environment variable VAR if defined, nothing
     otherwise.

`${VAR:-WORD}'
     if the environment variable VAR is defined, then its value,
     otherwise WORD.

`${VAR:+WORD}'
     if the environment variable VAR is defined, then WORD, otherwise
     nothing.

`$[NUM]'
     value of the NUMth argument given on the command line.  Note that
     $[0] is the name under which a2ps has been called.

`#{KEY}'
     expansion of the value of the variable KEY if defined, nothing
     otherwise (see Your Variables)

`#{KEY:-WORD}'
     if the variable VAR is defined, then the expansion of its,
     otherwise WORD.

`#{KEY:+WORD}'
     if the variable VAR is defined, then WORD, otherwise nothing.

`#.'
     the extension corresponding to the current output language (e.g.
     `ps').

`%*'
     current time in 24-hour format with seconds `hh:mm:ss'

`$*'
     file modification time in 24-hour format with seconds `hh:mm:ss'

`$#'
     the sequence number of the current input file

`%#'
     the total number of files

`%a'
     the localized equivalent for `Printed by USER NAME'.  USER NAME is
     obtained from the variable `user.name' (see Predefined Variables).

`%A'
     the localized equivalent for `Printed by USER NAME from HOST
     NAME'. The variables `user.name' and `user.host' are used (see
     Predefined Variables).

`%c'
     trailing component of the current working directory

`%C'
     current time in `hh:mm:ss' format

`$C'
     file modification time in `hh:mm:ss' format

`%d'
     current working directory

`$d'
     directory part of the current file (`.' if the directory part is
     empty).

`%D'
     current date in `yy-mm-dd' format

`$D'
     file modification date in `yy-mm-dd' format

`%D{STRING}'
     format current date according to STRING with the `strftime(3)'
     function.

`$D{STRING}'
     format file's last modification date according to STRING with the
     `strftime(3)' function.

`%e'
     current date in localized short format (e.g., `Jul 4, 76' in
     English, or `14 Juil 89' in French).

`$e'
     file modification date in localized short format.

`%E'
     current date in localized long format (e.g., `July 4, 76' in
     English, or `Samedi 14 Juillet 89' in French).

`$E'
     file modification date in localized long format.

`$f'
     full file name (with directory and suffix).

`\f'
     character `\f' (`form feed').

`#f0'
`#f9'
     ten temporary file names.  You can do anything you want with them,
     a2ps removes them at the end of the job.  It is useful for the
     delegations (see Your Delegations) and for the printer
     commands (see Your Printers).

`%F'
     current date in `dd.mm.yyyy' format.

`$F'
     file modification date in `dd.mm.yyyy' format.

`#h'
     medium height in PostScript points

`$l^'
     top most line number of the current page

`$l.'
     current line number.  To print the page number and the line
     interval in the right title, use `--right-title="$q:$l^-$l."'.

`$l#'
     number of lines in the current file.

`%m'
     the host name up to the first `.' character

`%M'
     the full host name

`\n'
     the character `\n' (`new line').

`%n'
     shortcut for the value of the variable `user.login' (see
     Predefined Variables).

`$n'
     input file name without the directory part.

`%N'
     shortcut for the value of the variable `user.name' (see
     Predefined Variables).

`$N'
     input file name without the directory, and without its suffix
     (e.g., on `foo.c', it will produce `foo').

`#o'
     name of the output, before substitution (i.e., argument of `-P',
     or of `-o').

`#O'
     name of the output, after substitution.  If output goes to a file,
     then the name of the file.  If the output is a symbolic printer
     (see Your Printers), the result of the evaluation.  For
     instance, if the symbolic printer `file' is defined as `> $n.%.',
     then `#O' returns `foo.c.ps' when printing `foo.c' to PostScript.
     `#o' would have returned `file'.

`#p'
     the range of the page to print from this page.  For instance if
     the user asked `--pages=1-10,15', and the current page is 8, then
     `#p' evaluates to `1-3,8'.

`$p^'
     number of the first page of this file appearing on the current
     sheet.  Note that `$p.', evaluated at the end of sheet, is also
     the number of the last page of this file appearing on this sheet.

`$p-'
     interval of the page number of the current file appearing on the
     current sheet.  It is the same as `$p^-$p.', if `$p^' and `$p.'
     are different, otherwise it is equal to `$p.'.

`%p.'
     current page number

`$p.'
     page number for this file

`%p#'
     total number of pages printed

`$p#'
     number of pages of the current file

`$p<'
     number of the first page of the current file

`$p>'
     number of the last page of the current file

`%q'
     localized equivalent for `Page %p.'

`$q'
     localized equivalent for `Page $p.'

`%Q'
     localized equivalent for `Page %p./%p#'

`$Q'
     localized equivalent for `Page $p./$p#'

`$s<'
     number of the first sheet of the current file

`%s.'
     current sheet number

`$s.'
     sheet number for the current file

`$s>'
     number of the last sheet of the current file

`%s#'
     total number of sheets

`$s#'
     number of sheets of the current file

`%t'
     current time in 12-hour am/pm format

`$t'
     file modification time in 12-hour am/pm format

`$t1'
`$t2'
`$t3'
     Content of tag 1, 2 and 3. Tags are pieces of text a2ps fetches in
     the files, according to the style.  For instance, in `mail-folder'
     style, tag 1 is the title of the mail, and tag 2 its author.

`%T'
     current time in 24-hour format `hh:mm'

`$T'
     file modification time in 24-hour format `hh:mm'

`#v'
     number of virtual sheets

`%V'
     the version string of a2ps.

`#w'
     medium width in PostScript points

`%W'
     current date in `mm/dd/yy' format

`$W'
     file modification date in `mm/dd/yy' format

Configuration Files
*******************

   a2ps reads several files before the command line options.  In the
order, they are:
  1. the system configuration file (usually `/usr/local/etc/a2ps.cfg')
     unless you have defined the environment variable `A2PS_CONFIG', in
     which case a2ps reads the file it points to;

  2. the user's home configuration file (`$HOME/.a2ps/a2psrc')

  3. the local file (`./.a2psrc')

   Because a2ps needs architecture dependent information (such as the
local `lpr' command) and architecture independent information (such as
the type of your printers), users have found useful that `a2ps.cfg' be
dedicated to architecture dependent information.  A sub configuration
file, `a2ps-site.cfg' (see Including Configuration Files) is
included from `a2ps.cfg'.

   The file `a2ps.cfg' is updated when you update a2ps, while
`a2ps-site.cfg' is not, to preserve local definitions.

   In the configuration files, empty lines and lines starting with `#'
are comments.

   The other lines have all the following form:
     TOPIC: ARGUMENTS

where TOPIC: is a keyword related to what you are customizing, and
ARGUMENTS the customization.  ARGUMENTS may be spread on several lines,
provided that the last character of a line to continue is a `\'.

   In the following sections, each TOPIC: is detailed.

Including Configuration Files
=============================

 - Configuration Setting: Include: FILE
     Include (read) the configuration FILE.  if FILE is a relative path
     (i.e., it does not start with `/'), then it is relatively to the
     current configuration file.

   This is especially useful for the site specific configuration file
`etc/a2ps.cfg': you may tune your printers etc. in a separate file for
easy upgrade of a2ps (and hence of its configuration files).

Your Library Path
=================

   To define the default library path, you can use:

 - Configuration Setting: LibraryPath: PATH
     Set the library path the PATH.

 - Configuration Setting: AppendLibraryPath: PATH
     Add PATH at the end of the current library path.

 - Configuration Setting: PrependLibraryPath: PATH
     Add PATH at the beginning of the current library path.

   Note that for users configuration files, it is better not to set the
library path, because the system's configuration has certainly been
built to cope with your system's peculiarities.  Use
`AppendLibraryPath:' and `PrependLibraryPath:'.

Your Default Options
====================

 - Configuration Setting: Options: OPTIONS+
     Give a2ps a list of command line options. OPTIONS+ is any sequence
     of regular command line options (see Invoking a2ps).

     It is the correct way to define the default behavior you expect
     from a2ps.  If for instance you want to use `Letter' as medium,
     then use:

          Options: --medium=Letter

     It is exactly the same as always giving a2ps the option
     `--medium=Letter' at run time.

   The quoting mechanism is the same as that of a shell.  For instance
     Options: --right-title="Page $p" --center-title="Hello World!"
     Options: --title="arg 'Jack said \\\"hi\\\"' has double quotes"

Your Media
==========

 - Configuration Setting: Medium: NAME DIMENSIONS
     Define the medium NAME to have the DIMENSIONS (in PostScript
     points, i.e., 1/72 of inch).

     There are two formats supported:

    long
          in which you must give both the size of the whole sheet, and
          the size of the printable area:
               # A4 for Desk Jets
               #      NAME     W      H     LLX   LLY   URX    URY
               Medium: A4dj    595    842    24    50    571    818

          where WxH are the dimension of the sheet, and the four other
          stand for lower left x and y, upper right x and y.

    short
          in which a surrounding margin of 24 points is used
               # A4
               #      NAME     W      H
               Medium: A4      595    842

          is the same as

               # A4
               #      NAME     W      H
               Medium: A4      595    842    24    24    571    818

Your Printers
=============

   A general scheme is used, so that whatever the way you should address
the printers on your system, the interface is still the same.  Actually,
the interface is so flexible, that you should understand `named
destination' when we write `printer'.

 - Configuration Setting: Printer: NAME PPD-KEY DESTINATION
 - Configuration Setting: Printer: NAME DESTINATION
 - Configuration Setting: Printer: NAME PPD-KEY
     Specify the destination of the output when the option `-P NAME' is
     given.  If PPD-KEY is given, declare the printer NAME to be
     described by the PPD file `PPD-KEY.ppd'.  If DESTINATION is not
     given, used that of the `UnknownPrinter:'.

     The DESTINATION must be of one of the following forms:
    `| COMMAND'
          in which case the output is piped into COMMAND.

    `> FILE'
          in which case the output is saved into FILE.

 - Configuration Setting: UnknownPrinter: [PPD-KEY] DESTINATION
     Specify the destination of the output when when the option `-P
     NAME' is given, but there is no `Printer:' entry for NAME.

 - Configuration Setting: DefaultPrinter: [PPD-KEY] DESTINATION
     Specify the destination of the output when when the option `-d'
     (send to default output) is given.

   Escapes expansion is performed on DESTINATION (see Escapes).
Recall that `#o' is evaluated to the destination name, i.e., the
argument given to `-P'.

   For instance
     # My Default Printer is called dominique
     DefaultPrinter: | lp -d dominique

     # `a2ps foo.c -P bar' will pipe into `lp -d bar'
     UnknownPrinter: | lp -d #o

     # `a2ps -P foo' saves into the file `foo'
     Printer: foo > foo.ps
     Printer: wc | wc
     Printer: lw | lp -d printer-with-a-rather-big-name

     # E.g. `a2ps foo.c bar.h -P file' will save into `foo.c.ps'
     Printer: file > $n.#.

     # E.g. `a2ps foo.c bar.h -P home' will save into `foo.ps'
     # in user's home
     Printer: home > ${HOME}/$N.#.

     # Here we address a printer which is not PostScript
     Printer: deskj | gs -q -sDEVICE=ljet3d -sOutputFile=- - \
              | lpr -P laserwriter -h -l

   MS-DOS users, and non-PostScript printer owners should take
advantage in getting good configuration of these entries.

Your Shortcuts
==============

   You can define some kind of `Macro Options' which stand for a set of
options.

 - Configuration Setting: UserOption: SHORTCUT OPTIONS...
     Define the SHORTCUT to be the list of OPTIONS....  When a2ps is
     called with `-=SHORTCUT' (or `--user-option=SHORTCUT'), consider
     the list of OPTIONS....

   Examples are
     # This emulates a line printer: no features at all
     # call a2ps -=lp to use it
     UserOption: lp -1m --pretty-print=plain -B --borders=no

     # When printing mail, I want to use the right style sheet with strong
     # highlight level, and stripping `useless' headers.
     UserOption: mail -Email -g --strip=1

Your PostScript magic number
============================

   a2ps produces full DSC conformant PostScript (see Glossary).
Adobe said
     Thou shalt start your PostScript DSC conformant files with
          %!PS-Adobe-3.0

   The bad news is that some printers will reject this header.  Then you
may change this header without any worry since the PostScript produced
by a2ps is also 100% PostScript level 1(1).

 - Configuration Setting: OutputFirstLine: MAGIC-NUMBER
     Specify the header of the produced PostScript file to be
     MAGIC-NUMBER.  Typical values include `%!PS-Adobe-2.0', or just
     `%!'.

   ---------- Footnotes ----------

   (1) That is to say, there are no PostScript printers that don't
understand these files.

Your Page Labels
================

   In the PostScript file is dropped information on where sheets begin
and end, so that post processing tools know where is the physical page
1, 2 etc.  With this information can be also stored a label, i.e., a
human readable text (typically the logical page numbers), which is for
instance what `Ghostview' shows as the list of page numbers.

   a2ps lets you define what you want in this field.

 - Configuration Setting: PageLabelFormat: FORMAT
     Specify the FORMAT to use to label the PostScript pages.  FORMAT
     can use Escapes (see Escapes).  Two variables are predefined
     for this: `#{pl.short}' and `#{pl.long}'.

Your Variables
==============

   There are many places in a2ps where one would like to have uniform
way of extending things.  It once became clear that "variables" where
needed in a2ps.

Defining Variables
------------------

 - Configuration Setting: Variable: KEY VALUE
     Define the escape `#{KEY}' to be a short cut for VALUE.  KEY must
     not have any character from `:(){}'.

   As as example, here is a variable for `psnup', which encloses all
the option passing one would like.  Delegations are then easier to
write:
     Variable: psnup psnup -#v -q #?j|-d|| #?r||-c| -w#w -h#h

   It is strongly suggested to follow a `.' (dot) separated hierarchy,
starting with:
`del'
     for variables that are related to delegations.

`pro'
     for variables used in prologues (see Designing PostScript Prologues).
     Please, specify the name of the prologue (e.g.,
     `pro.matrix.gray').

`ps'
     for variables related to PostScript matters, such as the page label
     (which is associated to `ps.page_label'), the header etc.

`pl'
     for page label formats. See Your Page Labels, the option
     `--page-label' in Input Options.

`toc'
     for toc formats.  See the option `--toc' in Input Options.

`user'
     for user related information.  See Predefined Variables.

   This naming convention has not fully stabilized.  We apologize for
the inconvenience this might cause to users.

Predefined Variables
--------------------

   There are a few predefined variables.  The fact that a2ps builds them
at startup changes nothing to their status: they can be modified like
any other variable using `--define' (see Global Options).

   In what follows, there are numbers (i) like this, or (ii) this.  It
means that a2ps first tries the solution (i), if a result is obtained
(non empty value), this is the value given to the variable.  Otherwise
it tries solution (ii), etc.  The rationale behind the order is usually
from user modifiable values (e.g. environment variables) through
system's hard coded values (e.g., calls to `getpwuid') and finally
arbitrary values.

`user.comments'
     Comments on the user.  Computed by (i) the system's database (the
     part of `pw_gecos' after the first `,'), (ii) not defined.

`user.home'
     The user's home directory.  Determined by (i) the environment
     variable `HOME', (ii) the system's database (using `getpwuid'),
     (iii) the empty string.

`user.host'
     The user's host name.  Assigned from (i) the system (`gethostname'
     or `uname'), (ii) the empty string.

`user.login'
     The user's login (e.g. `bgates').  Computed by (i) the environment
     variable `LOGNAME', (ii) the environment variable `USERNAME',
     (iii) the system's database (using `getpwuid'), (iv) the translated
     string `user'.

`user.name'
     The user's name (e.g. `William Gates').  Computed by (i) the
     system's database (`pw_gecos' up to the first `,'), (ii)
     capitalized value of the variable `user.login' unless it was the
     translated string `user', (iii) the translated string `Unknown
     User'.

Your Delegations
================

   There are some files you don't really want a2ps to pretty-print,
typically page description files (e.g., PostScript files, `roff' files,
etc.).  You can let a2ps delegate the treatment of these files to other
applications.  The behavior at run time depends upon the option
`--delegate' (see Input Options).

Defining a Delegation
---------------------

 - Configuration Setting: Delegation: NAME IN:OUT COMMAND
     Define the delegation NAME.  It is to be applied upon files of
     type IN when output type is OUT(1) thanks to COMMAND.  Both IN and
     OUT are a2ps type keys such as defined in `sheets.map' (see The Entry in sheets.map).

   COMMAND should produce the file on its standard output.  Of course
escapes substitution is performed on COMMAND (see Escapes).  In
particular, COMMAND should use the input file `$f'.

     # In general, people don't want to pretty-print PostScript files.
     # Pass the PostScript files to psnup
     Delegation: PsNup ps:ps \
             psselect #?V||-q| -p#?p|#p|-| $f | \
             psnup -#v -q #?j|-d|| #?r||-c| -w#w -h#h

   Advantage should be taken from the variables, to encapsulate the
peculiarities of the various programs.
     # Passes the options to psnup.
     # The files (in and out) are to be given
     Variable: psnup psnup -#v #?V||-q| #?j|-d|| #?r||-c| -w#w -h#h

     # Passes to psselect for PS page selection
     Variable: psselect psselect #?V||-q| -p#?p|#p|-|

     # In general, people don't want to pretty-print PostScript files.
     # Pass the PostScript files to psnup
     Delegation: PsNup ps:ps     #{psselect} $f | #{psnup}

   Temporary file names (`#f0' to `#f9') are available for complex
commands.
     # Pass DVI files to dvips.
     # A problem with dvips is that even on failure it dumps its prologue,
     # hence it looks like a success (output is produced).
     # To avoid that, we use an auxiliary file and a conditional call to
     # psnup instead of piping.
     Delegation: dvips dvi:ps    #{dvips} $f -o #f0 && #{psnup} #f0

   ---------- Footnotes ----------

   (1) Current `a2ps' only handles PostScript output, i.e. OUT=`ps'

Guide Line for Delegations
--------------------------

   First of all, select carefully the applications you will use for the
delegations.  If a filter is known to cause problems, try to avoid it in
delegations(1).  As a thumb rule, you should check that the PostScript
generating applications produce files that start by:
     %!PS-Adobe-3.0

   a2ps *needs* the `%%BeginSetup'-`%%EndSetup' section in order to
output correctly the page device definitions.  It can happen that your
filters don't output this section.  In that case, you should insert a
call to `fixps' right after the PostScript generation:
     ########## ROFF files
     # Pass the roff files to groff.  Ask grog how groff should be called.
     # Use fixps to ensure there is a %%BeginSetup/%%EndSetup section.
     Delegation: Groff roff:ps	\
        eval `grog -Tps '$f'` | fixps #?V!!-q! | #{d.psselect} | #{d.psnup}

   There are some services expected from the delegations.  The
delegations you may write should honor:
the input file
     available via the escape `$f'.  You should be aware that there are
     people who have great fun having spaces or dollars in their file
     names, so you probably should always use `'$f''.  Some other
     variables are affected.  Yes, I know, we need a special mechanism
     for `'' itself.  Well, we'll see that later `;-)'.

the medium
     the dimension of the medium selected by the user are available
     through `#w' and `#h'.

the page layout
     the number of virtual pages is `#v'.

the page range
     the page range (in a form `1-2,4-6,10-' for instance) is available
     by `#p'.

the verbosity level
     please, do not make your delegations verbose by default.  The
     silent mode should always be requested, unless `#?V' is set (see
     the above example with `groff').

   If ever you need several commands, do not use `;' to separate them,
since it may prevent detection of failure.  Use `&&' instead.

   The slogan "_the sooner, the better_" should be applied here: in the
processing chain, it is better to ask a service to the first
application that supports it.  An example will make it clear: when
processing a `DVI' file, `dvips' knows better the page numbers than
`psselect' would.  So a `DVI' to PostScript delegation should ask the
page selection (`#p') to `dvips', instead of using `psselect' later in
the chain.  An other obvious reason here is plain efficiency (globally,
less data is processed).

   ---------- Footnotes ----------

   (1) Because hiding its use into `a2ps' just makes it even more
difficult to the users to know why it failed.  Let them use it by hand.

Predefined Delegations
----------------------

   The purpose of this section is not to document all the predefined
delegations, for this you should read the comments in the system
configuration file `a2ps.cfg'.  We just want to explain some choices,
and give hints on how to make the best use of these delegations.

 - Delegation: dvips (DVI to PostScript)
     There is a problem when you use a naive implementation of this
     delegation: landscape jobs are not recognized, and therefore
     n-upping generally fails miserably.  Therefore, a2ps tries to
     guess if the file is landscape by looking for the keyword
     `landscape' in it, using `strings(1)':
          Delegation: dvips dvi:ps\
           if strings $f | sed 3q | fgrep landscape > /dev/null 2>&1; then \
             #{d.dvips} -T#hpt,#wpt $f -o #f0 && #?o|cat|#{d.psnup} -r| #f0;\
           else \
             #{d.dvips} $f -o #f0 && #{d.psnup} #f0; \
           fi

     In order to have that rule work correctly, it is expected from the
     TeX, or LaTeX file to include something like:

          \renewcommand{\printlandscape}{\special{landscape}}
          \printlandscape

     in the preamble.

     We don't use a pipe because dvips always outputs data (its
     prologue) even if it fails, what prevents error detection.

 - Delegation: LaTeX (LaTeX to DVI)
     We use a modern version of the shell script `texi2dvi', from the
     package `Texinfo', which runs `makeindex', `bibtex' and `latex' as
     many times as needed.  You should be aware that if the file
     includes files from *other* directories, it may miss some
     compilation steps.  Other cases (most typical) are well handled.

Your Internal Details
=====================

   There are settings that only meant for a2ps that you can tune by
yourself.

 - Configuration Setting: FileCommand: COMMAND
     The command to run to call `file(1)' on a file.  If possible, make
     it follow the symbolic links.

Library Files
*************

   To be general and to allow as much customization as possible, a2ps
avoids to hard code its knowledge (encodings, PostScript routines,
etc.), and tries to split it in various files.  Hence it needs a path,
i.e., a list of directories, in which it may find the files it needs.

   The exact value of this library path is available by `a2ps
--list=defaults'.  Typically its value is:
     gargantua ~ $ a2ps --list=defaults
     Configuration status of a2ps 4.13
     _More stuff deleted here_
     Internals:
       verbosity level     = 2
       file command        = /usr/ucb/file -L
       temporary directory =
       library path        =
             /inf/soft/infthes/demaille/.a2ps
             /usr/local/share/a2ps/sheets
             /usr/local/share/a2ps/ps
             /usr/local/share/a2ps/encoding
             /usr/local/share/a2ps/afm
             /usr/local/share/a2ps/printers
             /usr/local/share/a2ps

   You may change this default path through the configuration files
(see Your Library Path).

   If you plan to define yourself some files for a2ps, they should be in
one of those directories.