Go to the first, previous, next, last section, table of contents.
a2ps reads several files before the command line options. In the order, they are:
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.
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).
To define the default library path, you can use:
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:'.
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"
There are two formats supported:
# A4 for Desk Jets # name w h llx lly urx ury Medium: A4dj 595 842 24 50 571 818where wxh are the dimension of the sheet, and the four other stand for lower left x and y, upper right x and y.
# A4 # name w h Medium: A4 595 842is the same as
# A4 # name w h Medium: A4 595 842 24 24 571 818
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'.
The destination must be of one of the following forms:
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.
You can define some kind of `Macro Options' which stand for a set 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
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).
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.
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.
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:
ps.page_label), the header etc.
This naming convention has not fully stabilized. We apologize for the inconvenience this might cause to users.
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.
pw_gecos after the first `,'), (ii) not defined.
HOME, (ii) the system's database (using getpwuid), (iii)
the empty string.
gethostname
or uname), (ii) the empty string.
LOGNAME, (ii) the environment variable USERNAME,
(iii) the system's database (using getpwuid), (iv) the translated
string `user'.
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'.
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).
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
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:
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).
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.
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.
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.
There are settings that only meant for a2ps that you can tune by yourself.
file(1) on a file. If possible, make
it follow the symbolic links.
Go to the first, previous, next, last section, table of contents.