     [file version.texi not included]

This document describes GNU a2ps VERSION, a converter from various formats, included text, to PostScript converter, with pretty-printing abilities.

Copyright © 1988-1993 Miguel Santana Copyright © 1995-2000 Akim Demaille, Miguel Santana Copyright © 2007- Akim Demaille, Miguel Santana and Masayuki Hatta

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled ``Copying'' is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the author.

a2ps
****

GNU a2ps is a filter which generates PostScript from various formats, with pretty-printing features, strong support for many alphabets, and customizable layout.

This is Edition VERSION of the a2ps documentation, updated UPDATED.

Introduction
************

This document describes GNU a2ps version VERSION.  The latest versions may be found on the a2ps home page (http://www.gnu.org/software/a2ps/). We plan to update the GNU
a2ps home page (http://www.gnu.org/software/a2ps/) in the near future, in which case the latter will be a better source of information.

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 a2ps is difficult to use.  See Glossary, for technical words or even general information.

Please, send us emailcards :). Whatever the comment is, or if you just like a2ps, write to Miguel Santana and Akim Demaille.  But never write to either of us for asking questions, or to report bugs.  Chances are very high never to receive an answer, as we receive too many messages.  See a2ps Mailing Lists, for information on the mailing lists.

Description
===========

a2ps formats files for printing on a PostScript printer.

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 a2ps is kind of bootstrapped: its sources are frequently printed 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, a2ps supports delegations, i.e., you can safely use a2ps to print DVI, PostScript, LaTeX, JPEG etc., even compressed.

A short list of features of a2ps might look like this:

  - Customizable through various configuration files (see Configuration Files)

  - Powerful escapes to define the headers, table of contents etc. the way you want (see Escapes);

  - Variables to push even further the customizability in a comfortable manner (see Your Variables);

  - Open approach of encodings (see Encodings);

  - Excellent support of the Latin 2, 3, 4, 5 and 6 encodings, thanks to Ogonkify (see Overview (Ogonkify manual)), written by Juliusz Chroboczek.

  - Fully customizable output style: fonts, background and foreground colors, line numbering style etc. (see Designing PostScript Prologues).

  - Possibility to delegate the processing of some files to other filters (see 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 Contributions).

  - And finally, the ability to pretty-print sources written in quite a few various languages (see Pretty Printing).

Reporting Bugs
==============

We try hard to make a2ps portable on any Unix platform, and bug free. But sometimes there can still be bad surprises, even after having compiled and checked a2ps on several very different platforms.

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 FAQ), then on the page Known
a2ps Bugs (http://www.gnu.org/software/a2ps//bugs.html) if the issue has not been addressed yet.  If it is not the case, but it appears that the version of a2ps you have is old, consider 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, 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.

a2ps Mailing Lists
==================

There are several mailing lists related to a2ps:

a2ps@gnu.org
     This list is dedicated to announcements, questions/answers, etc. The alpha versions are announced too.  Requests and suggestions can be sent there.

bug-a2ps@gnu.org
     Any bug report should be sent to this address.  Please, be sure to state the version of a2ps in the subject of your message, together with a short description of the problem.  In the body of the message, include all the information that might be relevant: the system you run, etc.

a2ps-patches@gnu.org
     Send patches, style sheets, new delegations etc. to this list.  In other words, any candidate for inclusion into a2ps should be sent to this list.  It also serves to coordinate the developers.  If you are interested in the development of a2ps, then visit the Savannah a2ps page (https://savannah.gnu.org/projects/a2ps/).

a2ps-commit@gnu.org
     Each time a change is made the main a2ps repository, a message is sent to this mailing list.  For developers only.

To subscribe to any of these list, go to their web pages: a2ps (http://mail.gnu.org/mailman/listinfo/a2ps), bug-a2ps (http://mail.gnu.org/mailman/listinfo/bug-a2ps), a2ps-patches (http://mail.gnu.org/mailman/listinfo/a2ps-patches), and a2ps-commit (http://mail.gnu.org/mailman/listinfo/a2ps-patches).

Be sure never to send a private message to one of the authors, as it is approximately the best means never to get an answer.  In addition it is counter productive for the community, as the answer to your question might have interested more people.

Helping the Development
=======================

If you like a2ps and if you feel like helping, there are several things you 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 a2ps is under GNU gettext which means that all the messages can be translated, without having to look at the code of a2ps: you don't need to be a programmer at all.  All the details are available on the a2ps translation page (http://www.gnu.org/software/a2ps//po/).

Style Sheets
     Since a2ps is evolving and getting more powerful, the style sheets should 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 Pretty Printing for details.)

Encodings
     a2ps is wide open to any 8-bit encoding.  If your language is not covered today by a2ps, you can easily provide the support yourself. Honestly, the trickiest part is to find correct free fonts that support your mother tongue (see Encoding Files, to know more).

Fonts
     There are still some characters missing in Ogonkify. See the list
     of missing characters (http://www.dcs.ed.ac.uk/home/jec/ogonkify/missing.html) and the Ogonkify home
     page (http://www.dcs.ed.ac.uk/home/jec/ogonkify/) 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.

User's Guide
************

This chapter is devoted to people who don't know a2ps yet: we try to give 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 FAQ.

Purpose
=======

a2ps is a program that takes a text file (i.e., human readable), and makes a PostScript file out of it.  Typically output is sent to a printer.

How to print
============

To print a file doc.txt, just give it to a2ps: 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

a2ps sent the file doc.txt to the default printer, writing two columns of text on a single face of the sheet.  Indeed, by default a2ps uses the option -2, standing for two virtual pages.

Basics for Printing
-------------------

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

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

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

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

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

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

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

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

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

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

Special Printers
----------------

There are three special printers pre-defined.

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

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

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

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

Using Delegations
-----------------

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

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

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

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

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

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

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

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

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

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

You should be aware that:

  - the option -Z enables the delegations if they are not (see --list=defaults for your settings);

  - the set of delegations is customizable, to know the delegations your a2ps knows, consult a2ps --list=delegations.

Printing Duplex
---------------

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

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

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

This is also valid for several files.

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

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

and voila` !, a booklet printed on margot!

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

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

Checking the Defaults
---------------------

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

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

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

     a2ps --help | more

Important parameters
====================

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

The paper
     Make sure that the paper a2ps uses is the same as your printer (see Sheet Options, option --medium).

The encoding
     Make sure that the encoding a2ps uses is the same as the standard alphabet in your country (see Input Options, option --encoding).

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

Localizing
==========

a2ps provides some Native Language Support, that is speaking your mother 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

Interfacing with Other Programs
===============================

Here are some tips on how to use a2ps with other programs.

Interfacing With a Mailer
-------------------------

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

Most specifically, if your mailer is:

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

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

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

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

Netscape
--------

This is actually valid for any program that generates PostScript that you want to post-process with a2ps.  Use the following command:

     a2ps

Not too hard, isn't it?

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

     a2ps -ZEps

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

Invoking a2ps
*************

Calling a2ps is fairly simple:

     a2ps OPTIONS... FILES...

If no FILES... are given, a2ps prints its standard input.  If - appears in the FILES..., it designates the standard input too.

Command line options
====================

To read the options and arguments that you give, a2ps uses GNU getopt, 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 (A classical Unix trick to make the difference between the option -2, and the file -2 is to type ./-2.).

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.

Tasks Options
-------------

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

 -- Option: --version
     print version and exit successfully.

 -- Option: --help
     Print a short help, and exit successfully.

 -- Option: --copyright
     Display Copyright and copying conditions, and exit successfully.

 -- Option: --guess
     Act like file does: display the (key of the) type of the FILES.

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

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

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

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

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

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

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

 -- Option: --list=TOPIC
     Display a report on a2ps' status with respect to TOPIC, and exit successfully. TOPIC can be any non-ambiguous abbreviation of:

     defaults
     options
          Give an extensive report on a2ps configuration and installation.

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

     delegations
          Detailed list of the delegations.  See Your Delegations.

     encodings
          Detailed list of known encodings.  See Some Encodings.

     media
          Detailed list of known media. See Your Media.

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

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

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

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

     variables
          Detailed list of the variables.  See Your Variables.

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

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

     html-style-sheets
     ssh-html
          Detailed list of the style sheets in HTML format.

     texinfo-encodings
     edf-texi
          Detailed list of encodings, in Texinfo format.

     texinfo-prologues
     pro-texi
          Detailed list of prologues, in Texinfo format.

Global Options
--------------

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

 -- Option: -q
 -- Option: --quiet
 -- Option: --silent
     be really quiet

 -- Option: -v[LEVEL]
 -- Option: --verbose[=LEVEL]
     tell what we are doing.  At

       - LEVEL = 0, report nothing,

       - LEVEL = 1, a2ps just prints the total number of pages printed,

       - LEVEL = 2 (default), it reports it for each file,

       - above, it gives internal details.

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

     configuration
     options
          reading the configurations files and the options,

     encodings
          the encodings,

     expert
          more detailed information is provided: PPD listings is exhaustive,

     files
          inputs and outputs,

     fonts
          the fonts,

     escapes
     variables
     meta-sequences
          the expansion of escapes and variables,

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

     pathwalk
     pw
          the search for files,

     ppd
          PPD processing,

     sheets
          the style sheets,

     stats
          statistics on some internal data structures,

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

     all
          all the messages.

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

 -- Option: -=SHORTCUT
 -- Option: --user-option=SHORTCUT
     use the SHORTCUT defined by the user. See Your Shortcuts. Shortcuts may be freely mixed with regular options and arguments.

     There are a few predefined user-options:

     lp
          emulates a line printer, i.e., turn off most `pretty' features.

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

     manual
          make the job be printed on the manually fed tray.

 -- Option: --debug
     enable debugging features.  They are:

       - print the overall BoundingBox in PostScript;

       - down load a PostScript debugger which helps understanding why a printer may reject a file.

 -- Option: -D KEY[=VALUE]
 -- Option: --define=KEY[=VALUE]
     Without VALUE, unset the variable KEY.  Otherwise, set it to VALUE. See Your Variables, for more details.  Note that -Dfoo= gives FOO an empty value, though -Dfoo unsets foo.

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 a2ps to ask the library libpaper for the medium to use.  This choice is valid only if libpaper was available when a2ps was configured. See 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.

Page Options
------------

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

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

 -- Option: --line-numbers[=NUMBER]
     print the line numbers from NUMBER lines to NUMBER lines. Default is 1.

 -- Option: -C
     Alias for --line-numbers=5.

 -- Option: -f SIZE[UNIT]
 -- Option: --font-size=SIZE[UNIT]
     scale font to SIZE for body text. SIZE is a float number, and UNIT can be cm for centimeters, points for PostScript points, and in for inches.  Default unit in points.

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

 -- Option: -l NUM
 -- Option: --chars-per-line=NUM
     Set the font size so that NUM columns appear per virtual pages. NUM is the real number of columns devoted to the body of the text, i.e., no matter whether lines are numbered or not.

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

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

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

 -- Option: -T NUM
 -- Option: --tabsize=NUM
     set tabulator size to NUM.  This option is ignored if --interpret=no is given.

 -- Option: --non-printable-format=FORMAT
     specify how non-printable chars are printed. FORMAT can be

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

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

     question-mark
          A ? is written instead of the non-printable character.

     octal
          For instance \001, 177 etc.

     hexa
          For instance \x01, \xfe etc.

     emacs
          For instance C-h, M-C-c etc.

Headings Options
----------------

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

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

 -- Option: -B
 -- Option: --no-header
     no page headers at all.

 -- Option: -b[TEXT]
 -- Option: --header[=TEXT]
     set the page header

 -- Option: --center-title[=TEXT]
 -- Option: --left-title[=TEXT]
 -- Option: --right-title[=TEXT]
     Set virtual page center, left and right titles to TEXT.

 -- Option: -u[TEXT]
 -- Option: --underlay[=TEXT]
     use TEXT as under lay (or water mark), i.e., in a light gray, and under every page.

 -- Option: --left-footer[=TEXT]
 -- Option: --footer[=TEXT]
 -- Option: --right-footer[=TEXT]
     Set sheet footers to TEXT.

Input Options
-------------

 -- Option: -a[PAGE RANGE]
 -- Option: --pages[=PAGE RANGE]
     With no argument, print all the page, otherwise select the pages to print.  PAGE RANGE is a list of interval, such as -a1: print only the first page, -a-3,4,6,10-: print the first 3 pages, page 4 and 6, and all the page after 10 (included).  Giving toc prints the table of content whatever its page number is.

     The pages referred to are the input pages, not the output pages, that is, in -2, printing with -a1 will print the first virtual page, i.e., you will get half the page filled.

     Note that page selection does work with the delegations (see Your Delegations).

 -- Option: -c
 -- Option: --truncate-lines=BOOLEAN
     Cut lines too large to be printed inside the borders.  The maximum line size depends on format and font size used and whether line numbering is enabled.

 -- Option: -i
 -- Option: --interpret=BOOLEAN
     interpret tab and ff chars.  This means that ^L jumps to a new (virtual) pages, tab advances to the next tabulation.

 -- Option: --end-of-line=TYPE
     Specify what sequence of characters denotes the end of line.  TYPE can be:

     n
     unix
          \n.

     r
     mac
          \r.

     nr
          \n\r. As far as we know, this type of end-of-line is not used.

     pc
     rn
          \r\n. This is the type of end-of-line on MS-DOS.

     any
     auto
          Any of the previous cases. This last case prevents the bad surprises with files from PC (trailing ^M).

 -- Option: -X KEY
 -- Option: --encoding=KEY
     Use the input encoding identified by KEY.  See Some Encodings, and the result of a2ps --list=encodings to know what encodings are supported. Typical values are ASCII, latin1... latin6, isoN etc.

 -- Option: --stdin=FILENAME
     Give the name FILENAME to the files read through the standard input.

 -- Option: -t NAME
 -- Option: --title=NAME
     Give the name NAME to the document.  Escapes can be used (see Escapes).

     This is used for instance in the name given to the document from within the PostScript code (so that Ghostview and others can display a file with its real title, instead of just the PostScript file name).

     It is not the name of the output.  It is just a logical title.

 -- Option: --prologue=PROLOGUE
     Use PROLOGUE as the PostScript prologue for a2ps. PROLOGUE must be in a file named PROLOGUE.pro, which must be in a directory of your library path (see Library Files). Available prologues are:
          [file prologue.texi not included]

 -- Option: --print-anyway=BOOLEAN
     force binary printing.  By default, the whole print job is stopped as soon as a binary file is detected.  To detect such a file we make use of a very simple heuristic: if the first sheet of the file contains more than 40% of non-printing characters, it's a binary file.  a2ps also asks file(1) what it thinks of the type of the file.  If file(1) answers data, the file will also be considered as binary, hence not printed.

 -- Option: -Z
 -- Option: --delegate=BOOLEAN
     Enable delegation of some files to delegated applications.  If delegating is on, then a2ps will not process the file by itself, but will call an application which handles the file in another way.  If delegation is off, then a2ps will process every file itself.

     Typically most people don't want to pretty-print a PostScript source file, but want to print what describes that file.  Then set the delegations on.

     See Your Delegations for information on delegating, and option --list=delegations for the applications your a2ps knows.

 -- Option: --toc[=FORMAT]
     Generate a Table of Contents, which FORMAT is an escape (see Escapes) processed as a PreScript file (see PreScript).  If no FORMAT is given (i.e., you wrote --toc), use the default table of contents shape (#{toc}).  If the given format is empty (i.e., you wrote --toc=), don't issue the table of contents.

     Note that it is most useful to define a variable (see Your Variables), for instance, in a configuration file:

          Variable: toc.mine \
          \\Keyword{Table of Content}\n\
          #-1!f\
          |$2# \\keyword{$-.20n} sheets $3s< to $3s> ($2s#) \
          pages $3p<-$3p> $4l# lines\n||\
          \\Keyword{End of toc}\n

     and to give that variable as argument to --toc: a2ps *.c --toc=#{toc.mine}.

     Note too that you can generate only the table of content using --pages:

          a2ps *.c --toc -atoc

Pretty Printing Options
-----------------------

These options are related to the pretty printing features of a2ps.

 -- Option: --highlight-level=LEVEL
     Specify the LEVEL of highlighting.  LEVEL can be

     none
          no highlighting

     normal
          regular highlighting

     heavy
          even more highlighting.

     See the documentation of the style sheets (--list=style-sheets) for a description of heavy highlighting.

 -- Option: -g
     Alias for --highlight-level=heavy.

 -- Option: -E[LANGUAGE]
 -- Option: --pretty-print[=LANGUAGE]
     With no arguments, set automatic style selection on.  Otherwise, set style to LANGUAGE.  Note that setting LANGUAGE to plain turns off pretty-printing.  See Known Style Sheets, and the output of --list=style-sheets for the available style sheets.

     If LANGUAGE is KEY.ssh, then don't look in the library path, but use the file KEY.SSH.  This is to ease debugging non installed style sheets.

 -- Option: --strip-level=NUM
     Depending on the value of NUM:

     0
          everything is printed;

     1
          regular comments are not printed

     2
          strong comments are not printed

     3
          no comment is printed.

     This option is valuable for instance in java in which case strong comments are the so called documentation comments, or in SDL for which some graphical editors pollutes the specification with internal data as comments.

     Note that the current implementation is not satisfactory: some undesired blank lines remain.  This is planed to be fixed.

Output Options
--------------

These are the options to specify what you want to do out of what a2ps produces.  Only a single destination is possible at a time, i.e., if ever there are several options -o, -P or -d, the last one is honored.

 -- Option: -o FILE
 -- Option: --output=FILE
     leave output to file FILE.  If FILE is -, leave output to the standard output.

 -- Option: --version-control=TYPE
     to avoid loosing a file, a2ps offers backup services.  This is enabled when the output file already exists, is regular (that is, no backup is done on special files such as /dev/null), and is writable (in this case, disabling version control makes a2ps fail the very same way as if version control was disabled: permission denied).

     The type of backups made can be set with the VERSION_CONTROL environment variable, which can be overridden by this option.  If VERSION_CONTROL is not set and this option is not given, the default backup type is `existing'.  The value of the VERSION_CONTROL environment variable and the argument to this option are like the GNU Emacs version-control variable; they also recognize synonyms that are more descriptive.  The valid values are (unique abbreviations are accepted):

     none
     off
          Never make backups (override existing files).

     t
     numbered
          Always make numbered backups.

     nil
     existing
          Make numbered backups of files that already have them, simple backups of the others.

     never
     simple
          Always make simple backups.

 -- Option: --suffix=SUFFIX
     The suffix used for making simple backup files can be set with the SIMPLE_BACKUP_SUFFIX environment variable, which can be overridden by this option.  If neither of those is given, the default is ~, as it is in Emacs.

 -- Option: -P NAME
 -- Option: --printer=NAME
     send output to printer NAME.  See item Printer: and Unknown printer: in Your Printers and results of option --list=defaults to see the bindings between printer names and commands.

     It is possible to pass additional options to lpr or lp via the variable lp.options, for more information see Pass Options to lpr.

 -- Option: -d
     send output to the default printer. See item DefaultPrinter: in Your Printers.

PostScript Options
------------------

The following options are related only to variations you want to produce onto a PostScript output.

 -- Option: --ppd[=KEY]
     With no argument, set automatic PPD selection, otherwise set the PPD to KEY. FIXME: what to read.

 -- Option: -n NUM
 -- Option: --copies=NUM
     print NUM copies of each page

 -- Option: -s DUPLEX-MODE
 -- Option: --sides=DUPLEX-MODE
     Specify the number of sheet sides, or, more generally, the Duplex mode (see Glossary). The valid values for DUPLEX-MODE are:

     1
     simplex
          One page per sheet.

     2
     duplex
          Two pages per sheet, DuplexNoTumble mode.

     tumble
          Two pages per sheet, DuplexTumble mode.

     Not only does this option require Duplex from the printer, but it also enables duplex features from a2ps (e.g., the margin changes from front pages to back pages etc.).

 -- Option: -S KEY[:VALUE]
 -- Option: --setpagedevice=KEY[:VALUE]
     Pass a page device definition to the generated PostScript output.  If no VALUE is given, KEY is removed from the definitions. Note that several --setpagedevice can be accumulated.

     For example, command

          ubu $ a2ps -SDuplex:true -STumble:true NEWS
          [NEWS (plain): 15 pages on 8 sheets]
          [Total: 15 pages on 8 sheets] sent to the default printer

     prints file report.pre in duplex (two sides) tumble (suitable for landscape documents).  This is also valid for delegated files:

          a2ps -SDuplex:true -STumble:true a2ps.texi

     Page device operators are implementation dependent but they are standardized.  See Page Device Options, for details.

 -- Option: --statusdict=KEY[:VALUE]
 -- Option: --statusdict=KEY[::VALUE]
     Pass a statusdict definition to the generated PostScript output. statusdict operators and variables are implementation dependent; see the documentation of your printer for details.  See Statusdict Options, for details.  Several --statusdict can be accumulated.

     If no VALUE is given, KEY is removed from the definitions.

     With a single colon, pass a call to an operator, for instance:

          a2ps --statusdict=setpapertray:1 quicksort.c

     prints file quicksort.c by using paper from the paper tray 1 (assuming that printer supports paper tray selection).

     With two colons, define variable KEY to equal VALUE.  For instance:

          a2ps --statusdict=papertray::1 quicksort.c

     produces

            /papertray 1 def

     in the PostScript.

 -- Option: -k
 -- Option: --page-prefeed
     enable page prefeeding.  It consists in positioning the sheet in the printing area while the PostScript is interpreted (instead of waiting the end of the interpretation of the page before pushing the sheet).  It can lead to an significant speed up of the printing.

     a2ps quotes the access to that feature, so that non supporting printers won't fail.

 -- Option: -K
 -- Option: --no-page-prefeed
     disable page prefeeding.

Escapes
=======

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

Use of Escapes
--------------

They are used in several places in a2ps:

Page markers
     Headers, footers, titles and the water mark (see Headings Options), in general to print the name of file, page number etc.  On a new sheet a2ps first draws the water mark, then the content of the first page, then the frame of the first page, (ditto with the others), and finally the sheet header and footers.  This order must be taken into account for some escapes (e.g., $l., $l^).

Named output
     To specify the generic name of the file to produce, or how to access a printer (see Your Printers).

Delegation
     To specify the command associated to a delegation (see Your Delegations).

Table of Content
     To specify an index/table of content printed at the end of the job.

Variables in PostScript prologue
     To allow the user to change some parameters to your prologues (see Designing PostScript Prologues).

General Structure of the Escapes
--------------------------------

All format directives can also be given in format

ESCAPE WIDTH DIRECTIVE

where

escape
     In general

     %
          escapes are related to general information (e.g., the current date, the user's name etc.),

     #
          escapes are related to the output (e.g., the output file name) or to the options you gave (e.g., the number of virtual pages etc.), or to special constructions (e.g., enumerations of the files, or tests etc.),

     $
          escapes are related to the current input file (e.g., its name, its current page number etc.),

     \
          introduces classical escaping, or quoting, sequences (e.g., \n, \f etc.).

width
     Specifies the width of the column to which the escape is printed. There are three forms for WIDTH

     +PADDINGINTEGER
          the result of the expansion is prefixed by the character PADDING so that the whole result is as long as INTEGER.  For instance $+.10n with a file name $n=foo.c gives .....foo.c.

          If no PADDING is given,   (white space) is used.

     -PADDINGINTEGER
          Idem as above, except that completion is done on the left: $+.10n gives foo.c......

     INTEGER
          which is a short cut for +INTEGER. For example, escape $5P will expand to something like 12.

directive
     See Available Escapes.

Available Escapes
-----------------

Supported escapes are:

\\
     character \

\%
     character %

\$
     character $

\#
     character #

#?COND|IF_TRUE|IF_FALSE|
     this may be used for conditional assignment.  The separator (presented here as |) may be any character.  IF_TRUE and IF_FALSE may be defined exactly the same way as regular headers, included escapes and the #? construct.

     The available tests are:

     #?1
     #?2
     #?3
          true if tag 1, 2 or 3 is not empty.  See item $t1 for explanation.

     #?d
          true if Duplex printing is requested (-s2).

     #?j
          true if bordering is asked (-j).

     #?l
          true if printing in landscape mode.

     #?o
          true if only one virtual page per page (i.e., #v is 1).

     #?p
          a page range has been specified (i.e., #p is not empty).

     #?q
          true if a2ps is in quiet mode.

     #?r
          true if major is rows (--major=rows).

     #?v
          true if printing on the back side of the sheet (verso).

     #?V
          true if verbosity level includes the tools flag (see Global Options. option --verbosity).

#!KEY|IN|BETWEEN|
     Used for enumerations.  The separator (presented here as |) may be any character.  IN and BETWEEN are escapes.

     The enumerations may be:

     #!$
          enumeration of the command line options.  In this case IN in never used, but is replaced by the arguments.

     #!f
          enumeration of the input files in the other they were given.

     #!F
          enumeration of the input files in the alphabetical order of their names.

     #!s
          enumeration of the files appearing in the current sheet.

     For instance, the escapes The files printed were: #!f|$n|,
     |. evaluated with input a2ps NEWS main.c -o foo.ps, gives
     The files printed were: NEWS, main.c..

     As an exception, #! escapes use the WIDTH as the maximum number of objects to enumerate if it is positive, e.g., #10!f|$n|, | lists only the ten first file names.  If WIDTH is negative, then it does not enumerate the -WIDTH last objects (e.g., #-1!f|$n|, | lists all the files but the last).

${VAR}
     value of the environment variable VAR if defined, nothing otherwise.

${VAR:-WORD}
     if the environment variable VAR is defined, then its value, otherwise WORD.

${VAR:+WORD}
     if the environment variable VAR is defined, then WORD, otherwise nothing.

$[NUM]
     value of the NUMth argument given on the command line.  Note that $[0] is the name under which a2ps has been called.

#{KEY}
     expansion of the value of the variable KEY if defined, nothing otherwise (see Your Variables)

#{KEY:-WORD}
     if the variable VAR is defined, then the expansion of its, otherwise WORD.

#{KEY:+WORD}
     if the variable VAR is defined, then WORD, otherwise nothing.

#.
     the extension corresponding to the current output language (e.g. ps).

%*
     current time in 24-hour format with seconds hh:mm:ss

$*
     file modification time in 24-hour format with seconds hh:mm:ss

$#
     the sequence number of the current input file

%#
     the total number of files

%a
     the localized equivalent for Printed by USER NAME. USER NAME is obtained from the variable user.name (see Predefined Variables).

%A
     the localized equivalent for Printed by USER NAME from HOST NAME. The variables user.name and user.host are used (see Predefined Variables).

%c
     trailing component of the current working directory

%C
     current time in hh:mm:ss format

$C
     file modification time in hh:mm:ss format

%d
     current working directory

$d
     directory part of the current file (. if the directory part is empty).

%D
     current date in yy-mm-dd format

$D
     file modification date in yy-mm-dd format

%D{STRING}
     format current date according to STRING with the strftime(3) function.

$D{STRING}
     format file's last modification date according to STRING with the strftime(3) function.

%e
     current date in localized short format (e.g., Jul 4, 76 in English, or 14 Juil 89 in French).

$e
     file modification date in localized short format.

%E
     current date in localized long format (e.g., July 4, 76 in English, or Samedi 14 Juillet 89 in French).

$E
     file modification date in localized long format.

$f
     full file name (with directory and suffix).

\f
     character \f (form feed).

#f0
#f9
     ten temporary file names.  You can do anything you want with them, a2ps removes them at the end of the job.  It is useful for the delegations (see Your Delegations) and for the printer commands (see Your Printers).

%F
     current date in dd.mm.yyyy format.

$F
     file modification date in dd.mm.yyyy format.

#h
     medium height in PostScript points

$l^
     top most line number of the current page

$l.
     current line number.  To print the page number and the line interval in the right title, use --right-title="$q:$l^-$l.".

$l#
     number of lines in the current file.

%m
     the host name up to the first . character

%M
     the full host name

\n
     the character \n (new line).

%n
     shortcut for the value of the variable user.login (see Predefined Variables).

$n
     input file name without the directory part.

%N
     shortcut for the value of the variable user.name (see Predefined Variables).

$N
     input file name without the directory, and without its suffix (e.g., on foo.c, it will produce foo).

#o
     name of the output, before substitution (i.e., argument of -P, or of -o).

#O
     name of the output, after substitution.  If output goes to a file, then the name of the file.  If the output is a symbolic printer (see Your Printers), the result of the evaluation.  For instance, if the symbolic printer file is defined as > $n.%., then #O returns foo.c.ps when printing foo.c to PostScript.  #o would have returned file.

#p
     the range of the page to print from this page.  For instance if the user asked --pages=1-10,15, and the current page is 8, then #p evaluates to 1-3,8.

$p^
     number of the first page of this file appearing on the current sheet. Note that $p., evaluated at the end of sheet, is also the number of the last page of this file appearing on this sheet.

$p-
     interval of the page number of the current file appearing on the current sheet.  It is the same as $p^-$p., if $p^ and $p. are different, otherwise it is equal to $p..

%p.
     current page number

$p.
     page number for this file

%p#
     total number of pages printed

$p#
     number of pages of the current file

$p<
     number of the first page of the current file

$p>
     number of the last page of the current file

%q
     localized equivalent for Page %p.

$q
     localized equivalent for Page $p.

%Q
     localized equivalent for Page %p./%p#

$Q
     localized equivalent for Page $p./$p#

$s<
     number of the first sheet of the current file

%s.
     current sheet number

$s.
     sheet number for the current file

$s>
     number of the last sheet of the current file

%s#
     total number of sheets

$s#
     number of sheets of the current file

%t
     current time in 12-hour am/pm format

$t
     file modification time in 12-hour am/pm format

$t1
$t2
$t3
     Content of tag 1, 2 and 3. Tags are pieces of text a2ps fetches in the files, according to the style.  For instance, in mail-folder style, tag 1 is the title of the mail, and tag 2 its author.

%T
     current time in 24-hour format hh:mm

$T
     file modification time in 24-hour format hh:mm

#v
     number of virtual sheets

%V
     the version string of a2ps.

#w
     medium width in PostScript points

%W
     current date in mm/dd/yy format

$W
     file modification date in mm/dd/yy format

Configuration Files
*******************

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

 1. the system configuration file (usually /usr/local/etc/a2ps.cfg) unless you have defined the environment variable A2PS_CONFIG, in which case a2ps reads the file it points to;

 2. the user's home configuration file ($HOME/.a2ps/a2psrc)

 3. the local file (./.a2psrc)

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

The file a2ps.cfg is updated when you update a2ps, 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.

Including Configuration Files
=============================

 -- Configuration Setting: Include: FILE
     Include (read) the configuration FILE.  if FILE is a relative path (i.e., it does not start with /), then it is relatively to the current configuration file.

This is especially useful for the site specific configuration file etc/a2ps.cfg: you may tune your printers etc. in a separate file for easy upgrade of a2ps (and hence of its configuration files).

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

Your Default Options
====================

 -- Configuration Setting: Options: OPTIONS+
     Give a2ps a list of command line options. OPTIONS+ is any sequence of regular command line options (see Invoking a2ps).

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

          Options: --medium=Letter

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

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

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

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

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

Your Shortcuts
==============

You can define some kind of `Macro Options' which stand for a set of options.

 -- Configuration Setting: UserOption: SHORTCUT OPTIONS...
     Define the SHORTCUT to be the list of OPTIONS....  When a2ps is called with -=SHORTCUT (or --user-option=SHORTCUT), consider the list of OPTIONS....

Examples are

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

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

Your PostScript magic number
============================

a2ps produces full DSC conformant PostScript (see Glossary). Adobe said

     Thou shalt start your PostScript DSC conformant files with

          %!PS-Adobe-3.0

The bad news is that some printers will reject this header.  Then you may change this header without any worry since the PostScript produced by a2ps is also 100% PostScript level 1 (That is to say, there
are 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 %!.

Your Page Labels
================

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

a2ps lets you define what you want in this field.

 -- Configuration Setting: PageLabelFormat: FORMAT
     Specify the FORMAT to use to label the PostScript pages. FORMAT can use Escapes (see Escapes).  Two variables are predefined for this: #{pl.short} and #{pl.long}.

Your Variables
==============

There are many places in a2ps where one would like to have uniform way of extending things.  It once became clear that variables where needed in a2ps.

Defining Variables
------------------

 -- Configuration Setting: Variable: KEY VALUE
     Define the escape #{KEY} to be a short cut for VALUE.  KEY must not have any character from :(){}.

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

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

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

del
     for variables that are related to delegations.

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

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

pl
     for page label formats. See Your Page Labels, the option --page-label in Input Options.

toc
     for toc formats.  See the option --toc in Input Options.

user
     for user related information.  See Predefined Variables.

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

Predefined Variables
--------------------

There are a few predefined variables.  The fact that a2ps builds them at startup changes nothing to their status: they can be modified like any other variable using --define (see Global Options).

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

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

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

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

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

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

Your Delegations
================

There are some files you don't really want a2ps to pretty-print, typically page description files (e.g., PostScript files, roff files, etc.).  You can let a2ps delegate the treatment of these files to other applications.  The behavior at run time depends upon the option --delegate (see Input Options).

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 (Current a2ps only handles PostScript output, i.e. OUT=ps) thanks to COMMAND.  Both IN and OUT are a2ps type keys such as defined in sheets.map (see The Entry in sheets.map).

COMMAND should produce the file on its standard output.  Of course escapes substitution is performed on COMMAND (see Escapes). In particular, COMMAND should use the input file $f.

     # In general, people don't want to pretty-print PostScript files.
     # Pass the PostScript files to psnup
     Delegation: PsNup ps:ps \
             psselect #?V||-q| -p#?p|#p|-| $f | \
             psnup -#v -q #?j|-d|| #?r||-c| -w#w -h#h

Advantage should be taken from the variables, to encapsulate the peculiarities of the various programs.

     # Passes the options to psnup.
     # The files (in and out) are to be given
     Variable: psnup psnup -#v #?V||-q| #?j|-d|| #?r||-c| -w#w -h#h

     # Passes to psselect for PS page selection
     Variable: psselect psselect #?V||-q| -p#?p|#p|-|

     # In general, people don't want to pretty-print PostScript files.
     # Pass the PostScript files to psnup
     Delegation: PsNup ps:ps     #{psselect} $f | #{psnup}

Temporary file names (#f0 to #f9) are available for complex commands.

     # Pass DVI files to dvips.
     # A problem with dvips is that even on failure it dumps its prologue,
     # hence it looks like a success (output is produced).
     # To avoid that, we use an auxiliary file and a conditional call to
     # psnup instead of piping.
     Delegation: dvips dvi:ps    #{dvips} $f -o #f0 && #{psnup} #f0

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 (Because hiding its use into a2ps just makes it even more difficult to the users to know why it failed.  Let them use it by hand.).  As a thumb rule, you should check that the PostScript generating applications produce files that start by:

     %!PS-Adobe-3.0

a2ps needs the %%BeginSetup-%%EndSetup section in order to output correctly the page device definitions.  It can happen that your filters don't output this section.  In that case, you should insert a call to fixps right after the PostScript generation:

     ########## ROFF files
     # Pass the roff files to groff.  Ask grog how groff should be called.
     # Use fixps to ensure there is a %%BeginSetup/%%EndSetup section.
     Delegation: Groff roff:ps	\
        eval `grog -Tps '$f'` | fixps #?V!!-q! | #{d.psselect} | #{d.psnup}

There are some services expected from the delegations.  The delegations you may write should honor:

the input file
     available via the escape $f.  You should be aware that there are people who have great fun having spaces or dollars in their file names, so you probably should always use '$f'.  Some other variables are affected.  Yes, I know, we need a special mechanism for ' itself. Well, we'll see that later ;-).

the medium
     the dimension of the medium selected by the user are available through #w and #h.

the page layout
     the number of virtual pages is #v.

the page range
     the page range (in a form 1-2,4-6,10- for instance) is available by #p.

the verbosity level
     please, do not make your delegations verbose by default.  The silent mode should always be requested, unless #?V is set (see the above example with groff).

If ever you need several commands, do not use ; to separate them, since it may prevent detection of failure.  Use && instead.

The slogan "the sooner, the better" should be applied here: in the processing chain, it is better to ask a service to the first application that supports it.  An example will make it clear: when processing a DVI file, dvips knows better the page numbers than psselect would.  So a DVI to PostScript delegation should ask the page selection (#p) to dvips, instead of using psselect later in the chain.  An other obvious reason here is plain efficiency (globally, less data is processed).

Predefined Delegations
----------------------

The purpose of this section is not to document all the predefined delegations, for this you should read the comments in the system configuration file a2ps.cfg.  We just want to explain some choices, and give hints on how to make the best use of these delegations.

 -- Delegation: dvips (DVI to PostScript)
     There is a problem when you use a naive implementation of this delegation: landscape jobs are not recognized, and therefore n-upping generally fails miserably.  Therefore, a2ps tries to guess if the file is landscape by looking for the keyword landscape in it, using strings(1):

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

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

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

     in the preamble.

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

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

Your Internal Details
=====================

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

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

Library Files
*************

To be general and to allow as much customization as possible, a2ps avoids 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 VERSION
     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 Your Library Path).

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

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.

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.), a2ps should use VALUE (e.g., font file name, encoding description file name etc.).

The map files used in a2ps are:

encoding.map
     Resolving encodings aliases.

fonts.map
     Mapping font names to font file names.

sheets.map
     Rules to decide what style sheet to use.

Font Files
==========

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

Fonts Map File
--------------

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

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

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

Fonts Description Files
-----------------------

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

  - the AFM file (FONT-KEY.afm), which describes the metrics information corresponding to FONT;

  - in the case FONT is not known from the printer, the PFA or PFB file which is down loaded to the printer.  These files are actually the PostScript programs which execution produces the characters to be drawn on the page, in this FONT.

Adding More Font Support
------------------------

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

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

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

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

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

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

Style Sheet Files
=================

The style sheets are defined in various files.  See 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 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 a2ps to consider that the 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 a2ps will run file(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, a2ps may use bad style sheets. In 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*>

Encodings
*********

a2ps is trying to support the various usual encodings that its users use.  This chapter presents what an encoding is, how the encodings support is handled within a2ps, and some encodings it supports.

What is an Encoding
===================

This section is actually taken from the web pages of Alis Technologies inc. (http://www.alis.com/)

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.

Encoding Files
==============

The support of the encodings in a2ps is completely taken out of the code.  That is to say, adding, removing or changing anything in its support for an encoding does not require programming, nor even being a programmer.

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

Encoding Map File
-----------------

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

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

     ALIAS      KEY
     iso-8859-1 latin1
     latin1     latin1
     l1         latin1

where

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

     When ENCODING is asked, the lower case version of ENCODING must be equal to ALIAS.

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

Encoding Description Files
--------------------------

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

  - please make the name portable: alpha-numerical, at most 8 characters,

  - empty lines and lines starting by # are ignored.

The entries are

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

          Name: ISO-8859-1

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

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

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

     For instance in iso2.edf one can read:

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

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

          Default: Courier-Ogonki

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

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

Some Encodings
--------------

Most of the following information is a courtesy of Alis Technologies inc. (http://www.alis.com/) and of Roman Czyborra's page about The ISO 8859 Alphabet Soup (http://czyborra.com/charsets/). See What is an Encoding, is an instructive presentation of the encodings.

     [file encoding.texi not included]

Pretty Printing
***************

The main feature of a2ps is its pretty-printing capabilities. Two 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.

Syntactic limits
================

a2ps is not a powerful syntactic pretty-printer: it just handles lexical structures, i.e., if in your favorite language

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

is legal, then a2ps is not the tool you need.  Indeed a2ps just looks for some keywords, or some sequences.

Known Style Sheets
==================

     [file sheets.texi not included]

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

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

PreScript
---------

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

The main advantages for using PreScript are:

  - it is fairly simple,

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

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

Syntax
......

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:

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

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

Examples
........

PreScript and a2ps can be used for one-the-fly formating. For instance, on the passwd file:

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

PreTeX
------

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

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.

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 LaTeXbut have no sense in PreTeX. Hence there are simply ignored and not printed (if immediately followed by an end-of-line).

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.

TeXScript
---------

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

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

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

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

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

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

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

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

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

Faces
=====

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

The faces a2ps uses are:

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.

Style Sheets Semantics
======================

a2ps pretty prints a source file thanks to style sheets, one 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 does this, and if you don't expect to implement new styles.

Name and key
------------

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

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

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

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

Comments
--------

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

Alphabets
---------

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

Case sensitivity
----------------

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

P-Rules
-------

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

lhs
left-hand side
     its source string, with which the source file is compared;

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

       - a string, or a reference to a part of the source string (see Back-reference Operator (Regex manual))

       - the face to use to print it

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

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

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

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

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

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

     a_rule : part1 part2 ;

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

 1. it must start at the beginning of the line,

 2. then there is string composed of symbols, which is what you want to highlight,

 3. and a colon, which can be preceded by blank characters.

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

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

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

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

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

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

Sequences
---------

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

Optional entries
----------------

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

Style Sheets Implementation
===========================

In the previous section (see Style sheets semantics) were explained the various items needed to understand the machinery involved in pretty printing.  Here, their implementation, i.e., how to write a style sheet file,  is explained.  The next section (see A tutorial on style sheets), exposes a step by step simple example.

A Bit of Syntax
---------------

Here are the lexical rules underlying the style sheet language:

  - the separators are white space, form feed, new line, and tab.

  - # introduces a comment, ended at the end of the line.

  - special characters are the separators, plus #, ", ,, (, ), + and /.  Any other character is a regular character.

  - the list of the structuring keywords is

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

  - the list of the keywords designating faces is

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

  - the list of keywords designating special sequences is

          C-char, C-string

  - the list of keywords representing special characters is

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

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

          a2ps symbols.ssh

  - a string starts and finishes with ", and may contain anything. Regular C escaping mechanism is used.

  - a regular expression starts and finishes with /, and may contain anything.  Regular C escaping mechanism is used.  Regexps can be split in several parts, a` la C strings (i.e., /part 1/ /part 2/).

  - any sequence of regular characters which is not a keyword, is a string (consider this as a shortcut, avoiding extraneous ").

Style Sheet Header
------------------

The definition of the name of the style sheet is:

     style NAME is
       # body of the style sheet
     end style

The following constructions are optional:

version
     To define the version number of the style sheet

          version is VERSION-NUMBER

written
     To define the author(s).

          written by AUTHORS

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

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

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

          requires a2ps A2PS-VERSION-NUMBER

documentation
     To leave extra comments people should read.

          documentation is
             STRINGS
          end documentation

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

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

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

Syntax of the Words
-------------------

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

alphabet
     To define two different alphabets, use

          first alphabet is STRING
          second alphabet is STRING

     If both are identical, you may use the shortcut

          alphabets are STRING

     The default alphabets are

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

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

case

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

     The default is case insensitive.

Inheriting from Other Style Sheets
----------------------------------

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

     ancestors are
        ANCESTOR_1[, ANCESTOR_2...]
     end ancestors

where ANCESTOR1 etc. are style sheet keys.

For semantics, the rules are the following:

  - the ancestors are read in order;

  - the definition of the current style is read last;

  - it is always the last item read which wins (last defined alphabets, case sensitivity, keywords, operators and sequences).

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

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

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

Syntax for the P-Rules
----------------------

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

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

     RULES     ::= RULE_1 , RULE_2...
     RULE      ::= ( LHS RHS )
                | LHS SRHS ;
     LHS       ::= STRING | REGEX ;
     RHS       ::= SRHS , ...
     SRHS      ::= LATEX-KEYWORD | EXPANSION FACE
     EXPANSION ::= STRING | \NUM | <nothing>;
     FACE      ::= FACE-KEYWORD | <nothing>;

The rules are the following:

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

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

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

  - If no EXPANSION is specified, then the matched string is used. For instance (/fo*/, NULL, Keyword) applied on the source fooooo produces fooooo in Keyword.

  - If no FACE is given, then

       - if the context defines the default face, then this face is used;

       - if no default face is given, PLAIN is used.

Declaring the keywords and the operators
----------------------------------------

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

     keywords are
       RULES
     end keywords

or

     keywords in FACE-KEYWORD are
       RULES
     end keywords

in which case the default face is set to FACE-KEYWORD.

As an example:

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

is valid.

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

This is an extract of the C style sheet:

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

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

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

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

In term of implementation, it means that

     keywords are
       /foo|bar/
     end keywords

is exactly the same as

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

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

See Match-word-boundary Operator (Regex manual), for details on \b.

Declaring the sequences
-----------------------

Sequences admit several declarations too:

     SEQUENCES      ::= sequences are
                          SEQUENCE_1 , SEQUENCE_2...
                        end sequences
     SEQUENCE       ::= RULE IN_FACE CLOSE_OPT EXCEPTIONS_OPT
                      | C-string
                      | C-char
                      ;
     CLOSE_OPT      ::= RULE
                      | closers are
                          RULES
                        end closers
                      | <nothing>
                      ;
     EXCEPTIONS_OPT ::= exceptions are
                          RULES
                        end exceptions
                      | <nothing>
                      ;

The rules are:

  - The default face is then IN_FACE.

  - If no closing rule is given, "\n" (i.e., end-of-line) is used.

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

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

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

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

     sequences are
       # The comments
       "#" Comment,

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

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

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

     end sequences

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

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

     /*
      * a comment
      */

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

     //
     // a comment
     //

Checking a Style Sheet
----------------------

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

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

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

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

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

A Tutorial on Style Sheets
==========================

In this section a simple example of style sheet is entirely covered: that of ChangeLog files.

ChangeLog files are some kind of memory of changes done to files, so that various programmers can understand what happened to the sources. This helps a lot, for instance, in guessing what recent changes may have introduced new bugs.

Example and syntax
------------------

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

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

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

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

             * color.ps: Added box and underline routines.

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

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

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

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

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

Implementation
--------------

Quite naturally the style will be called ChangeLog, hence:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The Entry in sheets.map
-----------------------

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

     # ChangeLog files
     chlog:  /ChangeLog*/

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

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

     # ChangeLog files
     chlog:  /*ChangeLog*/

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

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

More Sophisticated Rules
------------------------

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

The target will be the lines like:

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

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

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

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

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

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

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

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

Notice the way regexps are split, to ease reading.

Guide Line for Distributed Style Sheets
---------------------------------------

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

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

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

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

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

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

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

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

PostScript
**********

This chapter is devoted to the information which is only relevant to PostScript.

Foreword: Good and Bad PostScript
=================================

To read this section, the reader must understand what DSC are (see Glossary).

     Why are there good PostScript files, easy to post-process, and bad files that none of my tools seem to understand?  They print fine though!

Once you understood that PostScript is not a page description format (like PDF is), you'll have understood most of the problem.  Let's imagine for a second that you are a word processor.

The user asks you to print his/her 100 page document in PostScript.  Up to page 50, there are few different fonts used.  Then, on pages 51 to 80, there are now many different heavy fonts.

When/where will you download the fonts?

The most typical choice, sometimes called Optimize for Speed, is, once you arrived to page 51, to download those fonts once for the rest of the document.  The global processing chain will have worked quite quickly: little effort from the software, same from the printer; better yet: you can start sending the file to the printer even before it is finished!  The problem is that this is not DSC conformant, and it is easy to understand why: if somebody wants to print only the page 60, then s/he will lack the three fonts which were defined in page 51... This document is not page independent.

Another choice is to download the three fonts in each page ranging from 51 to 80, that is the PostScript file contains 30 times the definition of each font.  It is easy for the application to do that, but the file is getting real big, and the printer will have to interpret 30 times the same definitions of fonts.  But it is DSC conformant!  And you can still send the file while you make it.

Now you understand why

     Non DSC conformant files are not necessarily badly designed files from broken applications.

They are files meant to be sent directly to the printer (they are still perfect PostScript files after all!), they are not meant to be post-processed.  And the example clearly shows why they are right.

There is a third possibility, sometimes called Optimize for Portability: downloading the three fonts in the prologue of the document, i.e., the section before the first page where are given all the common definitions of the whole file.  This is a bit more complicated to implement (the prologue, which is issued first though, grows at the same time as you process the file), and cannot be sent concurrently with the processing (you have to process the whole file to design the prologue).  This file is small (the fonts are downloaded once only), and DSC conformant.  Well, there are problems, of course...  You need to wait before sending the output, it can be costly for the computer (which cannot transfer as it produces), and for the printer (you've burnt quite a lot of RAM right since the beginning just to hold fonts that won't be used before page 51...  This can be a real problem for small printers).

This is what a2ps does.

If should be clear that documents optimized for speed should never escape the way between the computer and the printer: no post-processing is possible.

What you should remember is that some applications offer the possibility to tune the PostScript output, and they can be praised for that. Unfortunately, when these very same applications don't automatically switch to ``Optimize for Portability'' when you save the PostScript file, and they can be criticized for that.

So please, think of the people after you: if you create a PostScript file meant to be exchanged, read, printed, etc; by other people: give sane DSC conformant, optimized for portability files.

Page Device Options
===================

Page device is a PostScript level 2 feature that offers an uniform interface to control the printer's output device.  a2ps protects all page device options inside an if block so they have no effect in level 1 interpreters.  Although all level 2 interpreters support page device, they do not have to support all page device options.  For example some printers can print in duplex mode and some can not.  Refer to the documentation of your printer for supported options.

Here are some usable page device options which can be selected with the -S option (--setpagedevice).  For a complete listing, see PostScript Language Reference Manual (section 4.11 Device Setup in the second edition, or section 6, Device Control in the third edition).

Collate BOOLEAN
     how output is organized when printing multiple copies

Duplex BOOLEAN
     duplex (two side) printing

ManualFeed BOOLEAN
     manual feed paper tray

OutputFaceUp BOOLEAN
     print output `face up' or `face down'

Tumble BOOLEAN
     how opposite sides are positioned in duplex printing

Statusdict Options
==================

The statusdict is a special storage entity in PostScript (called a dictionary), in which some variables and operators determine the behavior of the printer.  This is an historic horror that existed before page device definitions were defined.  They are even more printer dependent, and are provided only for the people who don't have a level printer.  In any case, refer to the documentation of your printer for supported options.

Here are some statusdict definitions in which you might be interested:

manualfeed BOOLEAN
     Variable which determine that the manual fed paper tray will be used. Use is --statusdict=manualfeed::true.

setmanualfeed BOOLEAN
     Idem as the previous point, but use is --statusdict=setmanualfeed:true.

setduplexmode BOOLEAN
     If BOOLEAN, then print Duplex.  Use if --statusdict=setduplexmode:true.

Colors in PostScript
====================

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

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

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

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

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

a2ps PostScript Files
=====================

a2ps uses several types of PostScript files.  Some are standards, such as font files, and others are meant for a2ps only.

All a2ps files have two parts, one being the comments, and the other being the content, separated by the following line:

     % code follows this line

Designing PostScript Prologues
==============================

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

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

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

Definition of the faces
-----------------------

There are three things that define a face:

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

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

          %Face: FACE REAL-FONT-NAME SIZE

     This line tells a2ps that the font of FACE is REAL-FONT-NAME.  It will replace this line by the correct PostScript line to call the needed font, and will do everything needed to set up the font.

     The size of the text body is bfs.

Its background color
     There are two cases:

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

               0.8 0.8 0 true BG

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

               false BG

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

          0 0.5 0 FG

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

          true UL

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

Prologue File Format
--------------------

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

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

See Documentation Format, for more on the format.

A step by step example
----------------------

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

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

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

Then you need to look for k and K:

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

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

and turn it into:

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

     /K {
       0.4 0.2 0 true BG
       0.5 1 1 FG
     %Face: Keyword_strong Times-BoldItalic bfs
       Show
     } bind def

Waouh!  It looks great!

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

First, let's look for the font definition:

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

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

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

How about its foreground color?

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

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

Contributions
*************

This chapter documents the various shell scripts or other tools that are distributed with the a2ps package, but are not a2ps itself.  The reader should also look at the documentation of Ogonkify (see Overview (Ogonkify manual)), written by Juliusz Chroboczek.

card
====

Many users of a2ps have asked for a reference card, presenting a summary of the options.  In fact, something closely related to the output of a2ps --help.

The first version of this reference card was a PreScript file (see PreScript) to be printed by a2ps.  Very soon a much better scheme was found: using a style sheet to pretty print directly the output of a2ps --help!  A first advantage is then that the reference cards can be printed in the tongue you choose.

A second was that this treatment could be applied to any application supporting a --help-like option.

Invoking card
-------------

     card [OPTIONS] APPLICATIONS [-- A2PS-OPTIONS]

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

Supported options are:

 -- Option: -h
 -- Option: --help
     print a short help message and exit successfully.

 -- Option: -V
 -- Option: --version
     report the version and exit successfully.

 -- Option: -q
 -- Option: --quiet
 -- Option: --silent
     Run silently.

 -- Option: -D
 -- Option: --debug
     enter in debug mode.

 -- Option: -l LANGUAGE
 -- Option: --language=LANGUAGE
     specify the language in which the reference card should be printed. LANGUAGE should be the symbol used by LC_ALL etc. (such as fr, it etc.).

     If the APPLICATIONS don't support internationalization, English will be used.

 -- Option: --command=COMMAND
     Don't try to guess the APPLICATIONS' way to report their help message, but rather use the call COMMAND. A typical example is

          card --command="cc -flags"

It is possible to give options to a2ps (see Options) by specifying them after --.  For instance

     card gmake gtar --command="cc -flags" -- -Pdisplay

builds the reference card of GNU make, GNU tar (automatic detection of --help support), and cc thanks to -flags.

Caution when Using card
-----------------------

Remember that card runs the programs you give it, and the commands you supplied.  Hence if there is a silly programs that has a weird behavior given the option -h etc., beware of the result.

It is even clearer using --command: avoid running card --command="rm -rf *", because the result will be exactly what you think it will be!

fixps
=====

The shell script fixps tries its best to fix common problems in PostScript files that may prevent post processing.  It makes heavy use of the psutils.  It is a good idea to use fixps in the PostScript delegations.

It first tries to make simple fixes, but some really broken files may require a much deeper treatment.  If fixps feels the need for such a major surgery act, it may give up local changes and ask Ghostscript for a global rewriting.

Invoking fixps
--------------

     fixps [OPTIONS] [FILE]

sanitize the PostScript FILE (or of the standard input if no FILE is given, or if FILE is -).

Supported options are:

 -- Option: -h
 -- Option: --help
     Print a short help message and a list of the fixes that are performed.  Exit successfully.

 -- Option: -V
 -- Option: --version
     report the version and exit successfully.

 -- Option: -D
 -- Option: --debug
     enter in debug mode.

 -- Option: -q
 -- Option: --quiet
 -- Option: --silent
     Run silently.

 -- Option: -o FILE
 -- Option: --output=FILE
     specify the FILE in which is saved the output.

 -- Option: -n
 -- Option: --no-fix
     Don't actually fix the FILE but still honor all of the other options.  In particular, fixps -qn FILE is equivalent to cat FILE.

 -- Option: -c
 -- Option: --check
 -- Option: --dry-run
     Don't actually fix the FILE: just report the diagnostics. Contrary to the option fixps -qc does absolutely nothing (while it does take some time to do it nicely).

 -- Option: -f
 -- Option: --force
     Ask ghoscript for a full rewrite of the FILE.  The output file is really sane, but can be much longer than the original.  For this reason and others, it is not always a good idea to make a full rewrite. This option should be used only for files that give major problems.

fixnt
=====

fixnt (see its (http://www.itsm.uni-stuttgart.de/~bauer/fixnt.html), home page) is maintained by Holger Bauer and Michael Rath.  It is meant to fix the problems of the PostScript files generated by the Microsoft PostScript driver under Windows NT (3.5 and 4.0).

fixps is aware of the cases where fixnt should be used, hence you should not worry of when to use fixnt.

Invoking fixnt
--------------

     fixnt < file.ps

sanitize the PostScript file FILE.PS and produce the result on the standard output.

pdiff
=====

The shell script pdiff aims to pretty print diffs between files. It basically uses GNU diff (see Overview (Comparing and Merging Files)) or GNU wdiff (see The word difference finder (GNU wdiff)) to extract the diff, then calls a2ps with the correct settings to get a nice, printed contextual diff.

Invoking pdiff
--------------

     pdiff [OPTIONS] FILE-1 FILE-2 [-- A2PS-OPTIONS]

make a pretty comparison between FILE-1 and FILE-2. A2PS-OPTIONS are passed to a2ps.

Supported options are:

 -- Option: -h
 -- Option: --help
     print a short help message and exit successfully.

 -- Option: -V
 -- Option: --version
     report the version and exit successfully.

 -- Option: -q
 -- Option: --quiet
 -- Option: --silent
     Run silently.

 -- Option: -D
 -- Option: --debug
     enter in debug mode.

 -- Option: -w
 -- Option: --words
     Look for words differences (default).  White space differences are not considered.

 -- Option: -l
 -- Option: --lines
     Look for lines differences.

It is possible to give options to a2ps (see Options) by specifying them after --.  For instance

     pdiff COPYING COPYING.LIB -- -1 -P display

Compares the files COPYING and COPYING.LIB, and prints it on the printer display (usually Ghostview or gv).

psmandup
========

I personally hate to print documents of hundreds of pages on a single sided printer.  Too bad, here there are no Duplex printers.  The idea is then simply first to print the odd pages, then the even in reversed order.  To make sure one flips the page in the meanwhile, the second half should be printed from the manual feed tray.

Make a shell script that automates this, and you get psmandup.

Invoking psmandup
-----------------

     psmandup [OPTIONS] [FILE]

produce a manual duplex version of the PostScript FILE (or of the standard input if no FILE is given, or if FILE is -). Once the first half is printed, put the sheet stack in the manual feed tray for the second half (Many people seem to ignore that you can insert several sheets in the manual feed tray. Try at least once, it will save you from hours spent feeding page per page by hand!).

Be aware that there is a time out for manually fed jobs, usually short, hence do not miss the moment when the printer asks for the stack.  If ever you missed that moment, see option --back to recover the second half.

Supported options are:

 -- Option: -h
 -- Option: --help
     print a short help message and exit successfully.

 -- Option: -V
 -- Option: --version
     report the version and exit successfully.

 -- Option: -q
 -- Option: --quiet
 -- Option: --silent
     Run silently.

 -- Option: -D
 -- Option: --debug
     enter in debug mode.

 -- Option: -o FILE
 -- Option: --output=FILE
     specify the FILE in which is saved the output.

 -- Option: -n
 -- Option: --no-fix
     psmandup will fail on ill designed PostScript (well, actually the psutils will).  To avoid this, by default the PostScript file is sanitized by fixps.

     When given this option, don't run fixps.  This is meant to be used when fixps has already been used higher in the processing chain.

 -- Option: -f
 -- Option: --front
     Output only the front pages, with no special PostScript feature request.

 -- Option: -b
 -- Option: --back
     Output only the back pages, with a manual feed request.

     This option is especially useful when the manual feed time out expired before you could insert back the stack in the manual feed tray.

psmandup assumes the printer is Level 2, and supports manual feeding.  The FILE should be reasonably sane, otherwise psmandup fails miserably.

Typical use is

     psmandup file.ps | lp

or can be put into a2ps' printer commands (see Your Printers).

psset
=====

The shell script psset inserts calls to setpagedevice in a PostScript file.  This is useful for instance to add Tumble or Manual feed request.  Actually, psmandup uses psset.

You should know nevertheless that a2ps is able to make the calls to setpagedevice by itself, i.e., you can run a2ps -SManualFeed foo to print foo onto the manually fed tray, or run a2ps -s2 foo to print Duplex.  There are no need of psset from a2ps.

Invoking psset
--------------

     psset [OPTIONS] [FILE]

produce a version of the PostScript FILE (or of the standard input if no FILE is given, or if FILE is -) that makes protected calls to the PostScript operator setpagedevice. Typical use is making FILE print duplex, or on the manual tray etc.

The call is protected so that the resulting file is safe, i.e., will still be portable, even with requests such as -Sfoo:bar.

It is safe to run psset with no feature requests.  Depending upon the option --no-fix, it is either equivalent to doing nothing, or to running fixps (see fixps).

Supported options are:

 -- Option: -h
 -- Option: --help
     Print a short help message and exit successfully.

 -- Option: -V
 -- Option: --version
     report the version and exit successfully.

 -- Option: -D
 -- Option: --debug
     enter in debug mode.

 -- Option: -q
 -- Option: --quiet
 -- Option: --silent
     Run silently.

 -- Option: -o FILE
 -- Option: --output=FILE
     specify the FILE in which is saved the output.

 -- Option: -n
 -- Option: --no-fix
     psset will fail on ill designed PostScript.  Actually it is the psutils that fail.  To avoid this, by default the PostScript file is sanitized by fixps.

     When given this option, don't run fixps.  This is meant to be used when fixps has already been used higher in the processing chain.

 -- Option: -S KEY:VALUE
 -- Option: --setpagedevice=KEY:VALUE
     Insert a setpagedevice call setting KEY to VALUE. Multiple values accumulate.  Lists of requests separated with ; are valid (e.g., -SDuplex:true;Tumble:false).

 -- Option: -a PAGE
 -- Option: --at=PAGE
     Specify the page where the setpagedevice call should be done. The PAGE 0, which is the default, corresponds to the Setup section of the document.  More precisely, the insertion is performed at the end of the Setup section, so that if there are multiple calls to psset on the same document (which is of course, a bad idea), the last call is winning.

     In a typical use you should not change the PAGE.

 -- Option: -m
 -- Option: --manualfeed
     Alias for -SManualFeed:true, i.e., the request to print using the manual feed tray.

 -- Option: -s
 -- Option: --simplex
     Alias for -SDuplex:false, i.e., force simplex printing.

 -- Option: -d
 -- Option: --duplex
     Alias for -SDuplex:true;Tumble:false, i.e., the request to print in duplex mode, binding along the long edge of the paper.

 -- Option: -t
 -- Option: --tumble
     Alias for -SDuplex:true;Tumble:true, i.e., duplex printing such that binding should happen on the short edge of the medium.

Frequently asked questions
**************************

Please, before sending us mail, make sure the problem you have is not known, and explained.  Moreover, avoid using the mailing list for asking question about the options, etc.  It has been built for announces and suggestions, not to contact the authors.

Why Does...?
============

Error related questions.

Why Does it Print Nothing?
--------------------------

     a2ps works OK, but the printer prints nothing.

There are two ways that printing can fail: silently, or with a diagnostic.

First, check that the printer received what you sent.  a2ps may correctly do its job, but have the printer queue fail to deliver the job.  In case of doubt, please check that the printer's leds blink (or whatever is its way to show that something is being processed).

If the printer does receive the job, but prints nothing at all, check that you did not give exotic options to an old printer (typically, avoid printing on two sides on a printer that does not support it).  Avoid using -S, --setpagedevice (see Page Device Options) and --statusdict (see Statusdict Options).

If the trouble persists, please try again but with the option --debug (a PostScript error handler is downloaded), and then send us:

 1. the input file that gives problems

 2. the output file created by a2ps with the option --debug

 3. the error message that was printed.

Why Does it Print in Simplex?
-----------------------------

     Though I ask a2ps to print Duplex via --sides, the job is
     printed Simplex.

If your printer is too old, then a2ps will not be able to send it the code it needs when -s2 is specified.  This is because your printer uses an old and not standardized interface for special features.

So you need to

 1. specify that you want Duplex mode: -s2,

 2. remove by hand the standardized call to the Duplex feature: -SDuplex,

 3. add the non standard call to Duplex.  Try --statusdict=setduplexmode:true.

Since this is painful to hit, a User Option (see Your Shortcuts) should help.

Why Does it Print in Duplex?
----------------------------

     Though I ask a2ps to print Simplex via --sides, the job is
     printed Duplex.

Actually when you require Simplex, a2ps issues nothing, for portability reasons.  Hence, if your printer is defaulted to Duplex, the job will be Duplexed.  So you have to force a2ps to issue the Simplex request with -SDuplex:false.  The user options -=s1 and -=simplex have names easier to remember.

In the next version of a2ps this kind of portability problems will be fixed in a user friendly way.

Why Does it Not Fit on the Paper?
---------------------------------

     When I print text files with a2ps, it prints beyond the frame of
     the paper.

You are most probably printing with a bad medium, for instance using A4 paper within a2ps, while your printer uses Letter paper.  Some jet printers have a small printable area, and a2ps may not expect it.  In both case, read Sheet Options, option --medium for more.

Why Does it Print Junk?
-----------------------

     What I get on the printer is long and incomprehensible.  It does not seem to correspond to what I wanted to print.

You are probably printing a PostScript file or equivalent.  Try to print with -Z: a2ps will try to do his best to find what is the program that can help you (see Your Delegations).  In case of doubt, don't hesitate to save into a file, and check the content with Ghostview, or equivalent:

     $ a2ps my_weird_file -Z -o mwf.ps
     $ gv mwf.ps

If your a2ps is correctly installed, you can use the display fake-printer:

     $ a2ps my_weird_file -Z -P display

If it is incorrect, ask for help around you.

Why Does it Say my File is Binary?
----------------------------------

     a2ps complains that my file is binary though it is not.

There are several reasons that can cause a2ps to consider a file is binary:

  - there are many non printable characters in the file.  Then you need to use the option --print-anyway.

  - the file is sane, composed of printable characters.  Then it is very likely that file(1) said the type of the file is data, in which case a2ps prefers not to print the file.  Then you can either:

       - specify the type of the file, for instance -Eplain;

       - specify to print in any case, --print-anyway;

       - remove the annoying rule from the system's sheets.map:

               binary: <data*>

       - insert in your own ~/.a2ps/sheets.map a rule that overrides that of the system's sheets.map:

               # Load the system's sheets.map
               include(/usr/local/share/a2ps/sheets/sheets.map)

               # Override the rule for files with type `data' according to file(1)
               plain: <data*>

          But this is not very good, since then this rule is always the first tested, which means that any file with type data according to file(1) will be printed in plain style, even if the file is called foo.c.

       - if your files can be recognized, insert a new rule in a sheets.map, such as

               # file(1) says it's data, but it's pure text
               plain:   /*.txx/

Why Does it Refuse to Change the Font Size
------------------------------------------

     a2ps does not seem to honor --font-size
     (or --lines-per-page, or --chars-per-line).

This is probably because you used -1..-9 after the --font-size.  This is wrong, because the options -1..-9 set the font size (so that there are 80 characters per lines), and many other things (see Page Options, option --font-size).

Hence a2ps --font-size=12km -4 is exactly the same thing as a2ps -4, but is different from a2ps -4 --font-size=12km. Note that the `pure' options (no side-effects) to specify the number of virtual pages are --columns and --rows.

How Can I ...?
==============

A mini how-to on a2ps.

How Can I Leave Room for Binding?
---------------------------------

The option --margin[=SIZE] is meant for this.  See Sheet Options.

How Can I Print stdin?
----------------------

a2ps prints the standard input if you give no file name, or if you gave - as file name.  Automatic style selection is of course much weaker: without the file name, a2ps can only get file(1)'s opinion (see Style Sheet Files).  In general it means most delegations are safe, but there will probably be no pretty-printing.

You can supply a name to the standard input (--stdin=NAME) with which it could guess the language.

How Can I Change the Fonts?
---------------------------

See Designing PostScript Prologues, for details.  Make sure that all the information a2ps needs is available (see Font Files).

How Can I Simulate the Old Option -b?
-------------------------------------

By the past, a2ps had an option -b with which the fonts were bold.  Since now the fonts are defined by prologues (see Designing PostScript Prologues) this option no longer makes sense.  A replacement prologue is provided: bold.  To use it, give the option --prologue=bold.

How Can I Pass Options to lpr
-----------------------------

     How can I tell a2ps to ask lpr no to print the banner?

     How can I pass specific options to lp?

If your Printer: fields in the configuration files were properly filled (see Your Printers), you can use the variable lp.options to pass options to lpr (or lp, depending on your environment):

     a2ps -Dlp.options="-h -s" -P printer

You can also define lp.options once for all, see Defining Variables.

Finally, you can use Printer: several times to reach a printer with different lpr options.

How Can I Print on Non PostScript Printers?
-------------------------------------------

     I use a2ps at work and wish to use it at home, but my printer is
     not PostScript.  How can I do?

Ghostscript might be the tool you need (see Glossary).  It support conversion to many different non PostScript printers.

Here are some tips on how to use a non PostScript printer.  If somebody feels like writing a more precise documentation, she really is welcome.

Please refer to the Ghostscript documentation for a precise description of the tuning you need.

Basically, the first step you need is to achieve to call Ghostscript in a pipe chain.  In other words, try to find out the right arguments Ghostscript needs in order to print with a command like this:

     $ cat file.ps | gs MORE ARGUMENTS

In general it is the same command as for calling Ghostscript with a filename, except that the file name to use is -:

     $ cat file.ps \
       | gs -q -dNOPAUSE -sDEVICE=deskjet -sOutputFile=- - -c quit\
       | lp -dPRINTER-NAME

Once it works, it is then easy to settle the right Printer: line in your configuration file (see Your Printers).  For instance:

     Printer: djet \
       | gs -q -dNOPAUSE -sDEVICE=deskjet -sOutputFile=- - -c quit\
       | lp -d djet

Christian Mondrup uses a2ps under Windows with a non PostScript printer.  He uses:

     DefaultPrinter: | //c/gstools/gs5.10/Gswin32c.exe         \
        -Ic:\gstools\gs5.10;c:\gstools\gs5.10\fonts            \
        -sDEVICE=ljet4 -sPAPERSIZE=a4 -dNOPAUSE -r300 -dSAFER  \
        -sOutputFile="\\spool\HP LaserJet 5L (PCL)"            \
        -q - -c quit

How Can I Print Man Pages with Underlines
-----------------------------------------

     By the past, when I printed a man page with a2ps, it used
     underlines, but now it uses italics.  I want underlines back!

Use a2ps --pro=ul.

Please tell me...
=================

Wondering something?

Is a2ps Y2K compliant?
----------------------

The famous Y2K (Year 2000.) problem...

Yes, a2ps is Y2K compliant... provided that you have either a version more recent than 4.10.3.  The expansions of the following escapes were broken (giving 100 instead of 00): %D, %W, $D, $W.

Nevertheless, please note that if you required a two digit year, expect to have Jan 1st, 00 someday.  You are responsible of the format you want for the date: see Escapes.

Why Have the Options Changed?
-----------------------------

     The options of this a2ps are not the same as in the previous versions.

True.  But the old scheme (up to version 4.6.1) prevented us from offering more options.  We had to drop it, and to fully redesign the options handling.

Since that profound change, we try to change as little as possible between versions.  Nevertheless, as the time passes, we discover that some never used options should be renamed, or used for something else. In these cases, compatibility code is left for a long time.

Anywhere you put options but the command line (e.g., in a2ps configuration files or in shell scripts), avoid using short options, since short options are much more likely to be changed (there are not so many, so it is a precious resource).  Since there are as many long options as one wants, we can leave compatibility code with the long options.

Why not having used yacc and such
---------------------------------

There are several reasons why we decided not to use grammars to parse the files.  Firstly it would have made the design of the style sheets much more tricky, and today a2ps would know only 4 or 5 languages.

Secondly, it limits the number of persons who could build a style sheet.

Thirdly, we did not feel the need for such a powerful tool: handling the keywords and the sequences is just what the users expect.

Fourthly, any extension of a2ps would have required to recompile.

And last but not least, using a parser requires that the sources are syntactic bug free, which is too strong a requirement.

Nevertheless, PreScript gives the possibility to have on the one hand a syntactic parser which would produce PreScript code, and on the other hand, a2ps, which would make it PostScript.  This schema seems to us a good compromise.  If it is still not enough for you, you can use the library.

Why do you not use mozilla
--------------------------

To print with netscape (and other gecko browser as mozilla), we use remote commands (http://home.netscape.com/newsref/std/x-remote.html).

But in mozilla, the remote command saveas() does not exist. And we cannot save open file as postscript file.

Glossary
********

This section settles some terms used through out this document, and provides the definitions of some terms you probably want to know about.

Adobe
     Adobe is the firm who designed and owns the PostScript language. The patent that printer manufacturers must pay to Adobe is the main reason why PostScript printers are so expansive.

AFM file
     AFM stands for Adobe Font Metrics.  These files contain everything one needs to know about a font: the width of the characters, the available characters etc.

Charset
Code Set
     Cf. Encoding.

Delegate
     Another filter (application) which a2ps may call to process some files. This feature is especially meant for page description files (see Your Delegations).

DSC
Document Structuring Conventions
     Because PostScript is a language, any file describing a document can have an arbitrary complexity.  To ease the post-processing of PostScript files, the document should follow some conventions.  Basically there are two kinds of conventions to follow:

     Page Independence
          Special comments state where the pages begin and end.  With these comments (and the fact that the code describing a page starts and ends somewhere, which is absolutely not necessary in PostScript), very simple programs (such as psnup, psselect etc.) can post process PostScript files.

     Requirements
          Special features may be needed to run correctly the file.  Some comments specify what services are expected from the printer (e.g., fonts, duplex printing, color etc.), and other what features are provided by the file itself (e.g., fonts, procsets etc.), so that a print manager can decide that a file cannot be printed on that printer, or that it is possible if the file is slightly modified (e.g., adding a required font not known by the printer) etc.

     The DSC are edited by Adobe.  A document which respects them is said to be DSC conformant.

     a2ps follows all the DSC.

Duplex
DuplexTumble
DuplexNoTumble
     To print Duplex is to print double-sided.  There are two ways to print Duplex depending whether the second face is printed upside-down or not:

     DuplexTumble
          DuplexTumble is suitable when (if it were to be bound) the document would be bound along the short edge (for instance when you are printing booklets).

     DuplexNoTumble
          DuplexNoTumble corresponds to binding along the long edge of the medium. A typical case is when printing one-up.

Encoding
     Association of human readable characters, and computers' internal numbered representation.  In other words, they are the alphabets, which are different according to your country/mother tongue.  E.g.: ASCII, Latin 1, corresponding to Western Europe etc.

     To know more about encodings, see What is an Encoding.

Ghostscript

gs
     Ghostscript (http://www.cs.wisc.edu/~ghost/index.html), gs for short, is a full PostScript interpreter running under many various systems (Unices, MS-DOS, Mac etc.).  It comes with a large set of output formats allowing many different applications:

     Displaying
          It can be used either to view PostScript files (in general thanks to a graphic interface such as Ghostview or gv ...).

     Converting
          To may useful languages/formats: PDF, rewriting in portable PostScript or Encapsulated PS etc.

     Translating
          to a printer dedicated language, e.g., PCL.  In particular, thanks to ghostscript, you may print PostScript files on non PostScript printers.

Face
     A virtual style given to some text.  For instance, Keyword, Comment are faces.

Headings
     Everything that goes around the page and is not part of the text body. Typically the title, footer etc.

Key
     Many objects used in a2ps, such as encodings, have both a key and a name. The word name is used for a symbol, a label, which is only meant to be nice to read by a human.  For instance ISO Latin 1 is a name. a2ps never uses a name, but the key.

     A key is the identifier of a unique object.  This is information that a2ps processes, hence, whenever you need to specify an object to a2ps, use the key, not its name.  For instance latin1 is the unique identifier of the ISO Latin 1 encoding.

Logical page
     Cf. Virtual page.

lhs
left hand side
     See P-rule.

Medium
     Official name (by Adobe) given to the output physical support.  In other words, it means the description of a sheet, e.g., A4, Letter etc.

Name
     See Key.

Page
     A single side of a sheet.

Page Description Language
     A language that describes some text (which may be enriched with pointers, pictures etc.) and its layout.  HTML, PostScript, LaTeX, roff and others are such languages.  A file written in those languages is not made to be read as is by a human, but to be transformed (or compiled) into a readable form.

PCL
     FIXME:

PFA file
     PostScript Font in ASCII format.  This file can be directly down loaded to provide support for another font.

PFB file
     PostScript Font in Binary format.  In PFA files there are long sequences of hexadecimal digits.  Here these digits are represented by their value, hence compressing 2 characters in a PFA into 1 in the PFB.  This is the only advantage since a PFB file cannot be directly sent to printer: it must first be decompressed (hence turned into a PFA file) before being used.

PostScript
     PostScript is a page description language designed for Raster output devices.  It is even more powerful than that: unlike to HTML, or roff, but as TeX and LaTeX, it is truly a programming language which main purpose is to draw (on sheets). Most programs are a list of instructions that describes lines, shades of gray, or text to draw on a page.  This is the language that most printers understand.

     Note that the fact that PostScript is a programming language is responsible of both its success and its failure.  It is a big win for the PostScript programmer who can easily implement a lot of nice visual effects.  It is a big loss because the page descriptions can have an arbitrary complexity, hence rendering can be really slow (remember the first Laser you had, or even Ghostscript.  PDF has been invented by Adobe to remedy these problems).

     PostScript is a trademark of Adobe Systems Incorporated.

PPD file
PostScript Printer Description file
     These files report everything one needs to know about a printer: the known fonts, the patches that should be down loaded, the available memory, the trays, the way to ask it duplex printing, the supported media, etc.

     PostScript has pretended to be a device independent page description language, and the PPD files are here to prove that device independence was a failure.

ProcSet
     Set of (PostScript) procedures.

Prologue
     PostScript being a language, a typical PostScript program (i.e. a typical PostScript file) consists of two parts.  The first part is composed of resources, such as fonts, procsets, etc. and the second part of calls to these procedures.  The first part is called the prologue, and the second, the script.

P-rule
     Pretty printing rule.  It is composed of a left-hand side, (lhs for short), and a right-hand side, (rhs).  The lhs describes when the rule is triggered (i.e., the pattern of text to match), and the rhs specifies the pretty printed output. See P-Rules, for more semantical details, and see Syntax for the P-Rules, for implementation.

psutils
     The psutils (http://www.dcs.ed.ac.uk/home/ajcd/psutils/index.html) is a set of tools for PostScript post processing written by Angus Duggan (http://www.dcs.ed.ac.uk/home/ajcd/).  They let you resize the frame into which the page is drawn, reorder or select pages, put several pages onto a single sheet, etc.  To allow the psutils to run correctly, the PostScript files must be DSC conformant, and the bad news is that many PostScript drivers produce files which are not.  For some common cases (e.g., Micro$oft tools), Angus Duggan included in the package some tools (named fix...ps) to fix typical problems.  fixps is a collection of recipes on when to run what fix tool.

Raster Image Processor
RIP
     The hardware and/or software that translates data from a high-level language (e.g., PostScript) into dots or pixels in a printer or image setter.

Raster Output Device
     Behind these words is hidden the general class of devices which have Pixels that can be addressed individually: Laser, Ink or Dot printers, but also regular screens etc.  It is typically opposed to the class of devices which plot, i.e., have a pen that they move on the paper.

rhs
right hand side
     See P-rule.

RIP
     See Raster Image Processor.

Script
     See Prologue.

Sheet
     The physical support of the printing: it may support one or two pages, depending on your printing options.

Style sheet
     Set of rules used by a2ps to give a face to the strings of a file.  In a2ps, each programming language which is supported is defined via one style-sheet.

Tumble
     See Duplex.

Virtual page
     Area on a physical page in which a2ps draws the content of a file. There may be several virtual pages on a physical page. (``virtual page'' is the name recommended by Adobe).

Genesis
*******

Here are some words on a2ps and its history.

History
=======

The initial version was a shell program written by Evan Kirshenbaum.  It was very slow and contained many bugs.

A new version was written in C by Miguel Santana to improve execution speed and portability.  Many new features and improvements have been added since this first version. Many contributions (changes, fixes, ideas) were done by a2ps users in order to improve it.

From the latest version from Miguel Santana (4.3), Emmanuel Briot implemented bold faces for keywords in Ada, C and C++.

From that version, Akim Demaille generalized the pretty-printing capabilities, implemented more languages support, and other features.

Thanks
======

Patrick Andries, from Alis Technologies inc. (http://www.alis.com/) and Roman Czyborra (see his home page (http://czyborra.com/)), provided us with important information on encodings.  We strongly recommend that you go and read these pages: there is a lot to learn.

Juliusz Chroboczek worked a lot on the integration of the products of Ogonkify (such as Latin 2 etc. fonts) in a2ps.  Without his help, and the time is devoted to both a2ps and ogonkify, many non west-European people would still be unable to print easily texts written in their mother tongue.

Denis Girou brought a constant and valuable support through out the genesis of pretty-printing a2ps.  His comments on both the program and the documentation are the origin of many pleasant features (such as --prologue).

Alexander Mai provided us with invaluable help in the development.  He spotted several times subtle bugs in a2ps and the contributions, he keeps a vigilant eye on portability issues, he checks and improves the style sheets, and he maintains a port of a2ps for OS/2.

Graham Jenkins, with an extraordinary regularity, tortures a2ps on weird systems that nobody ever heard of :).  Graham is usually the ultimate test: if he says I can release a2ps, I rest reassured that, yes, this time it will compile!  If a2ps works today on your system, you should thank Graham too!

Of course this list is not up to date, and never will.  We would like to thank everybody that helped us, talked to us, and even criticized us with the intention to help us to improve a2ps.  Of course it doesn't sound right, yes it sounds a little childish, but we can tell you: we would never have the strength and the faith of building and maintaining a2ps without the support of all these guys.

While a2ps is finally just a couple of bits on a hard disk, to us it is an adventure we live with other humans, and, boy, that's a darn good pleasure!

Translators
===========

Some people worked on the translation of a2ps:

          [file translators.texi not included]

Copying
*******

The subroutines and source code in the a2ps package are "free"; this means that everyone is free to use them and free to redistribute them on a free basis.  The a2ps-related programs are not in the public domain; they are copyrighted and there are restrictions on their distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of these programs that they might get from you.

Specifically, we want to make sure that you have the right to give away copies of the programs that relate to a2ps, that you receive source code or else can get it if you want it, that you can change these programs or use pieces of them in new free programs, and that you know you can do these things.

To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights.  For example, if you distribute copies of the a2ps-related code, you must give the recipients all the rights that you have.  You must make sure that they, too, receive or can get the source code.  And you must tell them their rights.

Also, for our own protection, we must make certain that everyone finds out that there is no warranty for the programs that relate to a2ps.  If these programs are modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation.

The precise conditions of the licenses for the programs currently being distributed that relate to a2ps are found in the General Public Licenses that accompany them.