Go to the first, previous, next, last section, table of contents.

4 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 section 4.1 Including Configuration Files) is included from `a2ps.cfg'.

Another difference is that `a2ps.cfg' is updated when you update a2ps, while `a2ps-site.cfg' remains equal, 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.

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

4.2 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:'.

4.3 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 section 3 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"

4.4 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

4.5 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 section 3.2 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.

4.6 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

4.7 Your PostScript magic number

a2ps produces full DSC conformant PostScript (see section A 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(2).

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 `%!'.

4.8 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 section 3.2 Escapes). Two variables are predefined for this: `#{pl.short}' and `#{pl.long}'.

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

4.9.1 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 section 8.6 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 section 4.8 Your Page Labels, the option `--page-label' in section 3.1.6 Input Options.
`toc'
for toc formats. See the option `--toc' in section 3.1.6 Input Options.
`user'
for user related information. See section 4.9.2 Predefined Variables.

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

4.9.2 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 section 3.1.2 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'.

4.10 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 section 3.1.6 Input Options).

4.10.1 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(3) thanks to command. Both in and out are a2ps type keys such as defined in `sheets.map' (see section 7.7.3 The Entry in `sheets.map').

command should produce the file on its standard output. Of course escapes substitution is performed on command (see section 3.2 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

4.10.2 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(4). 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 through the escape `$f'.
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).

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

4.11 Your Internal Details

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

Configuration Setting: TemporaryDirectory: path
Specify a directory in which the temporary files are put. Default is `/tmp', or `/var/tmp', or `$TMPDIR' according your environment.

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

Go to the first, previous, next, last section, table of contents.