General Purpose PostScript Generating Utility

2.2.1 Basics for Printing

Say you want to print the C file bar.c, and its header foo.h, on 4 virtual pages, and save it into the file foobar.ps. Just hit:

gargantua $ a2ps foo.h bar.c -4 -o foobar.ps
[foo.h (C): 1 page on 1 sheet]
[bar.c (C): 3 pages on 1 sheet]
[Total: 4 pages on 2 sheets] saved into the file `foobar.ps'

The option ‘-4’ tells a2ps to make four virtual pages: two rows by two columns. The option ‘-o foobar.ps’ (which is the short version of ‘--output=foobar.ps’) specifies the output file. Long options must always be separated by spaces, though short options with no arguments may be grouped.

Note too that the options may be specified before or after the files, it does not matter.

If you send foobar.ps to a printer, you’ll discover that the keywords were highlighted, that the strings and comments have a different face. Indeed, a2ps is a pretty-printer: if it knows the (programming) language in which your file is written, it will try to make it look nice and clear on the paper.

But too bad: foo.h is only one virtual page long, and bar.c takes three. Moreover, the comments are essential in those files. And even worse: the system’s default printer is out of ink. Thanks god, precious options may help you:

gargantua $ a2ps -4 -Av foo.h bar.c --prologue=gray -P lw
[foo.h (C): 1 page on 1 sheet]
[bar.c (C): 3 pages on 1 sheet]
[Total: 4 pages on 1 sheet] sent to the printer `lw'

Here the option ‘-A’ is a short cut for the option ‘--file-align’ which specifies how different files should be separated. This option allows several symbolic arguments: ‘virtual’, ‘rank’, ‘page’, ‘sheet’ (See Sheet Options, for more details). The value ‘virtual’ means not to start each file on a different virtual pages.

So to fill the page is asked by ‘--file-align=virtual’, or ‘-A virtual’. But symbolic arguments can be abbreviated when there are no ambiguity, so here, you can just use ‘-Av’.

The option ‘-P lw’ means to print on the printer named ‘lw’, and finally, the long option ‘--prologue’ requires the use one of the alternative printing styles. There are other prologues (See Input Options, option ‘--prologue’), and you can even design yours (see Designing PostScript Prologues).

2.2.2 Special Printers

There are three special printers pre-defined.

The first one, void, sends the output to the trash. Its main use is to see how many pages would have been used.

gargantua ~ $ a2ps -P void parsessh.c
[parsessh.c (C): 33 pages on 17 sheets]
[Total: 33 pages on 17 sheets] sent to the printer `void'

The second, display sends the output to Ghostview, so that you can check the output without printing. Of course if you don’t have Ghostview, it won’t work... And it is up to you to configure another displaying application (see Your Printers).

The last, file saves the output into a file named after the file you printed (e.g., saves into foo.ps when you print foo.c).

2.2.3 Using Delegations

a2ps can decide that a2ps itself is not the right tool to do what you want. In that case it delegates the task to other programs. What you should retain from this, is, forget that there are delegations. Indeed, the interface with the delegations has been designed so that you don’t need to be aware that they exist to use them. Do as usual.

As an example, if you need to print a PostScript file, just hit:

gargantua ~ $ a2ps article.ps -d
[article.ps (ps, delegated to PsNup): 7 pages on 4 sheets]
[Total: 8 pages on 4 sheets] sent to the default printer

While honoring your defaults settings, a2ps delegates the task to put two virtual pages per physical page to psnup, a powerful filter part of the famous psutils by Angus Duggan.

Suppose now that you want to display a Texinfo file. Then, provided you have all the programs a2ps needs, just hit

gargantua ~ $ a2ps a2ps.texi -P display
[a2ps.texi (texinfo, delegated to texi2dvi): 75 pages on 38 sheets]
[Total: 76 pages on 38 sheets] sent to the printer `display'

Once the read documentation, you know you want to print just pages 10 to 20, plus the cover. Just hit:

gargantua ~ $ a2ps a2ps.texi --pages=1,10-20 -d
[a2ps.texi (texinfo, delegated to texi2dvi): 13 pages on 7 sheets]
[Total: 14 pages on 7 sheets] sent to the default printer

A final word: compressed files can be treated in the very same way:

gargantua ~ $ a2ps a2ps.texi.gz -a1,10-20 -d
[a2ps.texi (compressed, delegated to Gzip-a2ps): 13 pages on 7 sheets]
[Total: 14 pages on 7 sheets] sent to the default printer

You should be aware that:

• - the option ‘-Z’ enables the delegations if they are not (see ‘--list=defaults’ for your settings);
• - the set of delegations is customizable, to know the delegations your a2ps knows, consult ‘a2ps --list=delegations’.

2.2.4 Printing Duplex

If you still want to save more paper, and you are amongst the set of happy users of Duplex printers, a2ps will also be able to help you (See Glossary, for definitions). The option to specify Duplex printing is ‘--sides=mode’ (see PostScript Options).

Here is how to print the documentation in Duplex and send it to the Duplex printer ‘margot’:

quasimodo ~ a2ps/doc $ a2ps -s2 -Pmargot a2ps.texi
[a2ps.texi (texinfo, delegated to texi2dvi): 109 pages on 28 sheets]
[Total: 110 pages on 28 sheets] sent to the printer `margot'

This is also valid for several files.

Actually, you can do something even more tricky: print a small book! This is much more complicated than printing Duplex, because the pages needs to be completely reorganized another way. This is precisely the job of psbook, yet another PsUtil from Angus Duggan. But there is a user option which encapsulates the magic sequence of options: ‘book’. Therefore, just run

quasimodo a2ps/doc $ a2ps -=book -Pmargot a2ps.texi
[a2ps.texi (texinfo, delegated to texi2dvi): 109 pages on 109 sheets]
[Total: 109 pages on 109 sheets] sent to the printer `margot'

and voila‘ !, a booklet printed on margot!

We strongly discourage you to try with several files at once, because the tools then easily get lost. And, after all, the result will be exactly the same once you collated all the booklets together.

Another limitation is that this does not work if it is not sent to a printer. This kind of weird limitations will be solved in the future.

2.2.5 Checking the Defaults

If a2ps did not have the behavior expected, this may be because of the default settings given by your system administrator. Checking those default values is easy:

~ % a2ps --list=defaults
                Configuration status of a2ps 4.12a
                ==================================
Sheets:
-------
  medium          = A4, portrait
  page layout     = 1 x 1, rows first
  borders         = yes
  file alignment  = page
  interior margin = 0
More stuff deleted here
Internals:
----------
  verbosity level     = 2
  file command        = /usr/bin/file -L
  temporary directory = /tmp
  library path        =
        /home/akim/.a2ps
        /usr/share/a2ps/sheets
        /usr/share/a2ps/ps
        /usr/share/a2ps/encoding
        /usr/share/a2ps/afm
        /usr/share/ogonkify/afm
        /usr/share/a2ps/ppd
        /usr/share/a2ps/fonts
        /usr/share/ogonkify/fonts
        /usr/share/a2ps

Remember that the on-line help is always available. Moreover, if your screen is small, you may pipe it into more. Just trust this:

a2ps --help | more

2.5.1 Interfacing With a Mailer

