1. Introduction

This document describes GNU a2psversions may be found on the a2ps

We tried to make this document informative and pleasant. It tries to be more than a plain reference guide, and intends to offer information about the concepts or tools etc. that are related to printing PostScript. This is why it is now that big: to offer you all the information you might want, not because a2psdifficult to use. See section Glossary, for technical words or even general information.

Please, send us emailcards :). Whatever the comment is, or if you just like a2ps@c, write to Miguel Santana and Akim Demaille.

1.1 Description

a2ps

The format used is nice and compact: normally two pages on each physical page, borders surrounding pages, headers with useful information (page number, printing date, file name or supplied header), line numbering, pretty-printing, symbol substitution etc. This is very useful for making archive listings of programs or just to check your code in the bus. Actually a2psprinted with a2ps

While at the origin its names was derived from “ASCII to PostScript”, today we like to think of it as “Any to PostScript”. Indeed, a2pssupports delegations, i.e., you can safely use a2psPostScript, LaTeX, JPEG etc., even compressed.

A short list of features of a2ps

• - Customizable through various configuration files (see section Configuration Files)
• - Powerful escapes to define the headers, table of contents etc. the way you want (see section Escapes);
• - Variables to push even further the customizability in a comfortable manner (see section Your Variables);
• - Open approach of encodings (see section Encodings);
• - Excellent support of the Latin 2, 3, 4, 5 and 6 encodings, thanks to Ogonkify (see (ogonkify)Top section ‘Overview’ in Ogonkify manual), written by Juliusz Chroboczek.
• - Fully customizable output style: fonts, background and foreground colors, line numbering style etc. (see section Designing PostScript Prologues).
• - Possibility to delegate the processing of some files to other filters (see section Your Delegations).
• - Many contributions, e.g., pretty-print diffs, print reference cards of programs, sanitize broken PostScript files, print Duplex on Simplex printers etc. (see section Contributions).
• - And finally, the ability to pretty-print sources written in quite a few various languages (see section Pretty Printing).

1.2 Reporting Bugs

We try hard to make a2psBut sometimes there can still be bad surprises, even after having compiled and checked a2ps

You may encounter some of these problems yourself. In any case, please never abandon without giving us a chance. We need information from everybody so that mistakes get fixed as fast as possible.

So, if you have a problem (configuration error, compilation error, runtime error, documentation error or unclear), first check in the FAQ (see section Frequently asked questions), then on the page but it appears that the version of a2psconsider upgrading.

If the problem persists, send us a mail (bug-a2ps@gnu.org) which subject is ‘a2ps version: short-description’ and which content mentions the name of your machine and OS, the version of a2ps@c, every detail you have on your compiler, and as much traces as possible (the error messages you get on the screen, or the output of make when it fails etc.).

Be sure to get a quick answer.

1.3 a2ps

There is a mailing list in which are discussed various topics around a2ps@c: a2ps@gnu.org. There are also announcements about the version in alpha testing, requests for comments, new sheets, etc.

To subscribe to the list, send a mail to a2ps-request@gnu.org, with ‘subscribe’ in the body.

Please, note that the mailing list is by no means a bug reporting address: use bug-a2ps@gnu.org instead.

1.4 Helping the Development

If you like a2psyou can do.

Testing

You just can’t imagine how hard it is to make sure that the program that works perfectly here will work on your machine. Actually, in general the last weeks before a release are mostly dedicated to (Unix) portability issues.

So we need beta-testers! To be one is fairly simple: subscribe to the mailing-list where the betas are announced and distributed.

Translation

The interface of a2psthe messages can be translated, without having to look at the code of a2ps@c: you don’t need to be a programmer at all. All the details are available on the a2ps translation page.

Style Sheets

Since a2psshould be checked and improved. There are too many so that the authors work on them. Therefore if you feel your favorite language is not honored as it should be, improve the style sheet! (see section Pretty Printing for details.)

Encodings

a2pstoday by a2ps@c, you can easily provide the support yourself. Honestly, the trickiest part is to find correct free fonts that support your mother tongue (see section Encoding Files, to know more).

Fonts

There are still some characters missing in Ogonkify. See the list of missing characters and the Ogonkify home page for details.

Documentation

If you feel something is missing or is unclear, send us your contributions.

Porting

Porting a program to special architectures (MS-DOS, OS/2 etc.), or building special packages (e.g., RPM) requires having an access to these architectures. If you feel like maintaining such a port, tell us.

Features

Well, if you feel like doing something else, go ahead! But contact us, because we have quite a big stack of things we want to do or have started to do, and synchronizing might be useful.

2. User’s Guide

This chapter is devoted to people who don’t know a2psgive a soft and smooth introduction to the most useful features. For a reference manual, see Invoking a2ps. For the definition of some words, see Glossary, for questions you have, see Frequently asked questions.

2.1 Purpose

a2psand makes a PostScript file out of it. Typically output is sent to a printer.

2.2 How to print

To print a file ‘doc.txt’, just give it to a2ps@c: the default setting should be the one you’d like:

gargantua ~ $ a2ps doc.txt
[doc.txt (plain): 9 pages on 5 sheets]
[Total: 9 pages on 5 sheets] sent to the default printer

