Customizing a2ps

Configuration files

@pack reads several files before the command line options. In the order, they are:

1. the system configuration file (usually `/etc/a2ps.cfg')
2. the user's home configuration file (`$HOME/.a2ps/a2psrc')
3. the local file (`./.a2psrc')

In these 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.

Your default options

`Options: options+'

Give @pack a list of command line options. options+ is any sequence of regular command line options (see section Command line options). The quoting mechanism is a bit painful: you need to quote the whole options+. For instance

Options: --right-title='Page $p'

is wrong. Write

Options: '--right-title=Page $p'

Your guess rules

`Pattern: pattern language'

Specify that any file which name matches pattern (usual Unix file name patterns) should be treated with the style language. For instance, Promela programmers use the suffix `pr' for their files, though @pack hard codes `pr' to SDL. To override this rule, use:

Pattern: *.pr promela

The same problem occurs with Objective C and Octave/Matlab.

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.

`DefaultPrinter: destination'

Tell @pack where to send the PostScript it produced. See next item for information on destination. The DefaultPrinter is used when option `-d' is given.

`Printer: name destination'

`UnknownPrinter: destination'

Tell @pack where to send the PostScript it produced. Both entries are related to the `-P printer' option, the first one being triggered when printer is equal to name, and the second when name as no Printer: entry. The destination must be of one of the following forms:

`| command'

in which case the PostScript is piped in command

`> file'

in which case the PostScript is saved into file.

In each case, the argument given to option `-P' is substituted to `%s', and `%' to `%%' in destination. For instance

DefaultPrinter: | lp -d dominique
UnknownPrinter: | lp -d %s
Printer: foo > foo.ps
Printer: wc | wc
Printer: lw | lp -d printer-with-a-rather-big-name

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

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

Your shortcuts

`UserOption: shortcut Option+'

define a shortcut, i.e., when @pack is called with `--user-option=shortcut', then consider Option+.

Your PostScript magic number

@pack produces full DSC compliant PostScript which is something that only PS wizards may understand(1). Adobe said

Thou shalt start you PostScript DSC compliant 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 @pack is also 100% PostScript level 1(2). For instance:

OutputFirstLine: magic-number

where magic-number is `%!PS-Adobe-2.0', or just `%!'.

Designing prologues

It is pretty known that satisfying the various human tastes is an NEXPTIME-hard problem, so @pack offers ways to customize its output through the prologue files. But since the authors feel a little small against NEXPTIME, they agreed on the fact that you are the one who will design the look you like.

Hence in this section, you will find what you need to know to be able to customize a2ps output.

Basically, @pack uses faces which are associated to their "meanning" in the text. @pack let's you change the way the faces look.

a2ps faces

@pack uses 7 faces:

`Plain (p)'

This corresponds to the text body.

`Keyword (k)'

`Keyword_strong (K)'

These are related to the keywords that may appear in a text.

`Comment (c)'

`Comment_strong (C)'

These are related to comments in the text. Remember that comments should be considered as non essential ("Aaaeaaarg" says the programmer); indeed, the user might suppress the comments thanks (?) to the option `--strip-level'. Hence, never use these faces just because you think they look better on, say, strings.

`Label (l)'

`Label_strong (L)'

These are used when a point of extreme importance, or a sectioning point, is met. Typically, functions declarations etc.

`String (str)'

Used mainly for string and character literals.

Actually, there is also the face `Symbol', but this one is particular: it is not legal changing its font.

Definition of the faces

There are three things that define a face:

Its font

There is a uniform font naming scheme. They all start by `f', as in font :), then a letter for the name of the family of the font (`c' for Courier, `t' for Times, and `h' for Helvetica, and finally an optional letter for the declination of in the font family (`b' for bold, `i' for italic, and `e' (as in emphasize) for bold-italic). There are two steps in specifying a face's font:

1. tell @pack the font you use. This is achieved by a comment line:

   %Face: face real-font-name
   

2. tell the PostScript the font you want to use. This achieved calling setfont, preceded by the short font name:

   short-font-name setfont
   

Its background color

There are two cases:

1. You want a background color, then give the RGB (see section Colors in PostScript) ratio and true to BG:

   0.8 0.8 0 true BG
   

2. You don't want a background color, then call BG with false:

   false BG
   

3. Its foreground color As BG, call FG with an RGB ratio:

   0 0.5 0 FG
   

4. Its underlining UL requires a boolean argument, depending whether you want or not the current face to be underlined.

   true UL
   

5. Its boxing Requiring a bolean, BX let's a face have a box drawn around.

Colors in PostScript

Nevertheless, here are some tips on how to design your PostScript styles. It is strongly recommended to use `gray.pro' or `color.pro' as a template.

There are two PostScript instructions you might want to use in your new PostScript prologue:

setgray

this instruction must be preceded by a number between 0 (black) and 1 (white). It defines the gray level used.

setrgbcolor

this instruction must be preceded by three numbers between 0 (0 %) and 1 (100%). Those three numbers are related to red, green and blue proportions used to designate a color.

@pack uses two upper level procedures, BG and FG, but both use an argument as in setrgbcolor. So if you wanted a gray shade, just give three times the same ratio.

A step by step example

We strongly suggest our readers not to start from scratch, but to copy one of the available styles (see the result of `a2ps --list-features'), to drop it in one of @pack directories (say `$HOME/.a2psrc', and to patch it until you like it.

Here, we will start from `color.pro', trying to give it a funky look.

Say you want the keywords to be in Helvetica, drawn in a flashy pink on a light green. And strong keywords, in Times Bold Italic in brown on a soft Hawaïan sea green (you are definitely a fine art amateur).

Then you need to look for `k' and `K':

%Face: Keyword Courier
/k {
  false BG
  0 0 0.9 FG
  fc setfont
  Show
} bind def

%Face: Keyword_strong Courier-Bold
/K {
  false BG
  0 0 0.8 FG
  fcb setfont
  Show
} bind def

and turn it into:

%Face: Keyword Helvetica
/k {
  0.2 1 0.2 true BG
  1 0.2 1 FG
  fh setfont
  Show
} bind def

%Face: Keyword_strong Times_boldItalic
/K {
  0.4 0.2 0 true BG
  0.5 1 1 FG
  fte setfont
  Show
} bind def

Waouh! It looks great!

A bit trickier: let change the way the line numbers are printed.

First, let's look for the font definition:

%%BeginSetup
% The font for line numbering
/f# /Helvetica findfont bfs .6 mul scalefont def
%%EndSetup

Let it be in Times, twice bigger than the body font.

%%BeginSetup
% The font for line numbering
/f# /Times findfont bfs 2 mul scalefont def
%%EndSetup

How about its foreground color?

% Function print line number (<string> # -)
/# {
  gsave
    sx cw mul 2 div neg 0 rmoveto
    f# setfont
    0.8 0.1 0.1 FG
    c-show
  grestore
} bind def

Let it be blue. Now you know the process: just put `0 0 1' as FG arguments.