This is a2ps.info, produced by makeinfo version 4.0 from a2ps.texi.

INFO-DIR-SECTION Printing Tools
START-INFO-DIR-ENTRY
* a2ps: (a2ps).                    PostScript Generating Utility
* PreScript: (a2ps) PreScript.     Input language for a2ps
* card: (a2ps) card.               Print Reference Cards
* fixps: (a2ps) fixps.             Fixing Some Ill Designed PostScript Files
* fixnt: (a2ps) fixnt.             Fixing Microsoft NT PostScript Files
* pdiff: (a2ps) pdiff.             Produce Pretty Comparison of Files
* psmandup: (a2ps) psmandup.       Printing Duplex on Simplex Printers
* psset: (a2ps) psset.             Inserting calls to setpagedevice
END-INFO-DIR-ENTRY

   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.


File: a2ps.info,  Node: Input Options,  Next: Pretty Print Options,  Prev: Headings Options,  Up: Options

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 (*note
     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.  *Note 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 (*note
     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 (*note 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 *Note 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 (*note
     Escapes::) processed as a PreScript file (*note 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 (*note 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


File: a2ps.info,  Node: Pretty Print Options,  Next: Output Options,  Prev: Input Options,  Up: Options

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.  *Note 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.


File: a2ps.info,  Node: Output Options,  Next: PostScript Options,  Prev: Pretty Print Options,  Up: Options

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 *Note 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 *Note Pass Options
     to lpr::.

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


File: a2ps.info,  Node: PostScript Options,  Prev: Output Options,  Up: Options

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 (*note 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.  *Note 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.  *Note
     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.


File: a2ps.info,  Node: Escapes,  Prev: Options,  Up: Invoking a2ps

Escapes
=======

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

* Menu:

* Use of Escapes::              Where they are used
* Structure of the Escapes::    Their syntax
* Available Escapes::           Detailed list


File: a2ps.info,  Node: Use of Escapes,  Next: Structure of the Escapes,  Prev: Escapes,  Up: Escapes

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

   They are used in several places in a2ps:
_Page markers_
     Headers, footers, titles and the water mark (*note 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 (*note Your Printers::).

_Delegation_
     To specify the command associated to a delegation (*note 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
     (*note Designing PostScript Prologues::).


File: a2ps.info,  Node: Structure of the Escapes,  Next: Available Escapes,  Prev: Use of Escapes,  Up: Escapes

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
     *Note Available Escapes::.


File: a2ps.info,  Node: Available Escapes,  Prev: Structure of the Escapes,  Up: 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 (*Note
          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 (*note 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' (*note Predefined
     Variables::).

`%A'
     the localized equivalent for `Printed by USER NAME from HOST
     NAME'. The variables `user.name' and `user.host' are used (*note
     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 (*note Your Delegations::) and for the printer
     commands (*note 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' (*note
     Predefined Variables::).

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

`%N'
     shortcut for the value of the variable `user.name' (*note
     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
     (*note 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


File: a2ps.info,  Node: Configuration Files,  Next: Library Files,  Prev: Invoking a2ps,  Up: Top

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' (*note 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.

* Menu:

* Including Configuration Files::  Isolating site specific values
* Your Library Path::           Setting the files search path
* Your Default Options::        Default state of a2ps
* Your Media::                  Sheets dimensions
* Your Printers::               How to access the printers
* Your Shortcuts::              Your very own command line options
* Your PostScript magic number::  Handling very old printers
* Your Page Labels::            Page names as in `Ghostview'
* Your Variables::              Short cut for long sequences
* Your Delegations::            Delegating some files to other filters
* Your Internal Details::       Details you might want to tune


File: a2ps.info,  Node: Including Configuration Files,  Next: Your Library Path,  Prev: Configuration Files,  Up: Configuration Files

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).


File: a2ps.info,  Node: Your Library Path,  Next: Your Default Options,  Prev: Including Configuration Files,  Up: 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:'.


File: a2ps.info,  Node: Your Default Options,  Next: Your Media,  Prev: Your Library Path,  Up: Configuration Files

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

 - Configuration Setting: Options: OPTIONS+
     Give a2ps a list of command line options. OPTIONS+ is any sequence
     of regular command line options (*note 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"


File: a2ps.info,  Node: Your Media,  Next: Your Printers,  Prev: Your Default Options,  Up: Configuration Files

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


File: a2ps.info,  Node: Your Printers,  Next: Your Shortcuts,  Prev: Your Media,  Up: Configuration Files

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 (*note 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.


File: a2ps.info,  Node: Your Shortcuts,  Next: Your PostScript magic number,  Prev: Your Printers,  Up: Configuration Files

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


File: a2ps.info,  Node: Your PostScript magic number,  Next: Your Page Labels,  Prev: Your Shortcuts,  Up: Configuration Files

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

   a2ps produces full DSC conformant PostScript (*note 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.


File: a2ps.info,  Node: Your Page Labels,  Next: Your Variables,  Prev: Your PostScript magic number,  Up: Configuration 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 (*note Escapes::).  Two variables are predefined
     for this: `#{pl.short}' and `#{pl.long}'.


File: a2ps.info,  Node: Your Variables,  Next: Your Delegations,  Prev: Your Page Labels,  Up: Configuration Files

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.

* Menu:

* Defining Variables::          Syntax and conventions
* Predefined Variables::        Builtin variables


File: a2ps.info,  Node: Defining Variables,  Next: Predefined Variables,  Prev: Your Variables,  Up: Your Variables

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 (*note 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. *Note Your Page Labels::, the option
     `--page-label' in *Note Input Options::.

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

`user'
     for user related information.  *Note Predefined Variables::.

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


File: a2ps.info,  Node: Predefined Variables,  Prev: Defining Variables,  Up: Your Variables

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' (*note 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'.


File: a2ps.info,  Node: Your Delegations,  Next: Your Internal Details,  Prev: Your Variables,  Up: Configuration Files

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' (*note Input Options::).

* Menu:

* Defining a Delegation::       Syntax of the definitions of the delegations
* Guide Line for Delegations::  What should be respected
* Predefined Delegations::      Making the best use of these delegations


File: a2ps.info,  Node: Defining a Delegation,  Next: Guide Line for Delegations,  Prev: Your Delegations,  Up: Your Delegations

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' (*note The
     Entry in sheets.map::).

   COMMAND should produce the file on its standard output.  Of course
escapes substitution is performed on COMMAND (*note 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'


File: a2ps.info,  Node: Guide Line for Delegations,  Next: Predefined Delegations,  Prev: Defining a Delegation,  Up: Your Delegations

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.


File: a2ps.info,  Node: Predefined Delegations,  Prev: Guide Line for Delegations,  Up: Your Delegations

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.


File: a2ps.info,  Node: Your Internal Details,  Prev: Your Delegations,  Up: Configuration Files

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.


File: a2ps.info,  Node: Library Files,  Next: Encodings,  Prev: Configuration Files,  Up: Top

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
(*note Your Library Path::).

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

* Menu:

* Documentation Format::        Special tags to write a documentation
* Map Files::                   Their general shape and rationale
* Font Files::                  Using other fonts
* Style Sheet Files::           Defining pretty printing rules