When you print from a mailer (or a news reader), your mailer calls a tool, say a2ps on a part of the whole mailbox. This makes it difficult for a2ps to guess that the file is of the type ‘mail’. Therefore, for better results, make sure to tell a2ps the files are mails. The user option ‘mail’ (or ‘longmail’ for longer inputs) encapsulates most typical tuning users want to print mails (for instance, don’t print all the headers).

Most specifically, if your mailer is:

elm ¶

Once you are in elm, hit o to enter in the options edition menu, hit p to edit the printer command, and enter ‘a2ps -=mail %s -d’. The option ‘-d’ means to print on the default printer.

pine ¶

Jan Chrillesen suggests us how to use a2ps with the Pine mail-reader. Add the following to .pinerc (of course you can put it in pine.conf as well):

# Your printer selection
printer=a2ps -=mail -d

# Special print command
personal-print-command=a2ps -=mail -d

2.5.2 Processing the output of other programs

Use the following command:

a2ps

Not too hard, isn’t it?

Nevertheless, this setting suppose your world is OK, your file(1) detects correctly PostScript files, and your a2ps is configured to delegate. In case one one these conditions is not met, use:

a2ps -ZEps

Do not forget to tell the program whose output you are processing whether your printer supports colors, and the type of paper it uses.

3.1.1 Tasks Options

Task options specify the task a2ps will perform. It will not print, it executes the task and exits successfully.

Option: --version ¶

print version and exit successfully.

Option: --help ¶

Print a short help, and exit successfully.

Option: --copyright ¶

Display Copyright and copying conditions, and exit successfully.

Option: --guess ¶

Act like file does: display the (key of the) type of the Files.

For instance, on a C file, you expect it to answer ‘c’, and upon a PostScript file, ‘ps’.

This can be very useful on broken systems to understand why a file is printed with a bad style sheet (see Style Sheet Files).

Option: --which ¶

Look in the library for the files which names are given as arguments. For instance:

~ % a2ps --which bw.pro gray.pro /usr/local/share/a2ps/ps/bw.pro /usr/local/share/a2ps/ps/gray.pro

If there are several library files matching the name, only the first one is reported: this allows to check which occurrence of a file is used by a2ps.

Option: --glob ¶

Look in the library for the files which names match the patterns given as arguments. For instance:

~ % a2ps --glob 'g*.pro' /usr/local/share/a2ps/ps/gray.pro /usr/local/share/a2ps/ps/gray2.pro

Option: --list=topic ¶

Display a report on a2ps’ status with respect to topic, and exit successfully. topic can be any non-ambiguous abbreviation of:

‘defaults’

‘options’

Give an extensive report on a2ps configuration and installation.

‘features’

Known media, encodings, languages, prologues, printers, variables, delegations and user options are reported. In a word, anything that you may define.

‘delegations’

Detailed list of the delegations. See Your Delegations.

‘encodings’

Detailed list of known encodings. See Some Encodings.

‘media’

Detailed list of known media. See Your Media.

‘prologues’

Detailed list of PostScript prologues. See Designing PostScript Prologues.

‘printers’

Detailed list of printers and named outputs. See Your Printers.

‘style-sheets’

Detailed list of the known style sheets. See Known Style Sheets.

‘user-options’

Detailed list of the user options. See Your Shortcuts.

‘variables’

Detailed list of the variables. See Your Variables.

There are also options meant for the maintainers only, presented for sake of completeness.

‘texinfo-style-sheets’

‘ssh-texi’

Detailed list of known style sheets in Texinfo format. If the sheet verbosity is set, report version numbers, requirements and ancestors.

‘html-style-sheets’

‘ssh-html’

Detailed list of the style sheets in HTML format.

‘texinfo-encodings’

‘edf-texi’

Detailed list of encodings, in Texinfo format.

‘texinfo-prologues’

‘pro-texi’

Detailed list of prologues, in Texinfo format.

3.1.2 Global Options

These options are related to the interface between you and a2ps.

Option: -q ¶

Option: --quiet ¶

Option: --silent ¶

be really quiet

Option: -v[level] ¶

Option: --verbose[=level] ¶

tell what we are doing. At

• - level = 0, report nothing,
• - level = 1, a2ps just prints the total number of pages printed,
• - level = 2 (default), it reports it for each file,
• - above, it gives internal details.

There is also an interface made for the maintainer with finer grained selection of the verbosity level. level is a list of tokens (non ambiguous abbreviations are valid) separated by either ‘,’ or ‘+’. The tokens may be:

‘configuration’

‘options’

reading the configurations files and the options,

‘encodings’

the encodings,

‘expert’

more detailed information is provided: PPD listings is exhaustive,

‘files’

inputs and outputs,

‘fonts’

the fonts,

‘escapes’

‘variables’

‘meta-sequences’

the expansion of escapes and variables,

‘parsers’

any parsing process (style sheets, PPD files etc.),

‘pathwalk’

‘pw’

the search for files,

‘ppd’

PPD processing,

‘sheets’

the style sheets,

‘stats’

statistics on some internal data structures,

‘tools’

launched programs or shell commands ; triggers the escape ‘?V’ on (see Available Escapes),

‘all’

all the messages.

When a2ps is launched it consults the environment variable A2PS_VERBOSITY. If it is set, this defines the verbosity level for the whole session (options ‘--verbose’, and ‘-q’ etc. have then no influence). The valid values for A2PS_VERBOSITY are exactly the valid arguments of the option ‘--verbose’. This helps tracking down configuration problems that occur before a2ps had even a chance to read the command line.

Option: -=shortcut ¶

Option: --user-option=shortcut ¶

use the shortcut defined by the user. See Your Shortcuts. Shortcuts may be freely mixed with regular options and arguments.

There are a few predefined user-options:

‘lp’

emulates a line printer, i.e., turn off most ‘pretty’ features.

‘mail’

‘longmail’

preferred options to print a mail or a news. ‘longmail’ prints more text on a single sheet.

‘manual’

make the job be printed on the manually fed tray.

Option: --debug ¶

enable debugging features. They are:

• - print the overall BoundingBox in PostScript;
• - down load a PostScript debugger which helps understanding why a printer may reject a file.

Option: -D key[=value] ¶

Option: --define=key[=value] ¶

Without value, unset the variable key. Otherwise, set it to value. See Your Variables, for more details. Note that ‘-Dfoo=’ gives foo an empty value, though ‘-Dfoo’ unsets foo.

3.1.3 Sheet Options

This options specify the general layout, how the sheet should be used.

Option: -M medium ¶

Option: --medium=medium ¶

use output medium medium. See the output of ‘a2ps --list=media’ for the list of supported media. Typical values are ‘A3’, ‘A4’, ‘A5’, ‘B4’, ‘B5’, ‘Letter’, ‘Legal’. The default is the user’s preferred paper size, or the system default; see the man page of paper for how this is configured. The default paper size may also be requested explicitly with the name ‘libpaper’.

Option: -r ¶

Option: --landscape ¶

print in landscape mode

Option: -R ¶

Option: --portrait ¶

print in portrait mode

Option: --columns=num ¶

specify the number of columns of virtual pages per physical page.

Option: --rows=num ¶

specify the number of rows of virtual pages per physical page.

Option: --major=direction ¶

specify whether the virtual pages should be first filled in rows (direction = ‘rows’) or in columns (direction = ‘columns’).