a2pstwo columns of text on a single face of the sheet. Indeed, by default a2ps

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 a2pstwo 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(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 section 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 section Input Options, option ‘--prologue’), and you can even design yours (see section 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 section 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

a2psIn 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, a2pstwo 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

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

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(See section Glossary, for definitions). The option to specify Duplex printing is ‘--sides=mode’ (see section 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 a2psthe 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.3 Important parameters

Many things are parameterizable in a2ps@c, but two things are just essential to make sure everything goes right:

The paper

Make sure that the paper a2ps(See section Sheet Options, option ‘--medium’).

The encoding

Make sure that the encoding a2psstandard alphabet in your country (See section Input Options, option ‘--encoding’).

Both values may be checked with ‘a2ps --list=defaults’.

2.4 Localizing

a2psmother tongue. It uses three special features for non-English languages:

the tongue

i.e., the language used by the interface,

the date

i.e., the format and the words used in the language to specify a date.

To enable these features, properly set your environment variable LANG (see the documentation of your system, for instance ‘man locale’, ‘man environ’ etc.).

The problem with this approach is that a lot more than just messages and time information is affected: especially the way numbers are written changes, what may cause problems with awk and such.

So if you just want messages and time format to be localized, then define:

set LC_MESSAGES=fr ; export LC_MESSAGES
set LC_TIME=fr     ; export LC_TIME

2.5 Interfacing with Other Programs

Here are some tips on how to use a2ps

2.5.1 Interfacing With a Mailer

When you print from a mailer (or a news reader), your mailer calls a tool, say a2psa2psbetter results, make sure to tell a2psoption ‘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 a2pswith 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 Netscape

This is actually valid for any program that generates PostScript that you want to post-process with a2ps@c. 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 a2psdelegate. In case one one these conditions is not met, use:

a2ps -ZEps

Do not forget to tell Netscape whether your printer supports colors, and the type of paper it uses.

3. Invoking a2ps

Calling a2ps

a2ps Options... Files...

If no Files... are given, a2ps‘-’ appears in the Files..., it designates the standard input too.

3.1 Command line options

To read the options and arguments that you give, a2psgetopt, hence:

• - the options (short with arguments or long) must be separated by spaces.
• - the order between options and files does not matter: ‘a2ps -4m main.c’ and ‘a2ps main.c -4m’ are identical.
• - the order between options does matter, especially between options that influence the same parameters. For instance ‘a2ps -1 -l132’ is not the same as ‘a2ps -l132 -1’ (the latter being equivalent to ‘a2ps -1’).
• - short options may be grouped together: ‘a2ps -4mg main.c -P printer’
• - when there are no ambiguities, long options can be abbreviated, e.g., ‘--pro’ will be understood as ‘--prologue’,
• - ‘--’ ends the options. Anything behind ‘--’ is considered to be a file: ‘a2ps -- -2’ prints the file ‘-2’(1).

Here after a boolean is considered as true (i.e. setting the option on), if boolean is ‘yes’, or ‘1’; as false if it equals ‘no’ or ‘0’; and raise an error otherwise. The corresponding short option takes no arguments, but corresponds to a positive answer.

When an argument is presented between square brackets, it means that it is optional. Optional arguments to short option must never be separated from the option.

3.1.1 Tasks Options

Task options specify the task a2psit 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 section 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@c.

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@c’ status with respect to topic, and exit successfully. topic can be any non-ambiguous abbreviation of:

‘defaults’

‘options’

Give an extensive report on a2ps

‘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 section Your Delegations.

‘encodings’

Detailed list of known encodings. See section Some Encodings.

‘media’

Detailed list of known media. See section Your Media.

‘prologues’

Detailed list of PostScript prologues. See section Designing PostScript Prologues.

‘printers’

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

‘style-sheets’

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

‘user-options’

Detailed list of the user options. See section Your Shortcuts.

‘variables’

Detailed list of the variables. See section 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@c.

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
• - 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 section Available Escapes),

‘all’

all the messages.

When a2psA2PS_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 a2pseven a chance to read the command line.

Option: -=shortcut

Option: --user-option=shortcut

use the shortcut defined by the user. See section 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 section 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’.

‘A4dj’, ‘Letterdj’ are also defined for Desk Jet owners, since that printer needs bigger margins.

The special medium ‘libpaper’ means that you want a2psask the library libpaper for the medium to use. This choice is valid only if libpaper was available when a2psSee the man page of paperconf for more information.

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 section 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 section 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 a2psreadable version of the text described, or a pretty-printed version of the describing file (see section 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 section 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 section 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 section 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 section 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@c. prologue must be in a file named ‘prologue.pro’, which must be in a directory of your library path (see section Library Files). Available prologues are:

‘bold’

This style is meant to replace the old option -b of a2ps 4.3. It is a copy of the black and white prologue, but in which all the fonts are in Bold.

‘bw’

Style is plain: pure black and white, with standard fonts.

‘color’

Colors are used to highlight the keywords.

‘diff’

This style is meant to be used with the udiff, wdiff style sheets, to underline the differences. New things are in bold on a diff background, while removed sequences are in italic.

‘fixed’

This style uses exclusively fixed size fonts. You should use this style if you want the tabulations to be properly printed.

There are no means to use a fixed size Symbol font, therefore you should not use the heavy highlighting style.

‘gray’

Gray background is used for comments and labels.

‘gray2’

Black background is used for comments and labels.

‘matrix’

The layout is the same as ‘bw’, but alternating gray and white lines. There are two macros defining the behavior: ‘pro.matrix.cycle’ defines the length of the cycle (number of white and gray lines). It defaults to 6. ‘pro.matrix.gray’ defines the number of gray lines. Default is 3.

‘ul’

This style uses bold faces and underlines, but never italics. This is particularly meant for printing formatted man pages.

Option: --print-anyway=boolean

force binary printing. By default, the whole print job is stopped as soon as a binary file is detected. To detect such a file we make use of a very simple heuristic: if the first sheet of the file contains more than 40% of non-printing characters, it’s a binary file. a2psfile(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 a2psbut will call an application which handles the file in another way. If delegation is off, then a2ps

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

Option: --toc[=format]

Generate a Table of Contents, which format is an escape (see section Escapes) processed as a PreScript file (see section 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 section 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@c.

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 section 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 a2psproduces. 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, a2pswhen 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 a2psas 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 section 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 a2pspages 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 section 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 section 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.

a2psprinters won’t fail.

Option: -K

Option: --no-page-prefeed

disable page prefeeding.

3.2 Escapes

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

3.2.1 Use of Escapes

They are used in several places in a2ps@c:

Page markers

Headers, footers, titles and the water mark (see section Headings Options), in general to print the name of file, page number etc. On a new sheet a2psthen 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 section Your Printers).

Delegation

To specify the command associated to a delegation (see section 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 section 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 section 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

‘#?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 section 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

‘#{key}’

expansion of the value of the variable key if defined, nothing otherwise (see section 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 section Predefined Variables).

‘%A’

the localized equivalent for ‘Printed by User Name from Host Name’. The variables ‘user.name’ and ‘user.host’ are used (see section 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, a2psremoves them at the end of the job. It is useful for the delegations (see section Your Delegations) and for the printer commands (see section 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 section Predefined Variables).

‘$n’

input file name without the directory part.

‘%N’

shortcut for the value of the variable ‘user.name’ (see section 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 section 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 a2psfiles, 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@c.

‘#w’

medium width in PostScript points

‘%W’

current date in ‘mm/dd/yy’ format

‘$W’

file modification date in ‘mm/dd/yy’ format

4. Configuration Files

a2psorder, they are:

1. the system configuration file (usually ‘/usr/local/etc/a2ps.cfg’) unless you have defined the environment variable ‘A2PS_CONFIG’, in which case a2ps
2. the user’s home configuration file (‘$HOME/.a2ps/a2psrc’)
3. the local file (‘./.a2psrc’)

Because a2pslocal lpr command) and architecture independent information (such as the type of your printers), users have found useful that ‘a2ps.cfg’ be dedicated to architecture dependent information. A sub configuration file, ‘a2ps-site.cfg’ (see section Including Configuration Files) is included from ‘a2ps.cfg’.

The file ‘a2ps.cfg’ is updated when you update a2ps@c, while ‘a2ps-site.cfg’ is not, to preserve local definitions.

In the configuration files, empty lines and lines starting with ‘#’ are comments.

The other lines have all the following form:

Topic: Arguments

where Topic: is a keyword related to what you are customizing, and Arguments the customization. Arguments may be spread on several lines, provided that the last character of a line to continue is a ‘\’.

In the following sections, each Topic: is detailed.

4.1 Including Configuration Files

Configuration Setting: Include: file

Include (read) the configuration file. if file is a relative path (i.e., it does not start with ‘/’), then it is relatively to the current configuration file.

This is especially useful for the site specific configuration file ‘etc/a2ps.cfg’: you may tune your printers etc. in a separate file for easy upgrade of a2ps

4.2 Your Library Path

To define the default library path, you can use:

Configuration Setting: LibraryPath: path

Set the library path the path.

Configuration Setting: AppendLibraryPath: path

Add path at the end of the current library path.

Configuration Setting: PrependLibraryPath: path

Add path at the beginning of the current library path.

Note that for users configuration files, it is better not to set the library path, because the system’s configuration has certainly been built to cope with your system’s peculiarities. Use ‘AppendLibraryPath:’ and ‘PrependLibraryPath:’.

4.3 Your Default Options

Configuration Setting: Options: options+

Give a2pssequence of regular command line options (see section Invoking a2ps).

It is the correct way to define the default behavior you expect from a2ps@c. If for instance you want to use Letter as medium, then use:

Options: --medium=Letter

It is exactly the same as always giving a2ps‘--medium=Letter’ at run time.

The quoting mechanism is the same as that of a shell. For instance

Options: --right-title="Page $p" --center-title="Hello World!"
Options: --title="arg 'Jack said \\\"hi\\\"' has double quotes"

4.4 Your Media

Configuration Setting: Medium: name dimensions

Define the medium name to have the dimensions (in PostScript points, i.e., 1/72 of inch).

There are two formats supported:

long

in which you must give both the size of the whole sheet, and the size of the printable area:

# A4 for Desk Jets # name w h llx lly urx ury Medium: A4dj 595 842 24 50 571 818

where wxh are the dimension of the sheet, and the four other stand for lower left x and y, upper right x and y.

short

in which a surrounding margin of 24 points is used

# A4 # name w h Medium: A4 595 842

is the same as

# A4 # name w h Medium: A4 595 842 24 24 571 818

4.5 Your Printers

A general scheme is used, so that whatever the way you should address the printers on your system, the interface is still the same. Actually, the interface is so flexible, that you should understand ‘named destination’ when we write ‘printer’.

Configuration Setting: Printer: name PPD-key destination

Configuration Setting: Printer: name destination

Configuration Setting: Printer: name PPD-key

Specify the destination of the output when the option ‘-P name’ is given. If PPD-key is given, declare the printer name to be described by the PPD file ‘PPD-key.ppd’. If destination is not given, used that of the ‘UnknownPrinter:’.

The destination must be of one of the following forms:

‘| command’

in which case the output is piped into command.

‘> file’

in which case the output is saved into file.

Configuration Setting: UnknownPrinter: [PPD-key] destination

Specify the destination of the output when when the option ‘-P name’ is given, but there is no ‘Printer:’ entry for name.

Configuration Setting: DefaultPrinter: [PPD-key] destination

Specify the destination of the output when when the option ‘-d’ (send to default output) is given.

Escapes expansion is performed on destination (see section Escapes). Recall that ‘#o’ is evaluated to the destination name, i.e., the argument given to ‘-P’.

For instance

# My Default Printer is called dominique
DefaultPrinter: | lp -d dominique

# `a2ps foo.c -P bar' will pipe into `lp -d bar'
UnknownPrinter: | lp -d #o

# `a2ps -P foo' saves into the file `foo'
Printer: foo > foo.ps
Printer: wc | wc
Printer: lw | lp -d printer-with-a-rather-big-name

# E.g. `a2ps foo.c bar.h -P file' will save into `foo.c.ps'
Printer: file > $n.#.

# E.g. `a2ps foo.c bar.h -P home' will save into `foo.ps'
# in user's home
Printer: home > ${HOME}/$N.#.

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

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

4.6 Your Shortcuts

You can define some kind of ‘Macro Options’ which stand for a set of options.

Configuration Setting: UserOption: shortcut options...

Define the shortcut to be the list of options.... When a2psis called with ‘-=shortcut’ (or ‘--user-option=shortcut’), consider the list of options....

Examples are

# This emulates a line printer: no features at all
# call a2ps -=lp to use it
UserOption: lp -1m --pretty-print=plain -B --borders=no

# When printing mail, I want to use the right style sheet with strong
# highlight level, and stripping `useless' headers.
UserOption: mail -Email -g --strip=1

4.7 Your PostScript magic number

a2psAdobe said

Thou shalt start your PostScript DSC conformant files with

%!PS-Adobe-3.0

The bad news is that some printers will reject this header. Then you may change this header without any worry since the PostScript produced by a2psare no PostScript printers that don’t understand these files..

Configuration Setting: OutputFirstLine: magic-number

Specify the header of the produced PostScript file to be magic-number. Typical values include ‘%!PS-Adobe-2.0’, or just ‘%!’.

4.8 Your Page Labels

In the PostScript file is dropped information on where sheets begin and end, so that post processing tools know where is the physical page 1, 2 etc. With this information can be also stored a label, i.e., a human readable text (typically the logical page numbers), which is for instance what Ghostview shows as the list of page numbers.

a2ps

Configuration Setting: PageLabelFormat: format

Specify the format to use to label the PostScript pages. format can use Escapes (see section Escapes). Two variables are predefined for this: ‘#{pl.short}’ and ‘#{pl.long}’.

4.9 Your Variables

There are many places in a2psof extending things. It once became clear that variables where needed in a2ps@c.

4.9.1 Defining Variables

Configuration Setting: Variable: key value

Define the escape ‘#{key}’ to be a short cut for value. key must not have any character from ‘:(){}’.

As as example, here is a variable for psnup, which encloses all the option passing one would like. Delegations are then easier to write:

Variable: psnup psnup -#v -q #?j|-d|| #?r||-c| -w#w -h#h

It is strongly suggested to follow a ‘.’ (dot) separated hierarchy, starting with:

‘del’

for variables that are related to delegations.

‘pro’

for variables used in prologues (see section Designing PostScript Prologues). Please, specify the name of the prologue (e.g., ‘pro.matrix.gray’).

‘ps’

for variables related to PostScript matters, such as the page label (which is associated to ps.page_label), the header etc.

‘pl’

for page label formats. See section 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 section 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 a2psat startup changes nothing to their status: they can be modified like any other variable using --define (see section Global Options).

In what follows, there are numbers (i) like this, or (ii) this. It means that a2ps(non empty value), this is the value given to the variable. Otherwise it tries solution (ii), etc. The rationale behind the order is usually from user modifiable values (e.g. environment variables) through system’s hard coded values (e.g., calls to getpwuid) and finally arbitrary values.

‘user.comments’

Comments on the user. Computed by (i) the system’s database (the part of pw_gecos after the first ‘,’), (ii) not defined.

‘user.home’

The user’s home directory. Determined by (i) the environment variable HOME, (ii) the system’s database (using getpwuid), (iii) the empty string.

‘user.host’

The user’s host name. Assigned from (i) the system (gethostname or uname), (ii) the empty string.

‘user.login’

The user’s login (e.g. ‘bgates’). Computed by (i) the environment variable LOGNAME, (ii) the environment variable USERNAME, (iii) the system’s database (using getpwuid), (iv) the translated string ‘user’.

‘user.name’

The user’s name (e.g. ‘William Gates’). Computed by (i) the system’s database (pw_gecos up to the first ‘,’), (ii) capitalized value of the variable ‘user.login’ unless it was the translated string ‘user’, (iii) the translated string ‘Unknown User’.

4.10 Your Delegations

There are some files you don’t really want a2pstypically page description files (e.g., PostScript files, roff files, etc.). You can let a2psapplications. The behavior at run time depends upon the option ‘--delegate’ (see section Input Options).

4.10.1 Defining a Delegation

Configuration Setting: Delegation: name in:out command

Define the delegation name. It is to be applied upon files of type in when output type is out(2) thanks to command. Both in and out are a2psdefined in ‘sheets.map’ (see section The Entry in ‘sheets.map’).

command should produce the file on its standard output. Of course escapes substitution is performed on command (see section 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(3). As a thumb rule, you should check that the PostScript generating applications produce files that start by:

%!PS-Adobe-3.0

a2psin 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, a2psis landscape by looking for the keyword ‘landscape’ in it, using strings(1):

Delegation: dvips dvi:ps\ if strings $f | sed 3q | fgrep landscape > /dev/null 2>&1; then \ #{d.dvips} -T#hpt,#wpt $f -o #f0 && #?o|cat|#{d.psnup} -r| #f0;\ else \ #{d.dvips} $f -o #f0 && #{d.psnup} #f0; \ fi

In order to have that rule work correctly, it is expected from the TeX, or LaTeX file to include something like:

\renewcommand{\printlandscape}{\special{landscape}} \printlandscape

in the preamble.

We don’t use a pipe because dvips always outputs data (its prologue) even if it fails, what prevents error detection.

Delegation: LaTeX (LaTeX to DVI)

We use a modern version of the shell script texi2dvi, from the package Texinfo, which runs makeindex, bibtex and latex as many times as needed. You should be aware that if the file includes files from other directories, it may miss some compilation steps. Other cases (most typical) are well handled.

4.11 Your Internal Details

There are settings that only meant for a2psyourself.

Configuration Setting: FileCommand: command

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

5. Library Files

To be general and to allow as much customization as possible, a2psavoids to hard code its knowledge (encodings, PostScript routines, etc.), and tries to split it in various files. Hence it needs a path, i.e., a list of directories, in which it may find the files it needs.

The exact value of this library path is available by ‘a2ps --list=defaults’. Typically its value is:

gargantua ~ $ a2ps --list=defaults
Configuration status of a2ps 4.13
More stuff deleted here
Internals:
  verbosity level     = 2
  file command        = /usr/ucb/file -L
  temporary directory =
  library path        =
        /inf/soft/infthes/demaille/.a2ps
        /usr/local/share/a2ps/sheets
        /usr/local/share/a2ps/ps
        /usr/local/share/a2ps/encoding
        /usr/local/share/a2ps/afm
        /usr/local/share/a2ps/printers
        /usr/local/share/a2ps

You may change this default path through the configuration files (see section Your Library Path).

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

5.1 Documentation Format

In various places a documentation can be given. Since some parts of this document and of web pages are extracted from documentations, some tags are needed to provide a better layout. The format is a mixture made out of Texinfo like commands, but built so that quick and easy processing can be made.

These tags are:

‘code(’text‘)code’

Typeset text like a piece of code. This should be used for keys, variables, options etc. For instance the documentation of the bold prologue mentions the bw prologue:

Documentation This style is meant to replace the old option code(-b)code of a2ps 4.3. It is a copy of the black and white prologue, but in which all the fonts are in Bold. EndDocumentation

‘href(’link‘)href(’text‘)href’

Specifies a hyper text link displayed as text.

‘@example’

‘@end example’

They must be alone on the line. The text between these tags is displayed in a code-like fonts. This should be used for including a piece of code. For instance, in the documentation of the gnuc style sheet:

documentation is "Declaration of functions are highlighted" "emph(only)emph if you start the function name" "in the first column, and it is followed by an" "opening parenthesis. In other words, if you" "write" "@example" "int main (void)" "@end example" "it won't work. Write:" "@example" "int" "main (void)" "@end example" end documentation

‘@itemize’

‘@item’ text

‘@end itemize’

Typeset a list of items. The opening and closing tags must be alone on the line.

5.2 Map Files

Many things are defined through files. There is a general scheme to associate an object to the files to use: map files. They are typically used to:

• - resolve aliases. For instance the ISO-8859-1 encoding is also called ISO Latin 1, or Latin 1 for short. The ‘encoding.map’ file will map these three names to the same Encoding Description File.
• - cope with broken files systems. For instance, the-one-you-know-I-don’t-need-to-name cannot handle files named ‘Courier-BoldOblique.afm’: it is the same as ‘Courier-Bold.afm’. The ‘fonts.map’ file is here to associate a font file name to a font name.

The syntax of these files is:

• - any empty line, or any line starting by a ‘#’ is a comment.
• - a line with the format

  *** path

  requests that the file designated by path be included at this point.

• - any other line has the format

  key value

  meaning that when looking for key (e.g., name of a font, an encoding etc.), a2psencoding description file name etc.).

The map files used in a2ps

‘encoding.map’

Resolving encodings aliases.

‘fonts.map’

Mapping font names to font file names.

‘sheets.map’

Rules to decide what style sheet to use.

5.3 Font Files

Even when a PostScript printer knows the fonts you want to use, using these fonts requires some description files.

5.3.1 Fonts Map File

See section 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

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

a2psname of the files in which are stored the fonts (see section 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 a2psdirectories. 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‘/usr/local/share/a2ps/afm/make_fonts_map.sh’.

This script asks a2pscollecting 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 the library path (for instance in your ‘~/.a2ps/’ directory).

5.4 Style Sheet Files

The style sheets are defined in various files. See see section Pretty Printing for the structure of these files. As for most other features, there is main file, a road map, which defines in which condition a style sheet should be used (see section Map Files). This file is ‘sheets.map’.

Its format is simple:

style-key: patterns

or

include(file)

The patterns need not be on separate lines. There are two kinds of patterns:

/pattern/flags

if the current file name matches pattern, then select style style-key (i.e. file ‘style-key.ssh’).

<pattern>flags

if the result of a call to file(1) matches pattern, then select style style-key.

Currently flags can only be ‘i’, standing for an insentive match. Please note that the matching is not truly case insensitive: rather, a lower case version of the string is compared to the pattern as is, i.e., the pattern should itself be lower case.

The special style-key ‘binary’ tells a2psthe file should not be printed, and will be ignored, unless option ‘--print-anyway’ is given.

If a style name can’t be found, the plain style is used.

The map file is read bottom up, so that the “last” match is honored.

Two things are to retain from this:

1. if the file is presented through stdin, then a2psfile(1). However, unless you specify a fake file name with ‘--stdin’, pattern matching upon the name is turn off. In general you can expect correct delegations, but almost never pretty printing.
2. if file is wrong on some files, a2psIn this case, do try option ‘--guess’, compare it with the output of file, and if the culprit is file, go and complain to your system administrator :-), or fix it by defining your own filename pattern matching rules.

Consider the case of Texinfo files as an example (the language in which this documentation is written). Files are usually named ‘foo.texi’, ‘bar.txi’, or even ‘baz.texinfo’. file(1) is able to recognize Texinfo files:

doc % file a2ps.texi
a2ps.texi: Texinfo source text

Therefore the sheets.map would look like:

# Texinfo files
texinfo:  /*.txi/  /*.texi/  /*.texinfo/
          <Texinfo source*>

6. Encodings

a2psuse. This chapter presents what an encoding is, how the encodings support is handled within a2ps@c, and some encodings it supports.

6.1 What is an Encoding

This section is actually taken from the web pages of Alis Technologies inc.

Document encoding is the most important but also the most sensitive and explosive topic in Internet internationalization. It is an essential factor since most of the information distributed over the Internet is in text format. But the history of the Internet is such that the predominant - and in some cases the only possible - encoding is the very limited ASCII, which can represent only a handful of languages, only three of which are used to any great extent: English, Indonesian and Swahili.

All the other languages, spoken by more than 90% of the world’s population, must fall back on other character sets. And there is a plethora of them, created over the years to satisfy writing constraints and constantly changing technological limitations. The ISO international character set registry contains only a small fraction; IBM’s character registry is over three centimeters thick; Microsoft and Apple each have a bunch of their own, as do other software manufacturers and editors.

The problem is not that there are too few but rather too many choices, at least whenever Internet standards allow them. And the surplus is a real problem; if every Arabic user made his own choice among the three dozen or so codes available for this language, there is little likelihood that his "neighbor" would do the same and that they would thus be able to understand each other. This example is rather extreme, but it does illustrate the importance of standards in the area of internationalization. For a group of users sharing the same language to be able to communicate,

1. the code used in the shared document must always be identified (labeling)
2. they must agree on a small number of codes - only one, if possible (standards);
3. their software must recognize and process all codes (versatility)

Certain character sets stand out either because of their status as an official national or international standard, or simply because of their widespread use.

First off, there is the ISO 8859 standards series that standardize a dozen character sets that are useful for a large number of languages using the Latin, Cyrillic, Arabic, Greek and Hebrew alphabets. These standards have a limited range of application (8 bits per character, a maximum of 190 characters, no combining) but where they suffice (as they do for 10 of the 20 most widely used languages), they should be used on the Internet in preference to other codes. For all other languages, national standards should preferably be chosen or, if none are available, a well-known and widely-used code should be the second choice.

Even when we limit ourselves to the most widely used standards, the overabundance remains considerable, and this significantly complicates life for truly international software developers and users of several languages, especially when such languages can only be represented by a single code. It was to resolve this problem that both Unicode and the ISO 10646 International standard were created. Two standards? Oh no! Their designers soon realized the problem and were able to cooperate to the extent of making the character set repertoires and coding identical.

ISO 10646 (and Unicode) contain over 30,000 characters capable of representing most of the living languages within a single code. All of these characters, except for the Han (Chinese characters also used in Japanese and Korean), have a name. And there is still room to encode the missing languages as soon as enough of the necessary research is done. Unicode can be used to represent several languages, using different alphabets, within the same electronic document.

6.2 Encoding Files

The support of the encodings in a2psto say, adding, removing or changing anything in its support for an encoding does not require programming, nor even being a programmer.

See section What is an Encoding, if you want to know more about this.

6.2.1 Encoding Map File

See section 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

• - 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 section 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, a2psspecify 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 section What is an Encoding, is an instructive presentation of the encodings.

The known encodings are:

Encoding: ASCII (‘ascii.edf’)

US-ASCII.

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.

Very few fonts yet offer the possibility to print the Euro sign.

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: 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. Pretty Printing

The main feature of a2psTwo different levels of pretty printing can be reached:

• - basic (normal highlight level) in which what you print is what you wrote.
• - string (heavy highlight level), in which in general, some keywords are replaced by a Symbol character which best represents them. For instance, in most languages ‘<=’ and ‘>=’ will be replaced by the corresponding single character from the font Symbol.

Note that the difference is up to the author of the style sheet.

7.1 Syntactic limits

a2pshandles lexical structures, i.e., if in your favorite language

IF IF == THEN THEN THEN := ELSE ELSE ELSE := IF

is legal, then a2psjust looks for some keywords, or some sequences.

7.2 Known Style Sheets

Style Sheet: 68000 (‘68000.ssh’)

Althought designed at the origin for the 68k’s assembler, this style sheet seems to handle rather well other dialects.

Style Sheet: a2ps configuration file (‘a2psrc.ssh’)

Meant to print files such as ‘a2ps.cfg’, or ‘.a2ps/a2psrc’, etc.

Style Sheet: a2ps style sheet (‘ssh.ssh’)

Second level of highligthing (option ‘-g’)) substitutes the LaTeX symbols.

Style Sheet: Ada (‘ada.ssh’)

This style sheets cover Ada 95. If you feel the need for Ada 83, you’ll have to design another style sheet.

Style Sheet: ASN.1 (‘asn1.ssh’)

Written by Philippe Coucaud. ASN.1 (Abstract Syntax Notation One) is used to define the protocol data units (PDUs) of all application layer protocols to date.

Style Sheet: Autoconf (‘autoconf.ssh’)

Suitable for both configure.in and library m4 files.

Style Sheet: AWK (‘awk.ssh’)

Written by Edward Arthur. This style is devoted to the AWK pattern scanning and processing language. It is supposed to support classic awk, nawk and gawk.

Style Sheet: B (‘b.ssh’)

Written by Philippe Coucaud. B is a formal specification method mostly used to describe critical systems. It is based on the mathematical sets theory.

Style Sheet: BC (‘bc.ssh’)

bc is an arbitrary precision calculator language.

Style Sheet: Bourne Shell (‘sh.ssh’)

Some classical program names, or builtin, are highlighted in the second level of pretty-printing.

Style Sheet: C (‘c.ssh’)

This style does not highlight the function definitions. Another style which highlights them, GNUish C, is provided (gnuc.ssh). It works only if you respect some syntactic conventions.

Style Sheet: C Shell (‘csh.ssh’)

Written by Jim Diamond. Some classical program names, and/or builtins, are highlighted in the second level of pretty-printing.

Style Sheet: C++ (‘cxx.ssh’)

Should handle all known variations of C++. Most declarations (classes etc.) are not highlighted as they should be. Please, step forward!

Style Sheet: CAML (‘caml.ssh’)

This style is obsolete: use OCaml instead.

Style Sheet: ChangeLog (‘chlog.ssh’)

This style covers the usual ChangeLog files.

Style Sheet: Claire (‘claire.ssh’)

Claire is a high-level functional and object-oriented language with advanced rule processing capabilities. It is intended to allow the programmer to express complex algorithms with fewer lines and in an elegant and readable manner.

To provide a high degree of expressivity, Claire uses:

• - A very rich type system including type intervals and second-order types (with dual static/dynamic typing),
• - Parametric classes and methods,
• - An object-oriented logic with set extensions,
• - Dynamic versioning that supports easy exploration of search spaces.

To achieve its goal of readability, Claire uses

• - set-based programming with an intuitive syntax,
• - simple-minded object-oriented programming,
• - truly polymorphic and parametric functional programming,
• - a powerful-yet-readable extension of DATALOG to express logical conditions,
• - an entity-relation approach with explicit relations, inverses, unknown values and relational
• - operations.

More information on claire can be found on claire home page.

Style Sheet: Common Lisp (‘clisp.ssh’)

Written by Juliusz Chroboczek. It is not very clear what should be considered as a ‘keyword’ in Common Lisp. I like binders, control structures and declarations to be highlighted, but not assignments.

Names of defstructs are not highlighted because this would not work with defstruct options.

Style Sheet: Coq Vernacular (‘coqv.ssh’)

This style is devoted to the Coq v 5.10 vernacular language.

Style Sheet: CORBA IDL (‘cidl.ssh’)

Written by Bob Phillips. A first attempt at a style sheet for OMG CORBA IDL. I believe I captured all the keywords for CORBA 2.2 IDL. I also stole code from gnuc.ssh to print the method names in bold face. I’m not sure I quite like my own choices for Keyword_strong and Keyword, so I’m looking for feedback. Note that, as with gnuc.ssh, for a method name to be noted as such, the left parenthesis associated with the argument list for the method must appear on the same line as the method name.

Style Sheet: CPP (‘cpp.ssh’)

C traditional preprocessor handling, mostly meant to be inherited.

Style Sheet: dc_shell (‘dc_shell.ssh’)

Written by Philippe Le Van. Synopsys Design Compiler is a synthesis tool used by electronic companies for the design of their chips. This sheet is very incomplete, we have a lot of keywords to add, eventually options to highlight... The Label_strong style is used for commands which change the design.

Style Sheet: Eiffel (‘eiffel.ssh’)

Eiffel is an object oriented language that also includes a comprehensive approach to software construction: a method.

The language itself is not just a programming language but also covers analysis, design and implementation.

Heavy highlight uses symbols to represent common math operators.

Style Sheet: Emacs Lisp (‘elisp.ssh’)

Written by Didier Verna. This style sheet includes support for some extensions dumped with XEmacs.

Style Sheet: Encapsulated PostScript (‘eps.ssh’)

Illegal PostScript operators are highlighted as Errors.

Style Sheet: Extended Tcl (‘tclx.ssh’)

Written by Phil Hollenback. Extensions to plain Tcl.

Style Sheet: Fortran (‘fortran.ssh’)

Written by Denis Girou, Alexander Mai. There are several Fortran dialects, depending whether, on the one hand, you use Fortran 77 or Fortran 90/95, and, on the other hand, Fixed form comments, or Free form comments.

The style sheets for77kwds and for90kwds implements keywords only, while the style sheets for-fixed and for-free implements comments only.

This style sheet tries to support any of the various flavors (Fortran 77/90/95, fixed or free form). For more specific uses, you should use either:

• - for77-fixed, for Fortran 77 fixed form,
• - for77-free, for Fortran 77 free form,
• - for90-fixed, for Fortran 90/95 fixed form,
• - for90-free, for Fortran 90/95 free form.

Style Sheet: Fortran 77 Fixed (‘for77-fixed.ssh’)

Written by Denis Girou, Alexander Mai. Dedicated to Fortran 77 in fixed form, i.e., comments are lines starting with c, C, or *, and only those lines are comments.

Style Sheet: Fortran 77 Free (‘for77-free.ssh’)

Written by Denis Girou, Alexander Mai. Dedicated to Fortran 77 in free form, i.e., comments are introduced by ! anywhere on the line, and nothing else is a comment.

Style Sheet: Fortran 77 Keywords (‘for77kwds.ssh’)

Written by Denis Girou, Alexander Mai. This sheet implements only Fortran 77 keywords, and avoids implementing comments support. This is to allow for implementation of either fixed or free source form.

See the documentation of the style sheet fortran for more details.

Style Sheet: Fortran 90 Fixed (‘for90-fixed.ssh’)

Written by Denis Girou, Alexander Mai. Dedicated to Fortran 90/95 in fixed form, i.e., comments are lines starting with c, C, or *, and only those lines are comments.

Style Sheet: Fortran 90 Free (‘for90-free.ssh’)

Written by Denis Girou, Alexander Mai. Dedicated to Fortran 90/95 in free form, i.e., comments are introduced by ! anywhere on the line, and nothing else is a comment.

Style Sheet: Fortran 90 Keywords (‘for90kwds.ssh’)

Written by Denis Girou, Alexander Mai. This sheet implements the superset which Fortran 90 and Fortran 95 provide over Fortran 77.

See the documentation of the style sheet fortran for more details.

Style Sheet: Fortran Fixed (‘for-fixed.ssh’)

Written by Denis Girou, Alexander Mai. Implements comments of Fortran in fixed form, i.e., comments are lines starting with c, C, or *, and only those lines are comments. No other highlighting is done.

See the documentation of the style sheet fortran for more details.

Style Sheet: Fortran Free (‘for-free.ssh’)

Written by Denis Girou, Alexander Mai. Dedicated to Fortran in free form, i.e., comments are introduced by ! anywhere on the line, and nothing else is a comment.

Style Sheet: GNUish C (‘gnuc.ssh’)

Declaration of functions are highlighted only if you start the function name in the first column, and it is followed by an opening parenthesis. In other words, if you write

int main (void)

it won’t work. Write:

int main (void)

Style Sheet: GNUMakefile (‘gmake.ssh’)

Written by Alexander Mai. Special tokens of GNUmakefiles and non terminal declarations are highlighted.

Style Sheet: Haskell (‘haskell.ssh’)

Written by Ilya Beylin. Haskell: non-strict functional programming language http::/www.haskell.org/

Style Sheet: HTML (‘html.ssh’)

Written by Wesley J. Chun. This style is meant to pretty print HTML source files, not to simulate its interpretation (i.e., ‘<bold>foo</bold>’ does not print ‘foo’ in bold). If you really meant to print the result of the HTML file interpreted, then you should turn the delegations on, and make sure ‘a2ps’ has HTML delegations.

Style Sheet: IDL (‘idl.ssh’)

Written by Robert S. Mallozzi, Manfred Schwarb. Style sheet for IDL 5.2 (Interactive Data Language). Obsolete routines are not supported. http://www.rsinc.com.

Style Sheet: InstallShield 5 (‘is5rul.ssh’)

Written by Alex. InstallShield5 _TM_ RUL script.

Style Sheet: Java (‘java.ssh’)

Written by Steve Alexander. Documentation comments are mapped to strong comments, and any other comment is plain comment.

Style Sheet: JavaScript (‘js.ssh’)

Written by Scott Pakin. Keywords used are everything listed in the Client-Side JavaScript Reference 1.3, plus "undefined" (why isn’t that listed?) and "prototype". I omitted the semi-standard a2ps optional operators for equality, because JavaScript’s use of both strict- and non-strict equality might ambiguate the output. Finally, regular expressions are formatted like strings.

Style Sheet: LACE (‘lace.ssh’)

This is meant for the Eiffel equivalent of the Makefiles.

Style Sheet: Lex (‘lex.ssh’)

In addition to the C constructs, it highlights the declaration of states, and some special ‘%’ commands.

Style Sheet: Lout (‘lout.ssh’)

Written by Jean-Baptiste Nivoit. This is the style for Lout files.

Style Sheet: Mail Folder (‘mail.ssh’)

To use from elm and others, it is better to specify ‘-g -Email’, since the file sent to printer is no longer truly a mail folder. This style also suits to news. ‘--strip’ options are also useful (they strip "useless" headers).

Whenever the changes of encoding are clear, a2ps sets itself the encoding for the parts concerned.

Tag 1 is the subject, and Tag 2 the author of the mail/news.

Note: This style sheet is _very_ difficult to write. Please don’t report behavior you don’t like. Just send me improvements, or write a Bison parser for mails.

Style Sheet: Makefile (‘make.ssh’)

Special tokens, and non terminal declarations are highlighted.

Style Sheet: Management Information Base (‘mib.ssh’)

Written by Kelly Wiles. The MIB file is of ASN.1 syntax.

Style Sheet: Maple (‘maple.ssh’)

Written by Richard J Mathar. Some classical program names, and/or builtins, are highlighted in the second level of pretty-printing.

Style Sheet: MATLAB 4 (‘matlab4.ssh’)

Written by Marco De la Cruz. Note that comments in the code should have a space after the %.

Style Sheet: Modula 2 (‘modula2.ssh’)

Written by Peter Bartke.

Style Sheet: Modula 3 (‘modula3.ssh’)

Modula-3 is a member of the Pascal family of languages. Designed in the late 1980s at Digital Equipment Corporation and Olivetti, Modula-3 corrects many of the deficiencies of Pascal and Modula-2 for practical software engineering. In particular, Modula-3 keeps the simplicity of type safety of the earlier languages, while providing new facilities for exception handling, concurrency, object-oriented programming, and automatic garbage collection. Modula-3 is both a practical implementation language for large software projects and an excellent teaching language.

This sheet was designed based on Modula 3 home page.

Style Sheet: o2c (‘o2c.ssh’)

Style Sheet: Oberon (‘oberon.ssh’)

Created by N. Wirth, Oberon is the successor of the Pascal and Modula-2 family of programming languages. It was specifically designed for systems programming, and was used to create the Oberon system in cooperation with J. Gutknecht. A few years later, the Oberon language was extended with additional object-oriented features to result in the programming language Oberon-2.

Implementation of the sheet based on The Oberon Reference Site.

Style Sheet: Objective C (‘objc.ssh’)

Written by Paul Shum.

Style Sheet: OCaml (‘ocaml.ssh’)

Written by Markus Mott. This style should also suit other versions of ML (caml light, SML etc.).

Style Sheet: OCaml Yacc (‘mly.ssh’)

Written by Jean-Baptiste Nivoit. Should handle CAML Special Light parser files.

Style Sheet: Octave (‘octave.ssh’)

Written by C.P. Earls.

Style Sheet: Oracle parameter file (‘initora.ssh’)

Written by Pierre Mareschal. For init.ora parameter files.

Style Sheet: Oracle PL/SQL (‘plsql.ssh’)

Written by Pierre Mareschal. This style is to be checked.

Style Sheet: Oracle SQL (‘sql.ssh’)

Written by Pierre Mareschal. a2ps-sql Pretty Printer Version 1.0.0 beta - 18-MAR-97 For comments, support for – /*..*/ and //. This style is to be checked.

Style Sheet: Oracle SQL-PL/SQL-SQL*Plus (‘oracle.ssh’)

Written by Pierre Mareschal. 18-MAR-97 For comments, support for – /*..*/ and //. This style is to be checked.

Style Sheet: Pascal (‘pascal.ssh’)

The standard Pascal is covered by this style. But some extension have been added too, hence modern Pascal programs should be correctly handled. Heavy highlighting maps mathematical symbols to their typographic equivalents.

Style Sheet: Perl (‘perl.ssh’)

Written by Denis Girou. As most interpreted languages, Perl is very free on its syntax, what leads to significant problems for a pretty printer. Please, be kind with our try. Any improvement is most welcome.

Style Sheet: PostScript (‘ps.ssh’)

Only some keywords are highlighted, because otherwise listings are quickly becoming a big bold spot.

Style Sheet: PostScript Printer Description (‘ppd.ssh’)

Support for Adobe’s PPD files.

Style Sheet: Pov-Ray (‘pov.ssh’)

Written by Jean-Baptiste Nivoit. Should handle Persistence Of Vision input files.

Style Sheet: PreScript (‘pre.ssh’)

This style defines commands in the canonic syntax of a2ps. It is meant to be used either as an input language, and to highlight the table of contents etc.

It can be a good choice of destination language for people who want to produce text to print (e.g. pretty-printing, automated documentation etc.) but who definitely do not want to learn PostScript, nor to require the use of LaTeX.

Style Sheet: PreTeX (‘pretex.ssh’)

This style sheets provides LaTeX-like commands to format text. It is an alternative to the PreScript style sheet, in which formating commands are specified in a more a2ps related syntax.

It provides by the use of LaTeX like commands, a way to describe the pages that this program should produce.

Style Sheet: Prolog (‘prolog.ssh’)

Help is needed on this sheet.

Style Sheet: Promela (‘promela.ssh’)

There is no way for this program to highlight send and receive primitives.

Style Sheet: Python (‘python.ssh’)

Python is an easy to learn, powerful programming language. It has efficient high-level data structures and a simple but effective approach to object-oriented programming. Python’s elegant syntax and dynamic typing, together with its interpreted nature, make it an ideal language for scripting and rapid application development in many areas on most platforms.

The Python interpreter and the extensive standard library are freely available in source or binary form for all major platforms from the Python web site, and can be freely distributed.

The same site also contains distributions of and pointers to many free third party Python modules, programs and tools, and additional documentation.

The Python interpreter is easily extended with new functions and data types implemented in C or C++ (or other languages callable from C). Python is also suitable as an extension language for customizable applications.

Style Sheet: Reference Card (‘card.ssh’)

This style sheet is meant to process help messages generated by Unix applications. It highlights the options (-short or –long), and their arguments. Normal use of this style sheet is through the shell script card (part of the a2ps package), but a typical hand-driven use is:

program --help | a2ps -Ecard

Style Sheet: REXX (‘rexx.ssh’)

Written by Alexander Mai. This style sheet supports REXX. You can get information about REXX from the REXX Language Association.

Style Sheet: Sather (‘sather.ssh’)

Sather is an object oriented language designed to be simple, efficient, safe, flexible and non-proprietary. One way of placing it in the ‘space of languages’ is to say that it aims to be as efficient as C, C++, or Fortran, as elegant as and safer than Eiffel, and support higher-order functions and iteration abstraction as well as Common Lisp, CLU or Scheme.

Implementation of the sheet based on the Sather home page.

Heavy highlighting uses symbols for common mathematical operators.

Style Sheet: Scheme (‘scheme.ssh’)

This style sheet is looking for a maintainer and/or comments.

Style Sheet: SDL-88 (‘sdl88.ssh’)

Written by Jean-Philippe Cottin. –strip-level=2 is very useful: it cancels the graphical information left by graphic editors. Only the pure specification is then printed.

Style Sheet: Sed (‘sed.ssh’)

Comments and labels are highlighted. Other ideas are welcome! A lot of work is still needed.

Style Sheet: Shell (‘shell.ssh’)

This style sheet is not meant to be used directly, but rather an as ancestor for shell style sheets.

Style Sheet: SQL 92 (‘sql92.ssh’)

Written by Pierre Mareschal. 18-MAR-97 This style is to be checked.

Style Sheet: Standard ML (‘sml.ssh’)

Written by Franklin Chen, Daniel Wang. This style sheet takes advantage of the Symbol font to replace many ASCII operators with their natural graphical representation. This is enabled only at heavy highlighting.

Style Sheet: Symbols (‘symbols.ssh’)

This style sheet should be a precursor for any style sheet which uses LaTeX like symbols.

Style Sheet: TC Shell (‘tcsh.ssh’)

Written by Jim Diamond. C shell with file name completion and command line editing.

Style Sheet: TeX (‘tex.ssh’)

Written by Denis Girou. This is the style for (La)TeX files. It’s mainly useful for people who develop (La)TeX packages. With ‘-g’, common mathematical symbols are represented graphically.

Style Sheet: Texinfo (‘texinfo.ssh’)

Heavy highlighting prints the nodes on separate pages which title is the name of the node.

Style Sheet: TeXScript (‘texscript.ssh’)

TeXScript is the new name of what used to be called PreScript. New PreScript has pure a2ps names, PreTeX has pure TeX names, and TeXScript mixes both.

Style Sheet: Tiger (‘tiger.ssh’)

Tiger is a toy language that serves as example of the book Modern Compiler Implementation by Andrew W. Appel.

Style Sheet: tk (‘tk.ssh’)

Written by Larry W. Virden. Since everything, or almost, is a string, what is printed is not always what you would like.

Style Sheet: Tool Command Language (‘tcl.ssh’)

Written by Larry W. Virden. Since everything, or almost, is a string, what is printed is not always what you would like.

Style Sheet: Unified Diff (‘udiff.ssh’)

This style is meant to be used onto the output unidiffs, that is to say output from ‘diff -u’.

Typical use of this style is:

diff -u old new | a2ps -Eudiff

The prologue diff helps to highlight the differences (‘a2ps -Ewdiff --prologue=diff’).

Style Sheet: Unity (‘unity.ssh’)

Written by Jean-Philippe Cottin. The graphic conversion of the symbols (option ‘-g’) is nice.

Style Sheet: VERILOG (‘verilog.ssh’)

Written by Edward Arthur. This style is devoted to the VERILOG hardware description language.

Style Sheet: VHDL (‘vhdl.ssh’)

Written by Thomas Parmelan. Non-textual operators are not highlighted. Some logical operators are printed as graphical symbols in the second level of pretty-printing.

Style Sheet: Visual Basic for Applications (‘vba.ssh’)

Written by Dirk Eddelbuettel.

Style Sheet: Visual Tcl (‘vtcl.ssh’)

Written by Phil Hollenback. All the Vtcl keywords that aren’t in Tcl or TclX.

Style Sheet: VRML (‘vrml.ssh’)

Written by Nadine Richard. According to Grammar Definition Version 2.0 ISO/IEC CD 14772.

Style Sheet: wdiff (‘wdiff.ssh’)

This style is meant to be used onto the output of Franc,ois Pinard’s program wdiff. wdiff is a utility that underlines the differences of words between to files. Where diff make only the difference between lines that have changed, wdiff reports words that have changed inside the lines.

Typical use of this style is:

wdiff old new | a2ps -Ewdiff

wdiff can be found in usual GNU repositories. The prologue diff helps to highlight the differences (‘a2ps -Ewdiff --prologue=diff’).

Style Sheet: XS (‘xs.ssh’)

Written by Kestutis Kupciunas. This style covers Perl XS language.

Style Sheet: Yacc (‘yacc.ssh’)

Special tokens, and non terminal declarations are highlighted.

Style Sheet: Z Shell (‘zsh.ssh’)

Zsh is a UNIX command interpreter (shell) usable as an interactive login shell and as a shell script command processor. Of the standard shells, zsh most closely resembles ksh but includes many enhancements. Zsh has comand line editing, builtin spelling correction, programmable command completion, shell functions (with autoloading), a history mechanism, and a host of other features.

This style sheet highlights some classical program names and builtins in the second level of pretty-printing.

7.3 Type Setting Style Sheets

This section presents a few style sheets that define page description languages (compared to most other style sheet meant to pretty print source files).

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@c. Since bold sequences, special characters etc. were implemented in a2ps@c, we thought it would be good to allow direct access to those features: PreScript became an input language for a2ps@c, where special font treatments are specified in an ssh syntax (see section Style Sheets Implementation).

The main advantages for using PreScript are:

• - it is fairly simple,
• - a2psevery UNIX platform.

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

7.3.2.1 Syntax

Every command name begins with a backslash (‘\’). If the command uses an argument, it is given between curly braces with no spaces between the command name and the argument.

The main limit on PreScript is that no command can be used inside another command. For instance the following line will be badly interpreted by a2ps@c:

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

The correct way to write this in PreScript is

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

Everything from an unquoted % to the end of line is ignored (comments).

7.3.2.2 PreScript Commands

These commands required arguments.

‘\keyword{text}’

‘\Keyword{text}’

Highlight lightly/strongly the given text. Should be used only for a couple of adjacent words.

‘\comment{text}’

‘\Comment{text}’

The text is given a special face. The text may be removed if option ‘--strip’ is used.

‘\label{text}’

‘\Label{text}’

text should be considered as a definition, or an important point in the structure of the whole text.

‘\string{text}’

Write text with string’s face (e.g., in font Times).

‘\error{text}’

Write text with error’s face (generally a very different face, so that you see immediately).

‘\symbol{text}’

text is written in the PostScript symbol font. This feature is not compatible with LaTeX. It is recommended, when possible, to use the special keywords denoting symbols, which are compatible with LaTeX (see section Symbol).

‘\header{text}’

‘\footer{text}’

Use text as header (footer) for the current page. If several headers or footers are defined on the same page, the last one is taken into account.

‘\encoding{key}’

Change dynamically the current encoding. After this command, the text is printed using the encoding corresponding to key.

7.3.2.3 Examples

PreScript and a2psformating. For instance, on the ‘passwd’ file:

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.

7.3.3.1 Special characters

‘$’ is ignored in PreTeX for compatibility with LaTeX, and ‘%’ introduces a comment. Hence they are the only symbols which have to be quoted by a ‘\’. The following characters should also be quoted to produce good LaTeX files, but are accepted by PreScript: ‘_’, ‘&’, ‘#’.

Note that inside a command, like \textbf, the quotation mechanism does not work in PreScript (\textrm{#$%} writes ‘#$%’) though LaTeX still requires quotation. Hence whenever special characters or symbols are introduced, they should be at the outer most level.

7.3.3.2 PreTeX Commands

These commands required arguments.

‘\section{Title}’

‘\subsection{Title}’

‘\subsubsection{Title}.’

Used to specify the title of a section, subsection or subsubsection.

‘\textbf{text}’

‘\textit{text}’

‘\textbi{text}’

‘\textrm{text}’

write text in bold, italic, bold-italic, Times. Default font is Courier.

‘\textsy{text}’

text is written in the PostScript symbol font. This feature is not compatible with LaTeX. It is recommended, when possible, to use the special keywords denoting symbols, which are compatible with LaTeX (See the style sheet Symbol).

‘\header{text}’

‘\footer{text}’

Use text as header (footer) for the current page. If several headers or footers are defined on the same page, the last one is taken into account.

‘\verb+text+’

Quote text so that no special sequence will be interpreted. In ‘\verb+quoted string+’ ‘+’ can be any symbol in ‘+’, ‘!’, ‘|’, ‘#’, ‘=’.

‘\begin{document}’

‘\end{document}’

‘\begin{itemize}’

‘\end{itemize}’

‘\begin{enumerate}’

‘\end{enumerate}’

‘\begin{description}’

‘\end{description}’

These commands are legal in LaTeX but have no sense in PreTeX. Hence there are simply ignored and not printed (if immediately followed by an end-of-line).

7.3.3.3 Differences with LaTeX

The following symbols, inherited from the style sheet Symbol, are not supported by LaTeX:

‘\Alpha’, ‘\apple’, ‘\Beta’, ‘\carriagereturn’, ‘\Chi’, ‘\Epsilon’, ‘\Eta’, ‘\florin’, ‘\Iota’, ‘\Kappa’, ‘\Mu’, ‘\Nu’, ‘\Omicron’, ‘\omicron’, ‘\radicalex’, ‘\register’, ‘\Rho’, ‘\suchthat’, ‘\Tau’, ‘\therefore’, ‘\trademark’, ‘\varUpsilon’, ‘\Zeta’.

LaTeX is more demanding about special symbols. Most of them must be in so-called math mode, which means that the command must be inside ‘$’ signs. For instance, though

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

is perfectly legal in PreTeX, it should be written

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

for LaTeX. Since in PreTeX every ‘$’ is discarded (unless quoted by a ‘\’), the second form is also admitted.

7.3.4 TeXScript

TeXScript is a replacement of the old version of PreScript: it combines both the a2ps@c-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

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’. a2psHence, 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.4 Faces

A face is an attribute given to a piece of text, which specifies how it should look like. Since a2pssource files, the faces it uses are related to the syntactic entities that can be encountered in a file.

The faces a2ps

‘Plain’

This corresponds to the text body.

‘Keyword’

‘Keyword_strong’

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

‘Comment’

‘Comment_strong’

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’

‘Label_strong’

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

‘String’

Used mainly for string and character literals.

‘Error’

Used to underline the presence of an error. For instance in Encapsulated PostScript, some PostScript operators are forbidden: they are underlined as errors.

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

7.5 Style Sheets Semantics

a2psone per language. In the following is described how the style sheets are defined. You may skip this section if you don’t care how a2ps