Option: -1 ¶

1 x 1 portrait, 80 chars/line, major rows (i.e. alias for ‘--columns=1 --rows=1 --portrait --chars-per-line=80 --major=rows’).

Option: -2 ¶

2 x 1 landscape, 80 chars/line, major rows.

Option: -3 ¶

3 x 1 landscape, 80 chars/line, major rows.

Option: -4 ¶

2 x 2 portrait, 80 chars/line, major rows.

Option: -5 ¶

5 x 1 landscape, 80 chars/line, major rows.

Option: -6 ¶

3 x 2 landscape, 80 chars/line, major rows.

Option: -7 ¶

7 x 1 landscape, 80 chars/line, major rows.

Option: -8 ¶

4 x 2 landscape, 80 chars/line, major rows.

Option: -9 ¶

3 x 3 portrait, 80 chars/line, major rows.

Option: -j ¶

Option: --borders=boolean ¶

print borders around virtual pages.

Option: -A mode ¶

Option: --file-align=mode ¶

Align separate files according to mode. This option allows the printing of more than one file on the same page. mode can be any one of:

‘virtual’

Each file starts on the next available virtual page (i.e., leave no empty virtuals).

‘rank’

Each file starts at the beginning of the next row or column depending on the ‘--major’ setting.

‘page’

Each file starts on a new page.

‘sheet’

Each file starts on a new sheet. In Simplex mode, this is the same as ‘page’, in Duplex mode, files always start on a front side.

an integer num

Each file starts on a page which is a multiple of num plus 1. For instance, for ‘2’, the files must start on odd pages.

Option: --margin[=num] ¶

Specify the size of the margin (num PostScript points, or 12 points without arguments) to leave in the inside (i.e. left for the front side page, and right for the back side). This is intended to ease the binding.

3.1.4 Page Options

This options are related to the content of the virtual pages.

Please note that the options ‘-f’, ‘-L’, ‘-l’, ‘-m’, and ‘-1’ .. ‘-9’ all have an influence on the font size. Only the last one will win (i.e., ‘a2ps -L66 -l80’ is the same as ‘a2ps -l80’).

Option: --line-numbers[=number] ¶

print the line numbers from number lines to number lines. Default is ‘1’.

Option: -C ¶

Alias for ‘--line-numbers=5’.

Option: -f size[unit] ¶

Option: --font-size=size[unit] ¶

scale font to size for body text. size is a float number, and unit can be ‘cm’ for centimeters, ‘points’ for PostScript points, and ‘in’ for inches. Default unit in ‘points’.

To change the fonts used, change the current prologue (see Designing PostScript Prologues.

Option: -l num ¶

Option: --chars-per-line=num ¶

Set the font size so that num columns appear per virtual pages. num is the real number of columns devoted to the body of the text, i.e., no matter whether lines are numbered or not.

Option: -L num ¶

Option: --lines-per-page=num ¶

Set the font size so that num lines appear per virtual pages. This is useful for printing preformatted documents which have a fixed number of lines per page. The minimum number of lines per page is set at 40 and maximum is at 160. If a number less than 40 is supplied, scaling will be turned off.

Option: -m ¶

Option: --catman ¶

Understand UNIX manual output ie: 66 lines per page and possible bolding and underlining sequences. The understanding of bolding and underlining is there by default even if ‘--catman’ is not specified. You may want to use the ‘ul’ prologue (See Input Options, option ‘--prologue’) if you prefer underlining over italics.

If your file is actually a UNIX manual input, i.e., a roff file, then depending whether you left a2ps delegate or not, you will get a readable version of the text described, or a pretty-printed version of the describing file (see Your Delegations).

Option: -T num ¶

Option: --tabsize=num ¶

set tabulator size to num. This option is ignored if --interpret=no is given.

Option: --non-printable-format=format ¶

specify how non-printable chars are printed. format can be

‘caret’

Use classical Unix representation: ‘^A’, ‘M-^B’ etc.

‘space’

A space is written instead of the non-printable character.

‘question-mark’

A ‘?’ is written instead of the non-printable character.

‘octal’

For instance ‘\001’, ‘177’ etc.

‘hexa’

For instance ‘\x01’, ‘\xfe’ etc.

‘emacs’

For instance ‘C-h’, ‘M-C-c’ etc.

3.1.5 Headings Options

These are the options through which you may define the information you want to see all around the pages.

All these options support text as an argument, which is composed of plain strings and escapes. See Escapes, for details.

Option: -B ¶

Option: --no-header ¶

no page headers at all.

Option: -b[text] ¶

Option: --header[=text] ¶

set the page header

Option: --center-title[=text] ¶

Option: --left-title[=text] ¶

Option: --right-title[=text] ¶

Set virtual page center, left and right titles to text.

Option: -u[text] ¶

Option: --underlay[=text] ¶

use text as under lay (or water mark), i.e., in a light gray, and under every page.

Option: --left-footer[=text] ¶

Option: --footer[=text] ¶

Option: --right-footer[=text] ¶

Set sheet footers to text.

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

‘diffcolor’

Colors are used to highlight the keywords (for diffs).

‘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

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

3.1.8 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 How Can I Pass Options to ‘lpr’.

Option: -d ¶

send output to the default printer. See item ‘DefaultPrinter:’ in Your Printers.

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

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

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

3.2.3 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

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

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

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

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 | grep -F 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.

5.3.1 Fonts Map File

See Map Files, for a description of the map files. This file associates the font-key to a font name. For instance:

Courier                 pcrr
Courier-Bold            pcrb
Courier-BoldOblique     pcrbo
Courier-Oblique         pcrro

associates to font named Courier, the key pcrr. To be recognized, the font name must be exact: courier and COURIER are not admitted.

5.3.2 Fonts Description Files

There are two kinds of data a2ps needs to use a font:

• - the AFM file (font-key.afm), which describes the metrics information corresponding to font;
• - in the case font is not known from the printer, the PFA or PFB file which is down loaded to the printer. These files are actually the PostScript programs which execution produces the characters to be drawn on the page, in this font.

5.3.3 Adding More Font Support

a2ps can use as many fonts as you want, provided that you teach it the name of the files in which are stored the fonts (see Fonts Map File). To this end, a very primitive but still useful shell script is provided: make_fonts_map.sh.

First, you need to find the directories which store the fonts you want to use, and extend the library path so that a2ps sees those directories. For instance, add:

AppendLibraryPath: /usr/local/share/ghostscript/fonts

Then run make_fonts_map.sh. It should be located in the afm/ directory of the system’s a2ps hierarchy. Typically /usr/local/share/a2ps/afm/make_fonts_map.sh.

This script asks a2ps for the library path, wanders in this path collecting AFM files, and digging information in them.

Once the script has finished, a file fonts.map.new was created. Check its integrity, and if it’s correct, either replace the old fonts.map with it, or rename fonts.map.new as fonts.map and place it higher in the library path (for instance in your ~/.a2ps/ directory).

6.2.1 Encoding Map File

See Map Files, for a description of the map files.

The meaningful lines of the encoding.map file have the form:

alias      key
iso-8859-1 latin1
latin1     latin1
l1         latin1

where

alias

specifies any name under which the encoding may be used. It influences the option ‘--encoding’, but also the encodings dynamically required, as for instance in the mail style sheet (support for MIME).

When encoding is asked, the lower case version of encoding must be equal to alias.

key

specifies the prefix of the file describing the encoding (key.edf, Encoding Description Files).

6.2.2 Encoding Description Files

The encoding description file describing the encoding key is named key.edf. It is subject to the same rules as any other a2ps file:

• - please make the name portable: alpha-numerical, at most 8 characters,
• - empty lines and lines starting by ‘#’ are ignored.

The entries are

‘Name:’

Specifies the full name of the encoding. Please, try to use the official name if there is one.

Name: ISO-8859-1

‘Documentation/EndDocumentation’

Introduces the documentation on the encoding (see Documentation Format). Typical informations expected are the other important names this encoding has, and the languages it covers.

Documentation
Also known as ISO Latin 1, or Latin 1.  It is a superset
of ASCII, and covers most West-European languages.
EndDocumentation

‘Substitute:’

Introduces a font substitution. The most common fonts (e.g., Courier, Times-Roman...) do not support many encodings (for instance it does not support Latin 2). To avoid that Latin 2 users have to replace everywhere calls to Courier, a2ps allows to specify that whenever a font is called in an encoding, then another font should be used.

For instance in iso2.edf one can read:

# Fonts from Ogonkify offer full support of ISO Latin 2
Substitute: Courier              Courier-Ogonki
Substitute: Courier-Bold         Courier-Bold-Ogonki
Substitute: Courier-BoldOblique  Courier-BoldOblique-Ogonki
Substitute: Courier-Oblique      Courier-Oblique-Ogonki

‘Default:’

Introduces the name of the font that should be used when a font (not substituted as per the previous item) is called but provides to poor a support of the encoding. The Courier equivalent is the best choice.

Default: Courier-Ogonki

‘Vector:’

Introduces the PostScript encoding vector, that is a list of the 256 PostScript names of the characters. Note that only the printable characters are named in PostScript (e.g., ‘bell’ in ASCII (^G) should not be named). The special name ‘.notdef’ is to be used when the character is not printable.

Warning. Make sure to use real, official, PostScript names. Using names such as ‘c123’ may be the sign you use unusual names. On the other hand PostScript names such as ‘afii8879’ are common.

6.2.3 Some Encodings

Most of the following information is a courtesy of Alis Technologies, Inc. and of Roman Czyborra’s page about The ISO 8859 Alphabet Soup. See What is an Encoding, is an instructive presentation of the encodings.

The known encodings are:

Encoding: ASCII (ascii.edf) ¶

US-ASCII.

Encoding: EUC-JP (euc-jp.edf) ¶

The EUC-JP encoding is a 8-bit character set widely used in Japan.

Encoding: HPRoman (hp.edf) ¶

The 8 bits Roman encoding for HP.

Encoding: IBM-CP437 (ibm-cp437.edf) ¶

This encoding is meant to be used for PC files with drawing lines.

Encoding: IBM-CP850 (ibm-cp850.edf) ¶

Several characters may be missing, especially Greek letters and some mathematical symbols.

Encoding: ISO-8859-1 (iso1.edf) ¶

The ISO-8859-1 character set, often simply referred to as Latin 1, covers most West European languages, such as French, Spanish, Catalan, Basque, Portuguese, Italian, Albanian, Rhaeto-Romanic, Dutch, German, Danish, Swedish, Norwegian, Finnish, Faroese, Icelandic, Irish, Scottish, and English, incidentally also Afrikaans and Swahili, thus in effect also the entire American continent, Australia and the southern two-thirds of Africa. The lack of the ligatures Dutch IJ, French OE and ,,German“ quotation marks is considered tolerable.

The lack of the new C=-resembling Euro currency symbol U+20AC has opened the discussion of a new Latin0.

Encoding: ISO-8859-2 (iso2.edf) ¶

The Latin 2 character set supports the Slavic languages of Central Europe which use the Latin alphabet. The ISO-8859-2 set is used for the following languages: Czech, Croat, German, Hungarian, Polish, Romanian, Slovak and Slovenian.

Support is provided thanks to Ogonkify.

Encoding: ISO-8859-3 (iso3.edf) ¶

This character set is used for Esperanto, Galician, Maltese and Turkish.

Support is provided thanks to Ogonkify.

Encoding: ISO-8859-4 (iso4.edf) ¶

Some letters were added to the ISO-8859-4 to support languages such as Estonian, Latvian and Lithuanian. It is an incomplete precursor of the Latin 6 set.

Support is provided thanks to Ogonkify.

Encoding: ISO-8859-5 (iso5.edf) ¶

The ISO-8859-5 set is used for various forms of the Cyrillic alphabet. It supports Bulgarian, Byelorussian, Macedonian, Serbian and Ukrainian.

The Cyrillic alphabet was created by St. Cyril in the 9th century from the upper case letters of the Greek alphabet. The more ancient Glagolithic (from the ancient Slav glagol, which means "word"), was created for certain dialects from the lower case Greek letters. These characters are still used by Dalmatian Catholics in their liturgical books. The kings of France were sworn in at Reims using a Gospel in Glagolithic characters attributed to St. Jerome.

Note that Russians seem to prefer the KOI8-R character set to the ISO set for computer purposes. KOI8-R is composed using the lower half (the first 128 characters) of the corresponding American ASCII character set.

Encoding: ISO-8859-7 (iso7.edf) ¶

ISO-8859-7 was formerly known as ELOT-928 or ECMA-118:1986. It is meant for modern Greek.

Encoding: ISO-8859-9 (iso9.edf) ¶

The ISO 8859-9 set, or Latin 5, replaces the rarely used Icelandic letters from Latin 1 with Turkish letters.

Support is provided thanks to Ogonkify.

Encoding: ISO-8859-10 (iso10.edf) ¶

Latin 6 (or ISO-8859-10) adds the last letters from Greenlandic and Lapp which were missing in Latin 4, and thereby covers all Scandinavia.

Support is provided thanks to Ogonkify.

Encoding: ISO-8859-13 (iso13.edf) ¶

Latin7 (ISO-8859-13) is going to cover the Baltic Rim and re-establish the Latvian (lv) support lost in Latin6 and may introduce the local quotation marks.

Support is provided thanks to Ogonkify.

Encoding: ISO-8859-15 (iso15.edf) ¶

The new Latin9 nicknamed Latin0 aims to update Latin1 by replacing some less needed symbols (some fractions and accents) with forgotten French and Finnish letters and placing the U+20AC Euro sign in the cell of the former international currency sign.

Support of the Euro symbol is provided thanks to Ogonkify.

Encoding: KOI8 (koi8.edf) ¶

KOI-8 is a subset of ISO-IR-111 that can be used in Serbia, Belarus etc.

Encoding: MS-CP1250 (ms-cp1250.edf) ¶

Microsoft’s CP-1250 encoding (aka CeP).

Encoding: MS-CP1251 (ms-cp1251.edf) ¶

Microsoft CP1251 is encoding used in Microsoft Windows for Cyrillic languages

Encoding: Macintosh (mac.edf) ¶

For the Macintosh encoding. The support is not sufficient, and a lot of characters may be missing at the end of the job (especially Greek letters).

7.3.1 Symbol

The style sheet Symbol introduces easy to type keywords to obtain the special characters of the PostScript font Symbol. The keywords are named to provide a LaTeX taste. These keywords are also the names used when designing a style sheet, hence to get the full list, see A Bit of Syntax.

If you want to know the correspondence, it is suggested to print the style sheet file of Symbol:

a2ps -g symbol.ssh

7.3.2 PreScript

PreScript has been designed in conjunction with a2ps. Since bold sequences, special characters etc. were implemented in a2ps, we thought it would be good to allow direct access to those features: PreScript became an input language for a2ps, where special font treatments are specified in an ssh syntax (see Style Sheets Implementation).

The main advantages for using PreScript are:

• - it is fairly simple,
• - a2ps is small and easy to install, hence it is available on every UNIX platform.

It can be a good candidate for generation of PostScript output (syntactic pretty-printers, generation of various reports etc.).

• Syntax
• PreScript Commands
• Examples

\Keyword{Problems using \keyword{recursive \copyright} calls}

\Keyword{Problems using} \keyword{recursive} \copyright \Keyword{calls}.

ypcat passwd |
 awk -F: \
   '{print "\Keyword{" $5 "} (" $1 ") \rightarrow\keyword{" $7 "}"}'\
 | a2ps -Epre -P

7.3.3 PreTeX

The aim of the PreTeX style sheet is to provide something similar to PreScript, but with a more LaTeX like syntax.

• Special characters
• PreTeX Commands
• Differences with LaTeX

If \forall x \in E, x \in F then E \subseteq F.

If $\forall x \in E, x \in F$ then $E \subseteq F$.

7.3.4 TeXScript

TeXScript is a replacement of the old version of PreScript: it combines both the a2ps-like and the LaTeX-like syntaxes through inheritance of both PreScript and PreTeX.

In addition it provides commands meant to ease processing of file for a2ps by LaTeX.

Everything between ‘%%TeXScript:skip’ and ‘%%TeXScript:piks’ will be ignored in TeXScript, so that there can be inserted command definitions for LaTeX exclusively.

The commands ‘\textbi’ (for bold-italic) and ‘\textsy’ (for symbol) do not exist in LaTeX. They should be defined in the preamble:

%%TeXScript:skip
\newcommand{\textbi}[1]{\textbf{\textit{#1}}}
\newcommand{\textsy}[1]{#1}
%%TeXScript:piks

There is no way in TeXScript to get an automatic numbering. There is no equivalent to the LaTeX environment enumerate. But every command beginning by \text is doubled by a command beginning by ‘\magic’. a2ps behaves the same way on both families of commands. Hence, if one specifies that arguments of those functions should be ignored in the preamble of the LaTeX document, the numbering is emulated. For instance

\begin{enumerate}
\magicbf{1.}\item First line
\magicbf{2.}\item Second line
\end{enumerate}

will be treated the same way both in TeXScript and LaTeX.

‘\header’ and ‘\footer’, are not understood by LaTeX.

7.5.1 Name and key

Every style sheet has both a key, and a name. The name can be clean and beautiful, with any character you might want. The key is in fact the prefix part of the file name, and is alpha-numerical, lower case, and less than 8 characters long.

Anywhere a2ps needs to recognize a style sheet by a name, it uses the key (in the sheets.map file, with the option ‘-E’, etc.).

As an example, C++ is implemented in a file called cxx.ssh, in which the name is declared to be ‘C++’.

The rationale is that not every system accepts any character in the file name (e.g., no ‘+’ in MS-DOS). Moreover, it allows to make symbolic links on the ssh files (e.g., ‘ln -s cxx.ssh c++.ssh’ let’s you use ‘-E c++’).

7.5.2 Comments

ssh files can include the name of its author, a version number, a documentation note and a requirement on the version of a2ps. For instance, if a style sheet requires a2ps version 4.9.6, then a2ps version 4.9.5 will reject it.

7.5.3 Alphabets

a2ps needs to know the beginning and the end of a word, especially keywords. Hence it needs two alphabets: the first one specifying by which letters an identifier can begin, and the second one for the rest of the word. If you prefer, a keyword starts with a character belonging to the first alphabet, and a character not pertaining to the second is a separator.

7.5.4 Case sensitivity

If the style is case insensitive, then matching is case insensitive (keywords, operators and sequences).

7.5.5 P-Rules

A P-rule (Pretty printing rule), or rule for short, is a structure which consists of two items:

lhs

left-hand side

its source string, with which the source file is compared;

rhs

right hand side

a list of faced strings which will replace the text matched in the pretty-printed output. A faced string is composed of

• - a string, or a reference to a part of the source string (see Back-reference Operator in Regex manual)
• - the face to use to print it

Just a short example: ‘(foo, bar, Keyword_strong)’ as a rule means that every input occurrence of ‘foo’ will be replaced by ‘bar’, written with the Keyword_strong face.

If the destination string is empty, then a2ps will use the source string. This is different from giving the source string as a destination string if the case is different. An example will make it fairly clear.

Let foobar be a case insensitive style sheet including the rules ‘(foo, "", Keyword)’ and ‘(bar, bar, Keyword)’. Then, on the input ‘FOO BAR’, a2ps will produce ‘FOO bar’ in Keyword.

a2ps implements two different ways to match a string. The difference comes from that some keywords are sensitive to the delimiters around them (such as ‘unsigned’ and ‘int’ in C, which are definitely not the same thing as ‘unsignedint’), and others not (in C, ‘!=’ is "different from" both in ‘a != b’ and ‘a!=b’).

The first ones are called keywords in a2ps jargon, and the seconds are operators. Operators are matched anywhere they appear, while keywords need to have separators around them (see Alphabets).

Let us give a more complicated example: that of the Yacc rules. A rule in Yacc is of the form:

a_rule : part1 part2 ;

Suppose you want to highlight these rules. To recognize them, you will write a regular expression specifying that:

1. it must start at the beginning of the line,
2. then there is string composed of symbols, which is what you want to highlight,
3. and a colon, which can be preceded by blank characters.

The regexp you want is: ‘/^[a-zA-Z0-9_]*[\t ]*:/’. But with the rule

/^[a-zA-Z0-9_]*[\t ]*:/, "", Label_strong

the blanks and the colon are highlighted too. Hence you need to specify some parts in the regexp (see Back-reference Operator in Regex manual), and use a longer list of destination strings. The correct rule is

(/^([a-zA-Z0-9_]*)([\t ]*:)/, \1 Label_strong, \2 Plain)

Since it is a bit painful to read, regexps can be spread upon several lines. It is strongly suggested to break them by groups, and to document the group:

(/^([a-zA-Z0-9_]*)/    # \1. Name of the rule
 /([\t ]*:)/           # \2. Trailing space and colon
 \1 Label_strong, \2 Plain)

7.5.6 Sequences

A sequence is a string between two markers, along with a list of exceptions. A marker is a fixed string. Typical examples are comments, string (with usually ‘"’ as opening and closing markers, and ‘\\’ and ‘\"’ as exceptions) etc. Three faces are used: one for the initial marker, one for the core of the sequence, and a last one for the final maker.

7.5.7 Optional entries

There are two levels of pretty-printing encoded in the style sheets. By default, a2ps uses the first level, called normal, unless the option ‘-g’ is specified, in which case, heavy highlighting is invoked, i.e., optional keywords, operators and sequences are considered.

7.6.1 A Bit of Syntax

Here are the lexical rules underlying the style sheet language:

• - the separators are white space, form feed, new line, and tab.
• - ‘#’ introduces a comment, ended at the end of the line.
• - special characters are the separators, plus ‘#’, ‘"’, ‘,’, ‘(’, ‘)’, ‘+’ and ‘/’. Any other character is a regular character.
• - the list of the structuring keywords is

  alphabet, alphabets, are, case, documentation, end, exceptions, first, in, insensitive, is, keywords, operators, optional, second, sensitive, sequences, style

• - the list of the keywords designating faces is

  Comment, Comment_strong, Encoding, Error, Index1, Index2, Index3, Index4, Invisible, Keyword, Keyword_strong, Label, Label_strong, Plain, String, Symbol, Tag1, Tag2, Tag3, Tag4

• - the list of keywords designating special sequences is

  C-char, C-string

• - the list of keywords representing special characters is

  ---, \Alpha, \Beta, \Chi, \Delta, \Downarrow, \Epsilon, \Eta, \Gamma, \Im, \Iota, \Kappa, \Lambda, \Leftarrow, \Leftrightarrow, \Mu, \Nu, \Omega, \Omicron, \Phi, \Pi, \Psi, \Re, \Rho, \Rightarrow, \Sigma, \Tau, \Theta, \Uparrow, \Upsilon, \Xi, \Zeta, \aleph, \alpha, \angle, \approx, \beta, \bullet, \cap, \carriagereturn, \cdot, \chi, \circ, \clubsuit, \cong, \copyright, \cup, \delta, \diamondsuit, \div, \downarrow, \emptyset, \epsilon, \equiv, \eta, \exists, \florin, \forall, \gamma, \geq, \heartsuit, \in, \infty, \int, \iota, \kappa, \lambda, \langle, \lceil, \ldots, \leftarrow, \leftrightarrow, \leq, \lfloor, \mu, \nabla, \neq, \not, \not\in, \not\subset, \nu, \omega, \omicron, \oplus, \otimes, \partial, \perp, \phi, \pi, \pm, \prime, \prod, \propto, \psi, \radicalex, \rangle, \rceil, \register, \rfloor, \rho, \rightarrow, \sigma, \sim, \spadesuit, \subset, \subseteq, \suchthat, \sum, \supset, \supseteq, \surd, \tau, \theta, \therefore, \times, \trademark, \uparrow, \upsilon, \varUpsilon, \varcopyright, \vardiamondsuit, \varphi, \varpi, \varregister, \varsigma, \vartheta, \vartrademark, \vee, \wedge, \wp, \xi, \zeta

  It is a good idea to print the style sheet ‘symbols.ssh’ to see them:

  a2ps symbols.ssh
  

• - a string starts and finishes with ‘"’, and may contain anything. Regular C escaping mechanism is used.
• - a regular expression starts and finishes with ‘/’, and may contain anything. Regular C escaping mechanism is used. Regexps can be split in several parts, a‘ la C strings (i.e., ‘/part 1/ /part 2/’).
• - any sequence of regular characters which is not a keyword, is a string (consider this as a shortcut, avoiding extraneous ‘"’).

7.6.2 Style Sheet Header

The definition of the name of the style sheet is:

style name is
  # body of the style sheet
end style

The following constructions are optional:

version

To define the version number of the style sheet

version is version-number

written

To define the author(s).

written by authors

Giving your email is useful for bug reports about style sheets.

written by "Some Body <Some.Body@some.whe.re>"

requires

To specify the version of a2ps it requires. a2ps won’t accept a file which requires a higher version number than its own.

requires a2ps a2ps-version-number

documentation

To leave extra comments people should read.

documentation is
   strings
end documentation

strings may be a list of strings, without comas, in which case new lines are automatically inserted between each item. See Documentation Format, for details on the format.

Please, write useful comments, not ‘This style is devoted to C files’, since the name is here for that, nor ‘Report errors to mail@me.somewhere’, since written by is there for that.

documentation is
    "Not all the keywords are used, to avoid too much"
    "bolding. Heavy highlighting (code(-g)code), covers"
    "the whole language."
end documentation

7.6.3 Syntax of the Words

There are two things a2ps needs to know: what is symbol consistent, and whether the style is case insensitive.

alphabet

To define two different alphabets, use

first alphabet is string
second alphabet is string

If both are identical, you may use the shortcut

alphabets are string

The default alphabets are

first alphabet is
  "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_"
second alphabet is
"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_\
0123456789"

Note that it is on purpose that no characters interval are used.

case

case insensitive        # e.g., C, C++ etc.
case sensitive          # e.g., Perl, Sather, Java etc.

The default is case insensitive.

7.6.4 Inheriting from Other Style Sheets

It is possible to extend an existing style. The syntax is:

ancestors are
   ancestor_1[, ancestor_2...]
end ancestors

where ancestor1 etc. are style sheet keys.

For semantics, the rules are the following:

• - the ancestors are read in order;
• - the definition of the current style is read last;
• - it is always the last item read which wins (last defined alphabets, case sensitivity, keywords, operators and sequences).

As an example, both C++ and Objective C style sheets extend the C style sheet:

style "Objective C" is
#[...]
ancestors are
   c
end ancestors
#[...]
end style

To the biggest surprise of the author, mutually dependent style sheets do work!

7.6.5 Syntax for the P-Rules

See P-Rules, for the definition of P-rule.

Because of various short cuts, there are many ways to declare a rule:

rules     ::= rule_1 ‘,’ rule_2...
rule      ::= ‘(’ lhs rhs ‘)’
           | lhs srhs ;
lhs       ::= string | regex ;
rhs       ::= srhs ‘,’ ...
srhs      ::= latex-keyword | expansion face
expansion ::= string | ‘\’num | <nothing>;
face      ::= face-keyword | <nothing>;

The rules are the following:

• - If the left-hand side (lhs) is a regular expression, then it is compiled with the following syntax bits:

  #define RE_SYNTAX_A2PS \
    (/* Allow char classes. */					\
      RE_CHAR_CLASSES						\
    /* Be picky. */						\
    | RE_CONTEXT_INVALID_OPS					\
    /* Allow intervals with `{' and `}', forbid invalid ranges. */\
    | RE_INTERVALS | RE_NO_BK_BRACES | RE_NO_EMPTY_RANGES		\
    /* `(' and `)' are the grouping operators. */			\
    | RE_NO_BK_PARENS						\
    /* `|' is the alternation. */					\
    | RE_NO_BK_VBAR)
  

  Basically it means that all of the possible operators are used, and that they are in non-backslashed form. For instance ‘(’ and ‘)’ stand for the group operator, while ‘\\(’ stands for the character ‘(’. See Regular Expression Syntax in Regex manual, for a detailed description of the regular expressions.

• - If no expansion is specified, then the matched string is used. For instance ‘(/fo*/, NULL, Keyword)’ applied on the source ‘fooooo’ produces ‘fooooo’ in Keyword.
• - If no face is given, then
  • - if the context defines the default face, then this face is used;
  • - if no default face is given, PLAIN is used.

7.6.6 Declaring the keywords and the operators

Basically, keywords and operators are lists of rules. The syntax is:

keywords are
  rules
end keywords

or

keywords in face-keyword are
  rules
end keywords

in which case the default face is set to face-keyword.

As an example:

keywords in Keyword_strong are
  /foo*/,
  "bar" "BAR" Keyword,
  -> \rightarrow
end keywords

is valid.

The syntax for the operators is the same, and both constructs can be qualified with an optional flag, in which case they are taken into account in the heavy highlighting mode (see Pretty Printing Options).

This is an extract of the C style sheet:

optional operators are
   -> \rightarrow,
   && \wedge,
   || \vee,
   != \neq,
   == \equiv,
   # We need to protect these, so that <= is not replaced in <<=
   <<=,
   >>=,
   <= \leq,
   >= \geq,
   ! \not
end operators

Note how ‘<<=’ and ‘>>=’ are protected (there are defined to be written as is when met in the source). This is to prevent the two last characters of ‘<<=’ from being converted into a ‘less or equal’ sign.

The order in which you define the elements of a category (but the sequences) does not matter. But since a2ps sorts them at run time, it may save time if the alphabetical C-order is more or less followed.

You should be aware that when declaring a keyword with a regular expression as lhs, then a2ps automatically makes this expression matching only if there are no character of the first alphabet both just before, and just after the string.

In term of implementation, it means that

keywords are
  /foo|bar/
end keywords

is exactly the same as

operators are
  /\\b(foo|bar)\\b/
end operators

This can cause problems if you use anchors (e.g. $, or ^) in keywords: the matcher will be broken. In this particular case, define your keywords as operators, taking care of the ‘\\b’ by yourself.

See Match-word-boundary Operator in Regex manual, for details on ‘\b’.

7.6.7 Declaring the sequences

Sequences admit several declarations too:

sequences      ::= sequences are
                     sequence_1 ‘,’ sequence_2...
                   end sequences
sequence       ::= rule in_face close_opt exceptions_opt
                 | C-string
                 | C-char
                 ;
close_opt      ::= rule
                 | closers are
                     rules
                   end closers
                 | <nothing>
                 ;
exceptions_opt ::= exceptions are
                     rules
                   end exceptions
                 | <nothing>
                 ;

The rules are:

• - The default face is then in_face.
• - If no closing rule is given, ‘"\n"’ (i.e., end-of-line) is used.

As a first example, here is the correct definition for a C string:

sequences are
 "\"" Plain String "\"" Plain
     exceptions are
        "\\\\", "\\\""
     end exceptions
end sequences

Since a great deal of languages uses this kind of constructs, you may use C-string to mean exactly this, and C-char for manifest characters defined the C way.

The following example comes from ssh.ssh, the style sheet for style sheet files, in which there are two kinds of pseudo-strings: the strings (‘"example"’), and the regular expressions (‘/example/’). We do not want the content of the pseudo-strings in the face String.

sequences are
  # The comments
  "#" Comment,

  # The name of the style sheet
  "style " Keyword_strong (Label + Index1) " is" Keyword_strong,

  # Strings are exactly the C-strings, though we don't want to
  # have them in the "string" face
  "\"" Plain "\""
     exceptions are
        "\\\\", "\\\""
     end exceptions,

  # Regexps
  "/" Plain "/"
     exceptions are
        "\\\\", "\\\/"
     end exceptions

end sequences

The order between sequences does matter. For instance in Java, ‘/**’ introduces strong comments, and ‘/*’ comments. ‘/**’ must be declared before ‘/*’, or it will be hidden.

There are actually some sequences that could have been implemented as operators with a specific regular expression (that goes up to the closer). Nevertheless be aware of a big difference: regular expression are applied to a single line of the source file, hence, they cannot match on several lines. For instance, the C comments,

/*
 * a comment
 */

cannot be implemented with operators, though C++ comments can:

//
// a comment
//

7.6.8 Checking a Style Sheet

Once your style sheet is written, you may want to let a2ps perform simple tests on it (e.g., checking there are no rules involving upper case characters in a case insensitive style sheet, etc.). These tests are performed when verbosity includes the style sheets.

you may also want to use the special convention that when a style sheet is required with a suffix, then a2ps will not look at it in its library path, but precisely from when you are.

Suppose for instance you extended the c.ssh style sheet, which is in the current directory, and is said case insensitive. Run

ubu $ a2ps foo.c -Ec.ssh -P void -v sheets
# Long output deleted
Checking coherence of "C" (c.ssh)
a2ps: c.ssh:`FILE' uses upper case characters
a2ps: c.ssh:`NULL' uses upper case characters
"C" (c.ssh) is corrupted.
---------- End of Finalization of c.ssh

Here, it is clear that C is not case insensitive.

7.7.1 Example and syntax

First of all, here is a sample of a ChangeLog file, taken from the misc/ directory of the original a2ps package:

Sun Apr 27 14:29:22 1997  Akim Demaille  <demaille@inf.enst.fr>

        * base.ps: Merged in color.ps, since now a lot is
          common [added box and underline features].

Fri Apr 25 14:05:20 1997  Akim Demaille  <demaille@inf.enst.fr>

        * color.ps: Added box and underline routines.

Mon Mar 17 20:39:11 1997  Akim Demaille  <demaille@gargantua.enst.fr>

        * base.ps: Got rid of CourierBack and reencoded_backspace_font.
          Now the C has to handle this by itself.

Sat Mar  1 19:12:22 1997  Akim Demaille  <demaille@gargantua.enst.fr>

        * *.enc: they build their own dictionaries, to ease multi
          lingual documents.

The syntax is really simple: A line specifying the author and the date of the changes, then a list of changes, all of them starting with an star followed by the name of the files concerned, then optionally between parentheses the functions affected, and then some comments.

7.7.2 Implementation

Quite naturally the style will be called ChangeLog, hence:

style ChangeLog is
written by "Akim Demaille <demaille@inf.enst.fr>"
version is 1.0
requires a2ps 4.9.5

documentation is
   "This is a tutorial style sheet.\n"
end documentation
  ...
end style

A first interesting and easy entry is that of function names, between ‘(’ and ‘)’:

sequences are
  "(" Plain Label ")" Plain
end sequences

A small problem that may occur is that there can be several functions mentioned separated by commas, that we don’t want to highlight this way. Commas, here, are exceptions. Since regular expressions are not yet implemented in a2ps, there is a simple but stupid way to avoid that white spaces are all considered as part of a function name, namely defining two exceptions: one which captures a single comma, and a second, capturing a comma and its trailing space.

For the file names, the problem is a bit more delicate, since they may end with ‘:’, or when starts the list of functions. Then, we define two sequences, each one with one of the possible closers, the exceptions being attached to the first one:

sequences are
  "* " Plain Label_strong ":" Plain
     exceptions are
        ", " Plain, "," Plain
     end exceptions,
  "* " Plain Label_strong " " Plain
end sequences

Finally, let us say that some words have a higher importance in the core of text: those about removing or adding something.

keywords in Keyword_strong are
  add, added, remove, removed
end keywords

Since they may appear in lower or upper, of mixed case, the style will be defined as case insensitive.

Finally, we end up with this style sheet file, in which an optional highlighting of the mail address of the author is done. Saving the file is last step. But do not forget that a style sheet has both a name as nice as you may want (such as ‘Common Lisp’), and a key on which there are strict rules: the prefix must be alpha-numerical, lower case, with no more than 8 characters. Let’s chose chlog.ssh.

# This is a tutorial on a2ps' style sheets
style ChangeLog is
written by "Akim Demaille <demaille@inf.enst.fr>"
version is 1.0
requires a2ps 4.9.5

documentation is
   "Second level of high lighting covers emails."
end documentation

sequences are
  "(" Plain Label ")" Plain
     exceptions are
        ", " Plain, "," Plain
     end exceptions,
  "* " Plain Label_strong ":" Plain
     exceptions are
        ", " Plain, "," Plain
     end exceptions,
  "* " Plain Label_strong " " Plain
end sequences

keywords in Keyword_strong are
  add, added, remove, removed
end keywords

optional sequences are
   < Plain Keyword > Plain
end sequences
end style

As a last step, you may which to let a2ps check your style sheet, both its syntax, and common errors:

ubu $ a2ps -vsheet -E/tmp/chlog.ssh ChangeLog -P void
Long output deleted
Checking coherence of "ChangeLog" (/tmp/chlog.ssh)
"ChangeLog" (/tmp/chlog.ssh) is sane.
---------- End of Finalization of /tmp/chlog.ssh

It’s all set, your style sheet is ready!

7.7.3 The Entry in sheets.map

The last touch is to include the pattern rules about ChangeLog files (which could appear as ChangeLog.old etc.) in sheets.map:

# ChangeLog files
chlog:  /ChangeLog*/

This won’t work... Well, not always. Not for instance if you print misc/ChangeLog. This is not a bug, but truly a feature, since sometimes one gets more information about the type of a file from its path, than from the file name.

Here, to match the preceding path that may appear, just use ‘*’:

# ChangeLog files
chlog:  /*ChangeLog*/

If you want to be more specific (FooChangeLog should not match), use:

# ChangeLog files
chlog:  /ChangeLog*/ /*\/ChangeLog*/

7.7.4 More Sophisticated Rules

The example we have presented until now uses only basic features, and does not take advantage of the regexp. In this section we should how to write more evolved pretty printing rules.

The target will be the lines like:

Sun Apr 27 14:29:22 1997  Akim Demaille  <demaille@inf.enst.fr>

Fri Apr 25 14:05:20 1997  Akim Demaille  <demaille@inf.enst.fr>

There are three fields: the date, the name, the mail. These lines all start at the beginning of line. The last field is the easier to recognize: is starts with a ‘<’, and finishes with a ‘>’. Its rule is then ‘/<[^>]+>/’. It is now easier to specify the second: it is composed only of words, at least one, separated by blanks, and is followed by the mail: ‘/[[:alpha:]]+([ \t]+[[:alpha:]]+)*/’. To concatenate the two, we introduce optional blanks, and we put each one into a pair of ‘(’-‘)’ to make each one a recognizable part:

([[:alpha:]]+([ \t]+[[:alpha:]]+)*)
(.+)
(<[^>]+>)

Now the first part is rather easy: it starts at the beginning of the line, finishes with a digit. Once again, it is separated from the following field by blanks. Split by groups (see Grouping Operators in Regex manual), we have:

^
([^\t ].*[0-9])
([ \t]+)
([[:alpha:]]+([ \t]+[[:alpha:]]+)*)
(.+)
(<[^>]+>)

Now the destination is composed of back references to those groups, together with a face:

# We want to highlight the date and the maintainer name
optional operators are
  (/^([^\t ].*[0-9])/                        # \1. The date
   /([ \t]+)/                                # \2. Spaces
   /([[:alpha:]]+([ \t]+[[:alpha:]]+)*)/     # \3. Name
   /(.+)/                                    # \5. space and <
   /(<[^>]+)>/                               # \6. email
   \1 Keyword, \2 Plain, \3 Keyword_strong,
   \5 Plain, \6 Keyword, > Plain)
end operators

Notice the way regexps are split, to ease reading.

7.7.5 Guide Line for Distributed Style Sheets

This section is meant for people who wish to contribute style sheets. There is a couple of additional constraints, explained here.

The Copyright

Please, do put a copyright in your file, the same as all other distributed files have: it should include your name, but also the three paragraphs stating the sheet is covered by the GPL. I won’t distribute files without these paragraphs.

The Version

Do put a version number, so that people can track evolutions.

The Requirements

Make sure to include a requirement on the needed version of a2ps. If you don’t know what to put, just put the version of the a2ps you run.

The Documentation

The documentation string is mandatory. Unless the language your style sheet covers is widely known, please document a bit what the style sheet is meant for. If there were choices you made, if there are special behaviors, document them.

The sheets.map Entries

Put in a comment on the sheets.map lines that correspond to your style sheet.

A Test File

It is better to give a test file, as small as possible, that contains the most specific and/or most difficult contructs that your style sheet supports. I need to be able to distribute this file, therefore, do not put anything that is copyrighted.

Finally, make sure your style sheet behaves well! (see Checking a Style Sheet)

8.6.1 Definition of the faces

There are three things that define a face:

Its font

You should never call the font by yourself, because sometimes a2ps may decide that another font would be better. This is what happens for instance if a font does not support the encoding you use.

Hence, never set the font by yourself, but ask a2ps to do it. This is done through a line:

%Face: face real-font-name size

This line tells a2ps that the font of face is real-font-name. It will replace this line by the correct PostScript line to call the needed font, and will do everything needed to set up the font.

The size of the text body is bfs.

Its background color

There are two cases:

1. You want a background color, then give the RGB (see 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
   

Its foreground color

As BG, call FG with an RGB ratio:

0 0.5 0 FG

Its underlining

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

true UL

Its boxing

Requiring a boolean, BX let’s a face have a box drawn around.

8.6.2 Prologue File Format

Prologue files for a2ps must have ‘pro’ as suffix. Documentation (reported with ‘--list-prologues’) can be included in the comment part:

Documentation
This prologue is the same as the prologue code(pb)code, but using
the bold version of the fonts.
EndDocumentation
% code follows this line

See Documentation Format, for more on the format.

8.6.3 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=prologues’), to drop it in one of a2ps directories (say ‘$HOME/.a2ps’, 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 Hawaiian sea green (you are definitely a fine art amateur).

Then you need to look for ‘k’ and ‘K’:

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

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

and turn it into:

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

/K {
  0.4 0.2 0 true BG
  0.5 1 1 FG
%Face: Keyword_strong Times-BoldItalic bfs
  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-Roman 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.

9.1.1 Invoking card

card [options] applications [-- -options]

card is a shell script which tries to guess how to get your applications’ help message (typically by the options ‘--help’ or ‘-h’), and pretty prints it thanks to a2ps (or the content of the environment variable ‘A2PS’ if it is set). -options are passed to a2ps.

Supported options are:

Option: -h ¶

Option: --help ¶

print a short help message and exit successfully.

Option: -V ¶

Option: --version ¶

report the version and exit successfully.

Option: -q ¶

Option: --quiet ¶

Option: --silent ¶

Run silently.

Option: -D ¶

Option: --debug ¶

enter in debug mode.

Option: -l language ¶

Option: --language=language ¶

specify the language in which the reference card should be printed. language should be the symbol used by LC_ALL etc. (such as ‘fr’, ‘it’ etc.).

If the applications don’t support internationalization, English will be used.