path: root/doc/a2ps.texi

\input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename a2ps.info
@settitle General Purpose PostScript Generating Utility
@c @setchapternewpage odd
@c %**end of header

@c A few words about this document:
@c - use @pack{} when the name a2ps is needed, so that the correct
@c   face is used
@c - do not use macros in footnote: because of a bug in Texinfo 3.11
@c   the TeX result is erroneous.
@c - I tried to avoid the name ASCII to PostScript, because a2ps is no
@c   longer limited by an ASCII input.  "any" seems good, since it
@c   talks about the delegations too.

@include version.texi
@set PACKAGE a2ps
@set WWWHOME http://www.gnu.org/software/a2ps/

@c short cut for PACKAGE in @code.  @code in Info looks like this:
@c `a2ps'.  Avoid those quotes.
@iftex
@macro pack
@code{@value{PACKAGE}}
@end macro
@end iftex
@ifnottex
@macro pack
@value{PACKAGE}
@end macro
@end ifnottex

@c better looking url references
@iftex
@macro href{link, name}
\name\@footnote{@url{\link\}}
@end macro
@end iftex
@ifnottex
@macro href{link, name}
@uref{\link\,\name\}
@end macro
@end ifnottex

@c TeX variants
@macro LaTeX
La@TeX{}
@end macro

@macro PreTeX
Pre@TeX{}
@end macro

@macro TeXScript
@TeX{}Script
@end macro

@dircategory Printing Tools
@direntry
* a2ps: (a2ps).                    PostScript Generating Utility
* PreScript: (a2ps) PreScript.     Input language for a2ps
* card: (a2ps) card.               Print Reference Cards
* fixps: (a2ps) fixps.             Fixing Some Ill Designed PostScript Files
* fixnt: (a2ps) fixnt.             Fixing Microsoft NT PostScript Files
* pdiff: (a2ps) pdiff.             Produce Pretty Comparison of Files
* psmandup: (a2ps) psmandup.       Printing Duplex on Simplex Printers
* psset: (a2ps) psset.             Inserting calls to setpagedevice
@end direntry

@ifinfo
This document describes GNU @pack{} @value{VERSION}, a converter from
various formats, included text, to PostScript converter, with
pretty-printing abilities.

Copyright @copyright{} 1988-1993 Miguel Santana
Copyright @copyright{} 1995-2000 Akim Demaille, Miguel Santana
Copyright @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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
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.
@end ifinfo

@titlepage
@title GNU a2ps, version @value{VERSION}
@subtitle General Purpose PostScript Generating Utility
@subtitle Edition @value{EDITION}
@author Akim Demaille
@author Miguel Santana

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1988-1993 Miguel Santana

Copyright @copyright{} 1995-2000 Akim Demaille, Miguel Santana
Copyright @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 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 Free Software Foundation.
@end titlepage

@c In vr is put the options
@c @syncodeindex fn cp
@c @synindex pg cp

@ifinfo
@node Top
@top a2ps

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

This is Edition @value{VERSION} of the @pack{} documentation.

@menu
* Introduction::                Foreword
* User Guide::                  Beginner should start here
* Invoking a2ps::               The command line options
* Configuration Files::         Tuning your a2ps
* Library Files::               Dynamic extension of a2ps
* Encodings::                   Supporting various charsets
* Pretty Printing::             Support for source files
* PostScript::                  PostScript specific informations
* Contributions::               Tools around a2ps
* FAQ::                         Frequently Answered Questions
* Glossary::                    Small Dictionary
* Genesis::                     History of a2ps
* Copying::                     Your rights and ours
* Concept Index::               Most words used in here

@detailmenu --- The Detailed Node Listing ---

Introduction

* Description::                 What a2ps is
* Reporting Bugs::              What to do when you face problems
* a2ps Mailing Lists::           Getting news about a2ps
* Helping the Development::     How to contribute

User's Guide

* Purpose::                     What a2ps is made for
* How to print::                The basis
* Important parameters::        What needs to be set
* Localizing::                  How to have a2ps speaking your language
* Interfacing::                 Using a2ps from common programs

How to print

* Basics for Printing::         Printing text files
* Special Printers::            Some useful fake printers
* Using Delegations::           Printing special files (PS, DVI etc.)
* Printing Duplex::             Doing Fancy Things
* Checking the Defaults::       Is it set the way you want?

Interfacing with Other Programs

* Interfacing With a Mailer::   Printing Mails or News
* Netscape::                    Interfacing with Netscape

Invoking @pack{}

* Options::                     Command line options
* Escapes::                     Strings ready to use in the headers

Command line options

* Tasks Options::               Exclusive options
* Global Options::              Settings involving the whole process
* Sheet Options::               Specify the layout on the sheet
* Page Options::                Specify the virtual pages
* Headings Options::            Specify the headers you want
* Input Options::               How to process the input files
* Pretty Print Options::        Source files support
* Output Options::              What should be done of the output
* PostScript Options::          PostScript specific options

Escapes

* Use of Escapes::              Where they are used
* Structure of the Escapes::    Their syntax
* Available Escapes::           Detailed list

Configuration Files

* Including Configuration Files::  Isolating site specific values
* Your Library Path::           Setting the files search path
* Your Default Options::        Default state of a2ps
* Your Media::                  Sheets dimensions
* Your Printers::               How to access the printers
* Your Shortcuts::              Your very own command line options
* Your PostScript magic number::  Handling very old printers
* Your Page Labels::            Page names as in @code{Ghostview}
* Your Variables::              Short cut for long sequences
* Your Delegations::            Delegating some files to other filters
* Your Internal Details::       Details you might want to tune

Your Variables

* Defining Variables::          Syntax and conventions
* Predefined Variables::        Builtin variables

Your Delegations

* Defining a Delegation::       Syntax of the definitions of the delegations
* Guide Line for Delegations::  What should be respected
* Predefined Delegations::      Making the best use of these delegations

Library Files

* Documentation Format::        Special tags to write a documentation
* Map Files::                   Their general shape and rationale
* Font Files::                  Using other fonts
* Style Sheet Files::           Defining pretty printing rules

Font Files

* Fonts Map File::              Mapping a font name to a file name
* Fonts Description Files::     Needed files to use a Font
* Adding More Font Support::    Using even more Fonts

Encodings

* What is an Encoding::         The concept of encoding explained
* Encoding Files::              How a2ps handles the encodings

Encoding Files

* Encoding Map File::           Mapping an encoding name to a file name
* Encoding Description Files::  Specifying an encoding
* Some Encodings::              Classical or standard encodings

Pretty Printing

* Syntactic limits::            What can't be done
* Known Style Sheets::          Some supported languages
* Type Setting Style Sheets::   a2ps as a tiny word processor
* Faces::                       Encoding the look of pieces of text
* Style sheets semantics::      What is to be defined
* Style Sheets Implementation::  How they should be defined
* A tutorial on style sheets::  Step by step example

Type Setting Style Sheets

* Symbol::                      Access to the glyphs of the Symbol font
* PreScript::                   Typesetting in an a2ps like syntax
* PreTeX::                      Typesetting in a LaTeX like syntax
* TeXScript::                   Typesetting in a mixture of both

PreScript

* Syntax::                      Lexical specifications
* PreScript Commands::
* PreScript examples::

@PreTeX

* Special characters::
* PreTeX Commands::
* Differences with LaTeX::

Style Sheets Semantics

* Name and key::                Both names of a style sheet
* Comments::                    Author name, version etc.
* Alphabets::                   What words are legal
* Case sensitivity::            Is BEGIN different of begin
* P-Rules::                     Pretty Printing Rules
* Sequences::                   Strings, comments etc.
* Optional entries::            Second level of pretty printing

Style Sheets Implementation

* A Bit of Syntax::             Lexical rules of the ssh language
* Style Sheet Header::          Declaration of a style
* Syntax of the Words::         Classes of the Characters
* Inheriting::                  Extending existing style sheets
* Syntax for the P-Rules::      Atomic Pretty Printing rules
* Declaring keywords and operators::  Special Classes of Identifiers
* Declaring sequences::         Bordered Lexical Entities
* Checking a Style Sheet::      Ask a2ps to Check the Sheet

A Tutorial on Style Sheets

* Example and syntax::          ChangeLog files
* Implementation::              Implementation of chlog.ssh
* The Entry in sheets.map::     Getting automatic style selection
* More Sophisticated Rules::    Complex regular expressions
* Distributed Style Sheets::    Additional Constraints

PostScript

* Good and Bad PostScript::     How to lose, how to win
* Page Device Options::         Accessing some printers' features
* Statusdict Options::          Some other features
* Colors in PostScript::        Specifying a color or a gray
* a2ps PostScript Files::       Convention for PostScript library files
* Designing PostScript Prologues::  Make it look like what you want

Designing PostScript Prologues

* Definition of the faces::     What goes in a characters style
* Prologue File Format::        Including documentation
* A prologue example::          A step by step example

Contributions

* card::                        Printing Reference Cards
* fixps::                       Fixing Some Ill Designed PostScript Files
* fixnt::                       Fixing Microsoft NT PostScript Files
* pdiff::                       Produce Pretty Comparison of Files
* psmandup::                    Printing Duplex on Simplex Printers
* psset::                       Inserting calls to setpagedevice

@code{card}

* Invoking card::               Command Line Interface
* Caution when Using card::     card runs commands

@code{fixps}

* Invoking fixps::              Command Line Interface

@code{fixnt}

* Invoking fixnt::              Command Line Interface

@code{pdiff}

* Invoking pdiff::              Command Line Interface

@code{psmandup}

* Invoking psmandup::           Command Line Interface

@code{psset}

* Invoking psset::              Command Line Interface

Frequently asked questions

* Why Does ...?::               Questions on Error
* How Can I ...?::              a2ps' How-To
* Please tell me...::           Existential Questions on a2ps

Why Does...?

* It Prints Nothing::           The printer issues nothing
* It Prints in Simplex::        While I asked for Duplex
* It Prints in Duplex::         While I asked for Simplex
* It Does Not Fit on the Paper::  Some parts are missing
* It Prints Junk::              Random characters
* It Says my File is Binary::   And refuses to print it
* It Refuses to Change the Font Size::

How Can I ...?

* Leave Room for Binding::      Specifying Margins
* Print stdin::                 Using a2ps in a pipe chain
* Change the Fonts::            Tired of Courier?
* The Old Option -b?::          Printing in Bold
* Pass Options to lpr::         Disable the banner
* Non PostScript Printers::     Using GhostScript
* Man Pages with Underlines::   Now it Prints With Italics

Please tell me...

* Is a2ps Y2K compliant?::      Printing dates in short format
* The Options Have Changed::    Respect The Users
* Why not using yacc::          Why Using Style Sheets

Genesis

* History::                     Where does it come from
* Thanks::                      People who really helped
* Translators::                 People who brought support of your tongue

@end detailmenu
@end menu

@end ifinfo

@node    Introduction
@chapter Introduction
@c Now, that's what I call humor :)
@cindex First Page
This document describes GNU @pack{} version @value{VERSION}.  The latest
versions may be found on the @href{@value{WWWHOME},@pack{} home page}.
We plan to update the @href{http://www.gnu.org/software/a2ps/, GNU
@pack{} home page} 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, @strong{not} because @pack{} is
difficult to use.  @xref{Glossary}, for technical words or even general
information.

Please, send us emailcards @code{:)}. Whatever the comment is, or if you
just like @pack{}, write to @email{Miguel.Santana@@st.com, Miguel
Santana} and @email{akim@@freefriends.org, Akim Demaille}.  But
@emph{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.  @xref{a2ps Mailing Lists}, for information on the
mailing lists.


@menu
* Description::                 What a2ps is
* Reporting Bugs::              What to do when you face problems
* a2ps Mailing Lists::           Getting news about a2ps
* Helping the Development::     How to contribute
@end menu

@node Description
@section Description
@pack{} 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 @pack{} is kind of bootstrapped: its sources are frequently
printed with @pack{} @code{:)}.

While at the origin its names was derived from ``ASCII to PostScript'',
today we like to think of it as ``Any to PostScript''.  Indeed, @pack{}
supports @dfn{delegations}, i.e., you can safely use @pack{} to print DVI,
PostScript, LaTeX, JPEG etc., even compressed.

A short list of features of @pack{} might look like this:
@itemize @minus
@item
Customizable through various configuration files (@pxref{Configuration Files})

@item
Powerful escapes to define the headers, table of contents etc. the way you want
(@pxref{Escapes});

@item
Variables to push even further the customizability in a comfortable
manner (@pxref{Your Variables});

@item
Open approach of encodings (@pxref{Encodings});

@item
Excellent support of the Latin 2, 3, 4, 5 and 6 encodings, thanks to
@code{Ogonkify} (@pxref{top,,Overview,ogonkify,Ogonkify manual}),
written by Juliusz Chroboczek.

@item
Fully customizable output style: fonts, background and foreground
colors, line numbering style etc. (@pxref{Designing PostScript
Prologues}).

@item
Possibility to delegate the processing of some files to other filters
(@pxref{Your Delegations}).

@item
Many contributions, e.g., pretty-print diffs, print reference cards of
programs, sanitize broken PostScript files, print Duplex on Simplex
printers etc. (@pxref{Contributions}).

@item
And finally, the ability to pretty-print sources written in quite a
few various languages (@pxref{Pretty Printing}).
@end itemize


@node Reporting Bugs
@section Reporting Bugs
@cindex Bug
We try hard to make @pack{} portable on any Unix platform, and bug free.
But sometimes there can still be bad surprises, even after having
compiled and checked @pack{} 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
(@pxref{FAQ}), then on the page @href{@value{WWWHOME}/bugs.html,Known
@pack{} Bugs} if the issue has not been addressed yet.  If it is not the
case, but it appears that the version of @pack{} you have is old,
consider upgrading.

If the problem persists, send us a mail (@email{bug-a2ps@@gnu.org})
which subject is @samp{a2ps @var{version}: @var{short-description}} and
which content mentions the name of your machine and OS, the version of
@pack{}, 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
@code{make} when it fails etc.).

Be sure to get a quick answer.

@node a2ps Mailing Lists
@section @pack{} Mailing Lists

There are several mailing lists related to @pack{}:

@table @email
@item 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.

@item bug-a2ps@@gnu.org
Any bug report should be sent to this address.  Please, be sure to state
the version of @pack{} 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.

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

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

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

Be sure @emph{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.


@node Helping the Development
@section Helping the Development

If you like @pack{} and if you feel like helping, there are several things
you can do.

@table @emph
@item 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 @strong{need} beta-testers!  To be one is fairly simple: subscribe
to the mailing-list where the betas are announced and distributed.

@item Translation
The interface of @pack{} is under @code{GNU gettext} which means that all
the messages can be translated, without having to look at the code of
@pack{}: you don't need to be a programmer at all.  All the details are
available on @href{@value{WWWHOME}/po/, the a2ps translation page}.

@item Style Sheets
Since @pack{} 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! (@pxref{Pretty
Printing} for details.)

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

@item Fonts
There are still some characters missing in Ogonkify. See
@href{http://www.dcs.ed.ac.uk/home/jec/ogonkify/missing.html, the list
of missing characters} and
@href{http://www.dcs.ed.ac.uk/home/jec/ogonkify/, the Ogonkify home
page} for details.

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

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

@item 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.
@end table


@c #     #                          ###          #####
@c #     #   ####   ######  #####   ###   ####  #     #  #    #   #   #####
@c #     #  #       #       #    #   #   #      #        #    #   #   #    #
@c #     #   ####   #####   #    #  #     ####  #  ####  #    #   #   #    #
@c #     #       #  #       #####             # #     #  #    #   #   #    #
@c #     #  #    #  #       #   #        #    # #     #  #    #   #   #    #
@c  #####    ####   ######  #    #        ####   #####    ####    #   #####

@node User Guide
@chapter User's Guide

This chapter is devoted to people who don't know @pack{} yet: we try to
give a soft and smooth introduction to the most useful features.  For a
reference manual, see @ref{Invoking a2ps}.  For the definition of some
words, see @ref{Glossary}, for questions you have, see @ref{FAQ}.

@menu
* Purpose::                     What a2ps is made for
* How to print::                The basis
* Important parameters::        What needs to be set
* Localizing::                  How to have a2ps speaking your language
* Interfacing::                 Using a2ps from common programs
@end menu

@node Purpose
@section Purpose
@pack{} 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.

@node How to print
@section How to print
To print a file @file{doc.txt}, just give it to @pack{}: the default
setting should be the one you'd like:
@example
@cartouche
gargantua ~ $ a2ps doc.txt
[doc.txt (plain): 9 pages on 5 sheets]
[Total: 9 pages on 5 sheets] sent to the default printer
@end cartouche
@end example

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


@menu
* Basics for Printing::         Printing text files
* Special Printers::            Some useful fake printers
* Using Delegations::           Printing special files (PS, DVI etc.)
* Printing Duplex::             Doing Fancy Things
* Checking the Defaults::       Is it set the way you want?
@end menu

@node Basics for Printing
@subsection Basics for Printing
Say you want to print the C file @file{bar.c}, and its header
@file{foo.h}, on 4 virtual pages, and save it into the file
@file{foobar.ps}.  Just hit:
@example
@cartouche
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'
@end cartouche
@end example

The option @samp{-4} tells @pack{} to make four virtual pages: two rows by
two columns.  The option @samp{-o foobar.ps} (which is the short version of
@samp{--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 @file{foobar.ps} to a printer, you'll discover that the
keywords were highlighted, that the strings and comments have a
different face.  Indeed, @pack{} is a @dfn{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: @file{foo.h} is only one virtual page long, and
@file{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:
@example
@cartouche
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'
@end cartouche
@end example

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

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

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


@node Special Printers
@subsection Special Printers
@cindex @code{display}
@cindex @code{void}
@cindex @code{file}
There are three special printers pre-defined.

The first one, @code{void}, sends the output to the trash.
Its main use is to see how many pages would have been used.
@example
@cartouche
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'
@end cartouche
@end example

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

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

@node Using Delegations
@subsection Using Delegations

@pack{} can decide that @pack{} 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, @emph{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:
@example
@cartouche
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
@end cartouche
@end example

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

Suppose now that you want to display a Texinfo file. Then, provided you
have all the programs @pack{} needs, just hit
@example
@cartouche
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'
@end cartouche
@end example

Once the read documentation, you know you want to print just pages
10 to 20, plus the cover.  Just hit:
@example
@cartouche
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
@end cartouche
@end example

A final word: compressed files can be treated in the very same way:
@example
@cartouche
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
@end cartouche
@end example

You should be aware that:
@itemize @minus
@item
the option @samp{-Z} enables the delegations if they are not (see
@samp{--list=defaults} for your settings);

@item
the set of delegations is customizable, to know the delegations your
@pack{} knows, consult @samp{a2ps --list=delegations}.
@end itemize

@node Printing Duplex
@subsection Printing Duplex

If you still want to save more paper, and you are amongst the set of
happy users of Duplex printers, @pack{} will also be able to help you
(@xref{Glossary}, for definitions).  The option to specify Duplex
printing is @samp{--sides=@var{mode}} (@pxref{PostScript Options}).

Here is how to print the documentation in Duplex and send it to the
Duplex printer @samp{margot}:
@example
@cartouche
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'
@end cartouche
@end example
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 @code{psbook}, yet another PsUtil from Angus Duggan.  But there
is a user option which encapsulates the magic sequence of options:
@samp{book}.  Therefore, just run
@example
@cartouche
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'
@end cartouche
@end example

@noindent
and @i{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.


@node Checking the Defaults
@subsection Checking the Defaults

If @pack{} 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:
@example
@cartouche
~ % 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
@emph{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
@end cartouche
@end example

Remember that the on-line help is always available.  Moreover, if your
screen is small, you may @emph{pipe} it into @code{more}.  Just trust
this:
@example
a2ps --help | more
@end example

@node Important parameters
@section Important parameters
Many things are parameterizable in @pack{}, but two things are just
essential to make sure everything goes right:
@table @strong
@item The paper
Make sure that the paper @pack{} uses is the same as your printer
(@xref{Sheet Options}, option @samp{--medium}).

@item The encoding
Make sure that the @emph{encoding} @pack{} uses is the same as the
standard alphabet in your country (@xref{Input Options}, option
@samp{--encoding}).
@end table

Both values may be checked with @samp{a2ps --list=defaults}.

@node Localizing
@section Localizing
@pack{} provides some Native Language Support, that is speaking your
mother tongue.  It uses three special features for non-English
languages:
@table @emph
@item the tongue
i.e., the language used by the interface,

@item the date
i.e., the format and the words used in the language to specify a date.
@end table

To enable these features, properly set your environment variable
@code{LANG} (see the documentation of your system, for instance
@samp{man locale}, @samp{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 @code{awk} and such.

So if you just want messages and time format to be localized, then
define:
@example
set LC_MESSAGES=fr ; export LC_MESSAGES
set LC_TIME=fr     ; export LC_TIME
@end example


@node Interfacing
@section Interfacing with Other Programs
Here are some tips on how to use @pack{} with other programs.

@menu
* Interfacing With a Mailer::   Printing Mails or News
* Netscape::                    Interfacing with Netscape
@end menu

@node  Interfacing With a Mailer
@subsection Interfacing With a Mailer

When you print from a mailer (or a news reader), your mailer calls a tool,
say @pack{} on a part of the whole mailbox.  This makes it difficult for
@pack{} to guess that the file is of the type @samp{mail}.  Therefore, for
better results, make sure to tell @pack{} the files are mails.  The user
option @samp{mail} (or @samp{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:
@table @code
@item elm
@cindex @code{elm}
Once you are in elm, hit @kbd{o} to enter in the options edition menu,
hit @kbd{p} to edit the printer command, and enter @samp{a2ps -=mail
%s -d}.  The option @samp{-d} means to print on the default printer.

@item pine
@cindex @code{pine}
@email{jan@@chrillesen.dk, Jan Chrillesen} suggests us how to use @pack{}
with the Pine mail-reader.  Add the following to @file{.pinerc}
(of course you can put it in @file{pine.conf} as well):
@example
# Your printer selection
printer=a2ps -=mail -d

# Special print command
personal-print-command=a2ps -=mail -d
@end example

@end table



@node Netscape
@subsection Netscape

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

@noindent
Not too hard, isn't it?

Nevertheless, this setting suppose your world is OK, your @code{file(1)}
detects correctly PostScript files, and your @pack{} is configured to
delegate.  In case one one these conditions is not met, use:
@example
a2ps -ZEps
@end example

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


@c  ###
@c   #   #    #  #    #   ####    ####     ##   #####  #   ####   #    #
@c   #   ##   #  #    #  #    #  #    #   #  #    #    #  #    #  ##   #
@c   #   # #  #  #    #  #    #  #       #    #   #    #  #    #  # #  #
@c   #   #  # #  #    #  #    #  #       ######   #    #  #    #  #  # #
@c   #   #   ##   #  #   #    #  #    #  #    #   #    #  #    #  #   ##
@c  ###  #    #    ##     ####    ####   #    #   #    #   ####   #    #

@node Invoking a2ps
@chapter Invoking @pack{}

Calling @pack{} is fairly simple:
@example
a2ps @var{Options...} @var{Files...}
@end example

If no @var{Files...} are given, @pack{} prints its standard input.  If
@samp{-} appears in the @var{Files...}, it designates the standard input
too.

@menu
* Options::                     Command line options
* Escapes::                     Strings ready to use in the headers
@end menu

@node Options
@section Command line options
@cindex Command line options
@cindex Options

To read the options and arguments that you give, @pack{} uses GNU
@code{getopt}, hence:

@itemize @minus
@item
the options (short with arguments or long) must be separated by spaces.

@item
the order between options and files does not matter: @samp{a2ps -4m
main.c} and @samp{a2ps main.c -4m} are identical.

@item
the order between options @strong{does matter}, especially between
options that influence the same parameters.  For instance @samp{a2ps -1
-l132} is not the same as @samp{a2ps -l132 -1} (the latter being
equivalent to @samp{a2ps -1}).

@item
short options may be grouped together: @samp{a2ps -4mg main.c -P printer}

@item
when there are no ambiguities, long options can be abbreviated, e.g.,
@samp{--pro} will be understood as @samp{--prologue},

@item
@samp{--} ends the options.  Anything behind @samp{--} is considered to
be a file: @samp{a2ps -- -2} prints the file @file{-2}@footnote{A
classical Unix trick to make the difference between the option
@samp{-2}, and the file @file{-2} is to type @file{./-2}.}.

@end itemize

Here after a @var{boolean} is considered as true (i.e. setting the
option on), if @var{boolean} is @samp{yes}, or @samp{1}; as false if it
equals @samp{no} or @samp{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.

@menu
* Tasks Options::               Exclusive options
* Global Options::              Settings involving the whole process
* Sheet Options::               Specify the layout on the sheet
* Page Options::                Specify the virtual pages
* Headings Options::            Specify the headers you want
* Input Options::               How to process the input files
* Pretty Print Options::        Source files support
* Output Options::              What should be done of the output
* PostScript Options::          PostScript specific options
@end menu


@node Tasks Options
@subsection Tasks Options

Task options specify the task @pack{} will perform.  It will not print,
it executes the task and exits successfully.

@defvr {Option} -@b{-}version
print version and exit successfully.
@end defvr

@defvr {Option} -@b{-}help
Print a short help, and exit successfully.
@end defvr

@defvr {Option} -@b{-}copyright
Display Copyright and copying conditions, and exit successfully.
@end defvr

@defvr {Option}  -@b{-}guess
Act like @code{file} does: display the (key of the) type of the
@var{Files}.

For instance, on a @code{C} file, you expect it to answer @samp{c}, and
upon a PostScript file, @samp{ps}.

This can be very useful on broken systems to understand why a file is
printed with a bad style sheet (@pxref{Style Sheet Files}).
@end defvr

@defvr {Option}  -@b{-}which
Look in the library for the files which names are given as arguments.
For instance:

@cartouche
@example
~ % a2ps --which bw.pro gray.pro
/usr/local/share/a2ps/ps/bw.pro
/usr/local/share/a2ps/ps/gray.pro
@end example
@end cartouche

@noindent
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
@pack{}.
@end defvr

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

@cartouche
@example
~ % a2ps --glob 'g*.pro'
/usr/local/share/a2ps/ps/gray.pro
/usr/local/share/a2ps/ps/gray2.pro
@end example
@end cartouche
@end defvr

@defvr {Option}  -@b{-}list=@var{topic}
Display a report on @pack{}' status with respect to @var{topic}, and
exit successfully.
@var{topic} can be any non-ambiguous abbreviation of:
@table @samp
@item defaults
@itemx options
Give an extensive report on @pack{} configuration and installation.

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

@item delegations
Detailed list of the delegations.  @xref{Your Delegations}.

@item encodings
Detailed list of known encodings.  @xref{Some Encodings}.

@item media
Detailed list of known media. @xref{Your Media}.

@item prologues
Detailed list of PostScript prologues.  @xref{Designing PostScript Prologues}.

@item printers
Detailed list of printers and named outputs.  @xref{Your Printers}.

@item style-sheets
Detailed list of the known style sheets. @xref{Known Style Sheets}.

@item user-options
Detailed list of the user options. @xref{Your Shortcuts}.

@item variables
Detailed list of the variables.  @xref{Your Variables}.
@end table

There are also options meant for the maintainers only, presented for
sake of completeness.
@table @samp
@item texinfo-style-sheets
@itemx ssh-texi
Detailed list of known style sheets in Texinfo format.  If the
@code{sheet} verbosity is set, report version numbers, requirements and
ancestors.

@item html-style-sheets
@itemx ssh-html
Detailed list of the style sheets in @code{HTML} format.

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

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

@end table
@end defvr


@node Global Options
@subsection Global Options

These options are related to the interface between you and @pack{}.

@defvr {Option} -q
@defvrx {Option} -@b{-}quiet
@defvrx {Option} {-@b{-}silent}
be really quiet
@end defvr

@defvr {Option}  -v[@var{level}]
@defvrx {Option} -@b{-}verbose[=@var{level}]
tell what we are doing.  At
@itemize @minus
@item
@var{level} = 0, report nothing,

@item
@var{level} = 1, @pack{} just prints the total number of pages printed,

@item
@var{level} = 2 (default), it reports it for each file,

@item
above, it gives internal details.
@end itemize
There is also an interface made for the maintainer with finer grained
selection of the verbosity level.  @var{level} is a list of tokens (non
ambiguous abbreviations are valid) separated by either @samp{,} or
@samp{+}.  The tokens may be:
@table @samp
@item configuration
@itemx options
reading the configurations files and the options,

@item encodings
the encodings,

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

@item files
inputs and outputs,

@item fonts
the fonts,

@item escapes
@itemx variables
@itemx meta-sequences
the expansion of escapes and variables,

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

@item pathwalk
@itemx pw
the search for files,

@item ppd
PPD processing,

@item sheets
the style sheets,

@item stats
statistics on some internal data structures,

@item tools
launched programs or shell commands ; triggers the escape @samp{?V} on
(@pxref{Available Escapes}),

@item all
all the messages.
@end table

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


@defvr {Option} -=@var{shortcut}
@defvrx {Option} -@b{-}user-option=@var{shortcut}
use the @var{shortcut} defined by the user. @xref{Your Shortcuts}.
Shortcuts may be freely mixed with regular options and arguments.

There are a few predefined user-options:
@table @samp
@item lp
emulates a line printer, i.e., turn off most `pretty' features.

@item mail
@itemx longmail
preferred options to print a mail or a news.  @samp{longmail} prints more
text on a single sheet.

@item manual
make the job be printed on the manually fed tray.
@end table

@end defvr

@defvr {Option} -@b{-}debug
enable debugging features.  They are:
@itemize @minus
@item
print the overall BoundingBox in PostScript;

@item
down load a PostScript debugger which helps understanding why a
printer may reject a file.
@end itemize
@end defvr

@defvr {Option} -D @var{key}[=@var{value}]
@defvrx {Option} -@b{-}define=@var{key}[=@var{value}]
Without @var{value}, unset the variable @var{key}.  Otherwise, set it to
@var{value}. @xref{Your Variables}, for more details.  Note that
@samp{-Dfoo=} gives @var{foo} an empty value, though @samp{-Dfoo} unsets
foo.
@end defvr


@node  Sheet Options
@subsection Sheet Options

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

@defvr {Option}  -M @var{medium}
@defvrx {Option} -@b{-}medium=@var{medium}
@cindex @code{libpaper}
@cindex @code{paperconf}
use output medium @var{medium}.  See the output of @samp{a2ps
--list=media} for the list of supported media.  Typical values are
@samp{A3}, @samp{A4}, @samp{A5}, @samp{B4}, @samp{B5}, @samp{Letter},
@samp{Legal}.

@samp{A4dj}, @samp{Letterdj} are also defined for Desk Jet owners, since
that printer needs bigger margins.

The special @var{medium} @samp{libpaper} means that you want @pack{} to
ask the library @code{libpaper} for the medium to use.  This choice is
valid only if @code{libpaper} was available when @pack{} was configured.
See the man page of @code{paperconf} for more information.
@end defvr

@defvr {Option}  -r
@defvrx {Option} -@b{-}landscape
print in landscape mode
@end defvr

@defvr {Option}  -R
@defvrx {Option} -@b{-}portrait
print in portrait mode
@end defvr

@defvr {Option} -@b{-}columns=@var{num}
specify the number of columns of virtual pages per physical page.
@end defvr

@defvr {Option} -@b{-}rows=@var{num}
specify the number of rows of virtual pages per physical page.
@end defvr

@defvr {Option} -@b{-}major=@var{direction}
specify whether the virtual pages should be first filled in rows
(@var{direction} = @samp{rows}) or in columns (@var{direction} =
@samp{columns}).
@end defvr

@defvr {Option}  -1
1 x 1 portrait, 80 chars/line, major rows (i.e. alias for @samp{--columns=1 --rows=1 --portrait --chars-per-line=80 --major=rows}).
@end defvr

@defvr {Option}  -2
2 x 1 landscape, 80 chars/line, major rows.
@end defvr

@defvr {Option}  -3
3 x 1 landscape, 80 chars/line, major rows.
@end defvr

@defvr {Option}  -4
2 x 2 portrait, 80 chars/line, major rows.
@end defvr

@defvr {Option} -5
5 x 1 landscape, 80 chars/line, major rows.
@end defvr

@defvr {Option} -6
3 x 2 landscape, 80 chars/line, major rows.
@end defvr

@defvr {Option} -7
7 x 1 landscape, 80 chars/line, major rows.
@end defvr

@defvr {Option} -8
4 x 2 landscape, 80 chars/line, major rows.
@end defvr

@defvr {Option} -9
3 x 3 portrait, 80 chars/line, major rows.
@end defvr

@defvr {Option} -j
@defvrx {Option} -@b{-}borders=@var{boolean}
print borders around virtual pages.
@end defvr

@defvr {Option}  -A @var{mode}
@defvrx {Option} -@b{-}file-align=@var{mode}
Align separate files according to @var{mode}.  This option allows the
printing of more than one file on the same page.  @var{mode} can be any
one of:
@table @asis
@item @samp{virtual}
Each file starts on the next available virtual page (i.e., leave no
empty virtuals).

@item @samp{rank}
Each file starts at the beginning of the next row or column depending on
the @samp{--major} setting.

@item @samp{page}
Each file starts on a new page.

@item @samp{sheet}
Each file starts on a new sheet.  In Simplex mode, this is the same as
@samp{page}, in Duplex mode, files always start on a front side.

@item an integer @var{num}
Each file starts on a page which is a multiple of @var{num} plus 1.  For
instance, for @samp{2}, the files must start on odd pages.
@end table
@end defvr

@defvr {Option} -@b{-}margin[=@var{num}]
Specify the size of the margin (@var{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.
@end defvr

@node Page Options
@subsection Page Options

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

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

@defvr {Option} -@b{-}line-numbers[=@var{number}]
print the line numbers from @var{number} lines to @var{number} lines.
Default is @samp{1}.
@end defvr

@defvr {Option}  -C
Alias for @samp{--line-numbers=5}.
@end defvr

@defvr {Option}  -f @var{size}[@var{unit}]
@defvrx {Option} -@b{-}font-size=@var{size}[@var{unit}]
scale font to @var{size} for body text. @var{size} is a float number,
and @var{unit} can be @samp{cm} for centimeters, @samp{points} for
PostScript points, and @samp{in} for inches.  Default unit in
@samp{points}.

To change the fonts used, change the current prologue (@pxref{Designing
PostScript Prologues}.
@end defvr

@defvr {Option}  -l @var{num}
@defvrx {Option} -@b{-}chars-per-line=@var{num}
Set the font size so that @var{num} columns appear per virtual pages.
@var{num} is the real number of columns devoted to the body of the text,
i.e., no matter whether lines are numbered or not.
@end defvr

@defvr {Option}  -L @var{num}
@defvrx {Option} -@b{-}lines-per-page=@var{num}
Set the font size so that @var{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.
@end defvr

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

If your file is actually a UNIX manual @emph{input}, i.e., a roff file,
then depending whether you left @pack{} delegate or not, you will get a
readable version of the text described, or a pretty-printed version of
the describing file (@pxref{Your Delegations}).
@end defvr

@defvr {Option}  -T @var{num}
@defvrx {Option} -@b{-}tabsize=@var{num}
set tabulator size to @var{num}.  This option is ignored if
@code{--interpret=no} is given.
@end defvr

@defvr {Option}  -@b{-}non-printable-format=@var{format}
specify how non-printable chars are printed. @var{format} can be
@table @samp
@item caret
Use classical Unix representation: @samp{^A}, @samp{M-^B} etc.

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

@item question-mark
A @samp{?} is written instead of the non-printable character.

@item octal
For instance @samp{\001}, @samp{177} etc.

@item hexa
For instance @samp{\x01}, @samp{\xfe} etc.

@item emacs
For instance @samp{C-h}, @samp{M-C-c} etc.
@end table
@end defvr


@node Headings Options
@subsection Headings Options
@cindex Headers
These are the options through which you may define the information you
want to see all around the pages.

All these options support @var{text} as an argument, which is composed
of plain strings and escapes.  @xref{Escapes}, for details.

@defvr {Option} -B
@defvrx {Option} -@b{-}no-header
no page headers at all.
@end defvr

@defvr {Option}  -b[@var{text}]
@defvrx {Option} -@b{-}header[=@var{text}]
set the page header
@end defvr

@defvr {Option} -@b{-}center-title[=@var{text}]
@defvrx {Option}  -@b{-}left-title[=@var{text}]
@defvrx {Option} -@b{-}right-title[=@var{text}]
Set virtual page center, left and right titles to @var{text}.
@end defvr

@defvr {Option}  -u[@var{text}]
@defvrx {Option} -@b{-}underlay[=@var{text}]
@cindex Under lay
@cindex Water mark
use @var{text} as @dfn{under lay} (or @dfn{water mark}), i.e., in a
light gray, and under every page.
@end defvr

@defvr {Option}  -@b{-}left-footer[=@var{text}]
@defvrx {Option} -@b{-}footer[=@var{text}]
@defvrx {Option} -@b{-}right-footer[=@var{text}]
Set sheet footers to @var{text}.
@end defvr



@node Input Options
@subsection Input Options

@defvr {Option} -a[@var{Page range}]
@defvrx {Option} -@b{-}pages[=@var{Page range}]
@cindex Page Range
With no argument, print all the page, otherwise select the pages to
print.  @var{Page range} is a list of interval, such as @samp{-a1}:
print only the first page, @samp{-a-3,4,6,10-}: print the first 3 pages,
page 4 and 6, and all the page after 10 (included).  Giving @samp{toc}
prints the table of content whatever its page number is.

The pages referred to are the @emph{input} pages, not the output pages,
that is, in @samp{-2}, printing with @samp{-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 (@pxref{Your
Delegations}).
@end defvr

@defvr {Option}  -c
@defvrx {Option} -@b{-}truncate-lines=@var{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.
@end defvr

@defvr {Option} -i
@defvrx {Option} -@b{-}interpret=@var{boolean}
interpret tab and ff chars.  This means that @samp{^L} jumps to a new
(virtual) pages, @samp{tab} advances to the next tabulation.
@end defvr

@defvr {Option} -@b{-}end-of-line=@var{type}
Specify what sequence of characters denotes the end of line.  @var{type}
can be:
@table @code
@item n
@itemx unix
@samp{\n}.

@item r
@itemx mac
@samp{\r}.

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

@item pc
@itemx rn
@samp{\r\n}. This is the type of end-of-line on MS-DOS.

@item any
@itemx auto
Any of the previous cases. This last case prevents the bad surprises
with files from PC (trailing @samp{^M}).
@end table
@end defvr

@defvr {Option}  -X @var{key}
@defvrx {Option} -@b{-}encoding=@var{key}
@cindex Encoding
Use the input encoding identified by @var{key}.  @xref{Some Encodings},
and the result of
@samp{a2ps --list=encodings} to know what encodings are supported.
Typical values are @samp{ASCII}, @samp{latin1}... @samp{latin6},
@samp{iso@var{n}} etc.
@end defvr

@defvr {Option} -@b{-}stdin=@var{filename}
Give the name @var{filename} to the files read through the standard
input.
@end defvr

@defvr {Option} -t @var{name}
@defvrx {Option} -@b{-}title=@var{name}
Give the name @var{name} to the document.  Escapes can be used
(@pxref{Escapes}).

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

It is @strong{not} the name of the output.  It is just a logical title.
@end defvr

@defvr {Option}  -@b{-}prologue=@var{prologue}
@cindex Prologue
Use @var{prologue} as the PostScript prologue for @pack{}.
@var{prologue} must be in a file named @file{@var{prologue}.pro}, which
must be in a directory of your library path (@pxref{Library Files}).
Available prologues are:
@include prologue.texi
@end defvr

@defvr {Option}  -@b{-}print-anyway=@var{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.  @pack{} also asks
@code{file(1)} what it thinks of the type of the file.  If @code{file(1)}
answers @samp{data}, the file will also be considered as binary, hence
not printed.
@end defvr

@defvr {Option} -Z
@defvrx {Option} -@b{-}delegate=@var{boolean}
Enable delegation of some files to delegated applications.  If
delegating is on, then @pack{} will @emph{not} process the file by itself,
but will call an application which handles the file in another way.  If
delegation is off, then @pack{} will process @emph{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 @ref{Your Delegations} for information on delegating, and option
@samp{--list=delegations} for the applications your @pack{} knows.
@end defvr

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

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

@example
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
@end example

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

Note too that you can generate only the table of content using
@samp{--pages}:
@example
a2ps *.c --toc -atoc
@end example
@end defvr


@node Pretty Print Options
@subsection Pretty Printing Options

These options are related to the pretty printing features of @pack{}.

@defvr {Option} -@b{-}highlight-level=@var{level}
Specify the @var{level} of highlighting.  @var{level} can be
@table @samp
@item none
no highlighting

@item normal
regular highlighting

@item heavy
even more highlighting.
@end table
See the documentation of the style sheets (@samp{--list=style-sheets})
for a description of @samp{heavy} highlighting.
@end defvr

@defvr {Option}  -g
Alias for @samp{--highlight-level=heavy}.
@end defvr

@defvr {Option}  -E[@var{language}]
@defvrx {Option} -@b{-}pretty-print[=@var{language}]
With no arguments, set automatic style selection on.  Otherwise, set
style to @var{language}.  Note that setting @var{language} to
@samp{plain} turns off pretty-printing.  @xref{Known Style Sheets}, and the
output of @samp{--list=style-sheets} for the available style sheets.

If @var{language} is @samp{@var{key}.ssh}, then don't look in the
library path, but use the file @file{@var{key.ssh}}.  This is to ease
debugging non installed style sheets.
@end defvr

@defvr {Option} -@b{-}strip-level=@var{num}
Depending on the value of @var{num}:
@table @samp
@item 0
everything is printed;
@item 1
regular comments are not printed
@item 2
strong comments are not printed
@item 3
no comment is printed.
@end table

This option is valuable for instance in @code{java} in which case strong
comments are the so called documentation comments, or in @code{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.
@end defvr



@node Output Options
@subsection Output Options
These are the options to specify what you want to do out of what @pack{}
produces.  Only a single destination is possible at a time, i.e., if
ever there are several options @samp{-o}, @samp{-P} or @samp{-d}, the
last one is honored.

@defvr {Option}  -o @var{file}
@defvrx {Option} -@b{-}output=@var{file}
leave output to file @var{file}.  If @var{file} is @samp{-}, leave
output to the standard output.
@end defvr

@defvr {Option} -@b{-}version-control=@var{type}
to avoid loosing a file, @pack{} 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 @file{/dev/null}), and is writable (in
this case, disabling version control makes @pack{} fail the very same way
as if version control was disabled: permission denied).

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

@item t
@itemx numbered
Always make numbered backups.

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

@item never
@itemx simple
Always make simple backups.
@end table

@end defvr

@defvr {Option} -@b{-}suffix=@var{suffix}
The suffix used for making simple backup files can be set with the
@code{SIMPLE_BACKUP_SUFFIX} environment variable, which can be
overridden by this option.  If neither of those is given, the default is
@samp{~}, as it is in @code{Emacs}.
@end defvr

@defvr {Option}  -P @var{name}
@defvrx {Option} -@b{-}printer=@var{name}
@vindex lp.options
send output to printer @var{name}.  See item @samp{Printer:} and
@samp{Unknown printer:} in @ref{Your Printers} and results of option
@samp{--list=defaults} to see the bindings between printer names and
commands.

It is possible to pass additional options to @code{lpr} or @code{lp} via
the variable @samp{lp.options}, for more information see @ref{Pass
Options to lpr}.
@end defvr

@defvr {Option} -d
send output to the default printer. See item @samp{DefaultPrinter:} in
@ref{Your Printers}.
@end defvr


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

@defvr {Option} -@b{-}ppd[=@var{key}]
With no argument, set automatic PPD selection, otherwise set
the PPD to @var{key}.
FIXME: what to read.
@end defvr

@defvr {Option}  -n @var{num}
@defvrx {Option} -@b{-}copies=@var{num}
print @var{num} copies of each page
@end defvr

@defvr {Option}  -s @var{duplex-mode}
@defvrx {Option}  -@b{-}sides=@var{duplex-mode}
@cindex Duplex
Specify the number of sheet sides, or, more generally, the Duplex mode
(@pxref{Glossary}). The valid values for @var{duplex-mode} are:
@table @samp
@item 1
@itemx simplex
One page per sheet.

@item 2
@itemx duplex
Two pages per sheet, DuplexNoTumble mode.

@item tumble
Two pages per sheet, DuplexTumble mode.
@end table
Not only does this option require Duplex from the printer, but it also
enables duplex features from @pack{} (e.g., the margin changes from front
pages to back pages etc.).
@end defvr

@defvr {Option} -S @var{key}[:@var{value}]
@defvrx {Option} -@b{-}setpagedevice=@var{key}[:@var{value}]
@cindex @code{setpagedevice}
@cindex Page device
Pass a page device definition to the generated PostScript output.  If no
@var{value} is given, @var{key} is removed from the definitions.
Note that several @samp{--setpagedevice} can be accumulated.

For example, command

@example
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
@end example

@noindent
prints file @file{report.pre} in duplex (two sides) tumble (suitable for
landscape documents).  This is also valid for delegated files:
@example
a2ps -SDuplex:true -STumble:true a2ps.texi
@end example

Page device operators are implementation dependent but they are
standardized.  @xref{Page Device Options}, for details.
@end defvr

@defvr {Option} -@b{-}statusdict=@var{key}[:@var{value}]
@defvrx {Option} -@b{-}statusdict=@var{key}[::@var{value}]
@cindex @code{statusdict}
Pass a statusdict definition to the generated PostScript output.
@code{statusdict} operators and variables are implementation dependent;
see the documentation of your printer for details.  @xref{Statusdict
Options}, for details.  Several @samp{--statusdict} can be accumulated.

If no @var{value} is given, @var{key} is removed from the definitions.

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

@example
a2ps --statusdict=setpapertray:1 quicksort.c
@end example

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

With two colons, define variable @var{key} to equal @var{value}.  For
instance:

@example
a2ps --statusdict=papertray::1 quicksort.c
@end example

@noindent
produces

@example
  /papertray 1 def
@end example

@noindent
in the PostScript.
@end defvr

@defvr {Option} -k
@defvrx {Option} -@b{-}page-prefeed
@cindex 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.

@pack{} quotes the access to that feature, so that non supporting
printers won't fail.
@end defvr

@defvr {Option} -K
@defvrx {Option} -@b{-}no-page-prefeed
disable page prefeeding.
@end defvr


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

@menu
* Use of Escapes::              Where they are used
* Structure of the Escapes::    Their syntax
* Available Escapes::           Detailed list
@end menu

@node Use of Escapes
@subsection Use of Escapes
They are used in several places in @pack{}:
@table @emph
@item Page markers
Headers, footers, titles and the water mark (@pxref{Headings Options}),
in general to print the name of file, page number etc.  On a new sheet
@pack{} 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., @samp{$l.}, @samp{$l^}).

@item Named output
To specify the generic name of the file to produce, or how to access a
printer (@pxref{Your Printers}).

@item Delegation
To specify the command associated to a delegation (@pxref{Your
Delegations}).

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

@item Variables in PostScript prologue
To allow the user to change some parameters to your prologues
(@pxref{Designing PostScript Prologues}).
@end table

@node Structure of the Escapes
@subsection General Structure of the Escapes
All format directives can also be given in format

@var{escape} @var{width} @var{directive}

@noindent
where
@table @var
@item escape
In general
@table @samp
@item %
escapes are related to general information (e.g., the current
date, the user's name etc.),

@item #
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.),

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

@item \
introduces classical escaping, or quoting, sequences (e.g., @samp{\n}, @samp{\f}
etc.).
@end table


@item width
Specifies the width of the column to which the escape is printed.
There are three forms for @var{width}
@table @samp
@item +@var{padding}@var{integer}
the result of the expansion is prefixed by the character @var{padding}
so that the whole result is as long as @var{integer}.  For instance
@samp{$+.10n} with a file name @samp{$n}=@file{foo.c} gives
@samp{.....foo.c}.

If no @var{padding} is given, @samp{ } (white space) is used.

@item -@var{padding}@var{integer}
Idem as above, except that completion is done on the left: @samp{$+.10n}
gives @samp{foo.c.....}.

@item @var{integer}
which is a short cut for @samp{+@var{integer}}. For example, escape
@samp{$5P} will expand to something like @samp{@ @
@ 12}.

@end table

@item directive
@xref{Available Escapes}.
@end table

@node Available Escapes
@subsection Available Escapes

Supported escapes are:
@table @samp
@item \\
character @samp{\}

@item \%
character @samp{%}

@item \$
character @samp{$}

@item \#
character @samp{#}

@item #?@var{cond}|@var{if_true}|@var{if_false}|
this may be used for conditional assignment.  The separator (presented
here as @samp{|}) may be any character.  @var{if_true} and
@var{if_false} may be defined exactly the same way as regular headers,
included escapes and the @samp{#?} construct.

The available tests are:
@table @samp
@item #?1
@itemx #?2
@itemx #?3
true if tag 1, 2 or 3 is not empty.  See item @samp{$t1} for
explanation.

@item #?d
true if Duplex printing is requested (@samp{-s2}).

@item #?j
true if bordering is asked (@samp{-j}).

@item #?l
true if printing in landscape mode.

@item #?o
true if only one virtual page per page (i.e., @samp{#v} is 1).

@item #?p
a page range has been specified (i.e., @samp{#p} is not empty).

@item #?q
true if @pack{} is in quiet mode.

@item #?r
true if major is rows (@samp{--major=rows}).

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

@item #?V
true if verbosity level includes the @samp{tools} flag (@xref{Global
Options}. option @samp{--verbosity}).
@end table

@item #!@var{key}|@var{in}|@var{between}|
Used for enumerations.  The separator (presented here as @samp{|}) may
be any character.  @var{in} and @var{between} are escapes.

The enumerations may be:
@table @samp
@item #!$
enumeration of the command line options.  In this case @var{in} in never
used, but is replaced by the arguments.

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

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

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

@end table

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

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

@item $@{@var{var}@}
value of the environment variable @var{var} if defined, nothing
otherwise.

@item $@{@var{var}:-@var{word}@}
if the environment variable @var{var} is defined, then its value,
otherwise @var{word}.

@item $@{@var{var}:+@var{word}@}
if the environment variable @var{var} is defined, then @var{word},
otherwise nothing.

@item $[@var{num}]
value of the @var{num}th argument given on the command line.  Note that
$[0] is the name under which @pack{} has been called.

@item #@{@var{key}@}
expansion of the value of the variable @var{key} if defined, nothing
otherwise (@pxref{Your Variables})

@item #@{@var{key}:-@var{word}@}
if the variable @var{var} is defined, then the expansion of its,
otherwise @var{word}.

@item #@{@var{key}:+@var{word}@}
if the variable @var{var} is defined, then @var{word}, otherwise
nothing.

@item #.
the extension corresponding to the current output language
(e.g. @samp{ps}).

@item %*
current time in 24-hour format with seconds @samp{hh:mm:ss}

@item $*
file modification time in 24-hour format with seconds @samp{hh:mm:ss}

@item $#
the sequence number of the current input file

@item %#
the total number of files

@item %a
the localized equivalent for @samp{Printed by @var{User Name}}.
@var{User Name} is obtained from the variable @samp{user.name}
(@pxref{Predefined Variables}).

@item %A
the localized equivalent for @samp{Printed by @var{User Name} from
@var{Host Name}}. The variables @samp{user.name} and @samp{user.host}
are used (@pxref{Predefined Variables}).

@item %c
trailing component of the current working directory

@item %C
current time in @samp{hh:mm:ss} format

@item $C
file modification time in @samp{hh:mm:ss} format

@item %d
current working directory

@item $d
directory part of the current file (@samp{.} if the directory part is
empty).

@item %D
current date in @samp{yy-mm-dd} format

@item $D
file modification date in @samp{yy-mm-dd} format

@item %D@{@var{string}@}
format current date according to @var{string} with the
@code{strftime(3)} function.

@item $D@{@var{string}@}
format file's last modification date according to @var{string} with the
@code{strftime(3)} function.

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

@item $e
file modification date in localized short format.

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

@item $E
file modification date in localized long format.

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

@item \f
character @samp{\f} (@code{form feed}).

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

@item %F
current date in @samp{dd.mm.yyyy} format.

@item $F
file modification date in @samp{dd.mm.yyyy} format.

@c @item %H
@c document title

@item #h
medium height in PostScript points

@item $l^
top most line number of the current page

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

@item $l#
number of lines in the current file.

@item %m
the host name up to the first @samp{.} character

@item %M
the full host name

@item \n
the character @samp{\n} (@code{new line}).

@item %n
shortcut for the value of the variable @samp{user.login}
(@pxref{Predefined Variables}).

@item $n
input file name without the directory part.

@item %N
shortcut for the value of the variable @samp{user.name}
(@pxref{Predefined Variables}).

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

@item #o
name of the output, before substitution (i.e., argument of @samp{-P},
or of @samp{-o}).

@item #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 (@pxref{Your
Printers}), the result of the evaluation.  For instance, if the symbolic
printer @samp{file} is defined as @samp{> $n.%.}, then @samp{#O} returns
@samp{foo.c.ps} when printing @file{foo.c} to PostScript.  @samp{#o}
would have returned @samp{file}.

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

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

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

@item %p.
current page number

@item $p.
page number for this file

@item %p#
total number of pages printed

@item $p#
number of pages of the current file

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

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

@item %q
localized equivalent for @samp{Page %p.}

@item $q
localized equivalent for @samp{Page $p.}

@item %Q
localized equivalent for @samp{Page %p./%p#}

@item $Q
localized equivalent for @samp{Page $p./$p#}

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

@item %s.
current sheet number

@item $s.
sheet number for the current file

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

@item %s#
total number of sheets

@item $s#
number of sheets of the current file

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

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

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

@item %T
current time in 24-hour format @samp{hh:mm}

@item $T
file modification time in 24-hour format @samp{hh:mm}

@item #v
number of virtual sheets

@item %V
the version string of @pack{}.

@item #w
medium width in PostScript points

@item %W
current date in @samp{mm/dd/yy} format

@item $W
file modification date in @samp{mm/dd/yy} format
@end table


@c   #####                                   #######
@c  #     #  ####  #    # ###### #  ####     #       # #      ######  ####
@c  #       #    # ##   # #      # #    #    #       # #      #      #
@c  #       #    # # #  # #####  # #         #####   # #      #####   ####
@c  #       #    # #  # # #      # #  ###    #       # #      #           #
@c  #     # #    # #   ## #      # #    #    #       # #      #      #    #
@c   #####   ####  #    # #      #  ####     #       # ###### ######  ####

@node Configuration Files
@chapter Configuration Files
@cindex Configuration Files
@cindex @file{.a2ps}
@cindex @file{a2psrc}
@cindex @file{a2ps.cfg}
@cindex @file{a2ps-site.cfg}

@pack{} reads several files before the command line options.  In the
order, they are:
@enumerate
@item
@cindex @samp{A2PS_CONFIG}
the system configuration file (usually @file{/usr/local/etc/a2ps.cfg})
unless you have defined the environment variable @samp{A2PS_CONFIG}, in
which case @pack{} reads the file it points to;

@item
the user's home configuration file (@file{$HOME/.a2ps/a2psrc})

@item
the local file (@file{./.a2psrc})
@end enumerate

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

The file @file{a2ps.cfg} is updated when you update @pack{}, while
@file{a2ps-site.cfg} is not, to preserve local definitions.

In the configuration files, empty lines and lines starting with @samp{#}
are comments.

The other lines have all the following form:
@example
@var{Topic:} @var{Arguments}
@end example

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

In the following sections, each @var{Topic:} is detailed.

@menu
* Including Configuration Files::  Isolating site specific values
* Your Library Path::           Setting the files search path
* Your Default Options::        Default state of a2ps
* Your Media::                  Sheets dimensions
* Your Printers::               How to access the printers
* Your Shortcuts::              Your very own command line options
* Your PostScript magic number::  Handling very old printers
* Your Page Labels::            Page names as in @code{Ghostview}
* Your Variables::              Short cut for long sequences
* Your Delegations::            Delegating some files to other filters
* Your Internal Details::       Details you might want to tune
@end menu

@node Including Configuration Files
@section Including Configuration Files

@defvr {Configuration Setting} Include: @var{file}
@cindex @samp{Include:}
Include (read) the configuration @var{file}.  if @var{file} is a
relative path (i.e., it does not start with @samp{/}), then it is
relatively to the current configuration file.
@end defvr

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

@node Your Library Path
@section Your Library Path

To define the default library path, you can use:

@defvr {Configuration Setting} LibraryPath: @var{path}
@cindex @samp{LibraryPath:}
Set the library path the @var{path}.
@end defvr

@defvr {Configuration Setting} AppendLibraryPath: @var{path}
@cindex @samp{AppendLibraryPath:}
Add @var{path} at the end of the current library path.
@end defvr

@defvr {Configuration Setting} PrependLibraryPath: @var{path}
@cindex @samp{PrependLibraryPath:}
Add @var{path} at the beginning of the current library path.
@end defvr

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
@samp{AppendLibraryPath:} and @samp{PrependLibraryPath:}.

@node Your Default Options
@section Your Default Options

@defvr {Configuration Setting} Options: @var{options+}
@cindex @samp{Options:}
Give @pack{} a list of command line options. @var{options+} is any
sequence of regular command line options (@pxref{Invoking a2ps}).

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

@example
Options: --medium=Letter
@end example

@noindent
It is exactly the same as always giving @pack{} the option
@samp{--medium=Letter} at run time.
@end defvr

The quoting mechanism is the same as that of a shell.  For instance
@example
Options: --right-title="Page $p" --center-title="Hello World!"
Options: --title="arg 'Jack said \\\"hi\\\"' has double quotes"
@end example

@node Your Media
@section Your Media

@defvr {Configuration Setting} Medium: @var{name} @var{dimensions}
@cindex @samp{Medium:}
Define the medium @var{name} to have the @var{dimensions} (in PostScript
points, i.e., 1/72 of inch).

There are two formats supported:

@table @asis
@item long
in which you must give both the size of the whole sheet, and the size of
the printable area:
@example
# A4 for Desk Jets
#      @var{name}     @var{w}      @var{h}     @var{llx}   @var{lly}   @var{urx}    @var{ury}
Medium: A4dj    595    842    24    50    571    818
@end example

@noindent
where @var{w}x@var{h} are the dimension of the sheet, and the four other
stand for lower left x and y, upper right x and y.

@item short
in which a surrounding margin of 24 points is used
@example
# A4
#      @var{name}     @var{w}      @var{h}
Medium: A4      595    842
@end example

@noindent
is the same as

@example
# A4
#      @var{name}     @var{w}      @var{h}
Medium: A4      595    842    24    24    571    818
@end example
@end table
@end defvr



@node Your Printers
@section 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'.

@defvr {Configuration Setting} Printer: @var{name} @var{PPD-key} @var{destination}
@defvrx {Configuration Setting} Printer: @var{name} @var{destination}
@defvrx {Configuration Setting} Printer: @var{name} @var{PPD-key}
@cindex @samp{Printer:}
Specify the destination of the output when the option @samp{-P
@var{name}} is given.  If @var{PPD-key} is given, declare the printer
@var{name} to be described by the PPD file @file{@var{PPD-key}.ppd}.  If
@var{destination} is not given, used that of the @samp{UnknownPrinter:}.

The @var{destination} must be of one of the following forms:
@table @samp
@item | @var{command}
in which case the output is piped into @var{command}.

@item > @var{file}
in which case the output is saved into @var{file}.
@end table
@end defvr

@defvr {Configuration Setting} UnknownPrinter: [@var{PPD-key}] @var{destination}
@cindex @samp{UnknownPrinter:}
Specify the destination of the output when when the option @samp{-P @var{name}}
is given, but there is no @samp{Printer:} entry for @var{name}.
@end defvr

@defvr {Configuration Setting} DefaultPrinter: [@var{PPD-key}] @var{destination}
@cindex @samp{DefaultPrinter:}
Specify the destination of the output when when the option @samp{-d}
(send to default output) is given.
@end defvr


Escapes expansion is performed on @var{destination} (@pxref{Escapes}).
Recall that @samp{#o} is evaluated to the destination
name, i.e., the argument given to @samp{-P}.

For instance
@example
# 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
@end example

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


@node Your Shortcuts
@section Your Shortcuts

@cindex @samp{:}
You can define some kind of `Macro Options' which stand for a set of
options.

@defvr {Configuration Setting} UserOption: @var{shortcut} @var{options...}
@cindex @samp{UserOption:}
Define the @var{shortcut} to be the list of @var{options...}.  When @pack{}
is called with @samp{-=@var{shortcut}} (or
@samp{--user-option=@var{shortcut}}), consider the list of
@var{options...}.
@end defvr

Examples are
@example
# 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
@end example


@node Your PostScript magic number
@section Your PostScript magic number
@cindex @samp{OutputFirstLine:}
@cindex @samp{%!}

@pack{} produces full DSC conformant PostScript (@pxref{Glossary}).
Adobe said
@quotation
Thou shalt start your PostScript DSC conformant files with
@example
%!PS-Adobe-3.0
@end example
@end quotation

The bad news is that some printers will reject this header.  Then you
may change this header without any worry since the PostScript produced
by @pack{} is also 100% PostScript level 1@footnote{That is to say, there
are no PostScript printers that don't understand these files.}.

@defvr {Configuration Setting} OutputFirstLine: @var{magic-number}
@cindex @samp{OutputFirstLine:}
Specify the header of the produced PostScript file to be @var{magic-number}.
Typical values include @samp{%!PS-Adobe-2.0}, or just @samp{%!}.
@end defvr


@node  Your Page Labels
@section 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 @code{Ghostview} shows as the list of page numbers.

@pack{} lets you define what you want in this field.

@defvr {Configuration Setting} PageLabelFormat: @var{format}
@cindex @samp{PageLabelFormat:}
Specify the @var{format} to use to label the PostScript pages.
@var{format} can use Escapes (@pxref{Escapes}).  Two
variables are predefined for this: @samp{#@{pl.short@}} and
@samp{#@{pl.long@}}.
@end defvr


@node Your Variables
@section Your Variables
@cindex Escape
@cindex Variable

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

@menu
* Defining Variables::          Syntax and conventions
* Predefined Variables::        Builtin variables
@end menu

@node Defining Variables
@subsection Defining Variables

@defvr {Configuration Setting} Variable: @var{key} @var{value}
@cindex @samp{Variable:}
Define the escape @samp{#@{@var{key}@}} to be a short cut for
@var{value}.  @var{key} must not have any character from @samp{:()@{@}}.
@end defvr

As as example, here is a variable for @code{psnup}, which encloses all
the option passing one would like.  Delegations are then easier to
write:
@example
Variable: psnup psnup -#v -q #?j|-d|| #?r||-c| -w#w -h#h
@end example

It is strongly suggested to follow a @samp{.} (dot) separated hierarchy,
starting with:
@table @samp
@item del
for variables that are related to delegations.

@item pro
for variables used in prologues (@pxref{Designing PostScript
Prologues}).  Please, specify the name of the prologue (e.g.,
@samp{pro.matrix.gray}).

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

@item pl
for page label formats. @xref{Your Page Labels}, the option
@samp{--page-label} in @ref{Input Options}.

@item toc
for toc formats.  See the option @samp{--toc} in @ref{Input Options}.

@item user
for user related information.  @xref{Predefined Variables}.
@end table

This naming convention has not fully stabilized.  We apologize for the
inconvenience this might cause to users.
@node Predefined Variables
@subsection Predefined Variables
@cindex Predefined Variables
@cindex Variables, predefined

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

In what follows, there are numbers (i) like this, or (ii) this.  It
means that @pack{} 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 @code{getpwuid}) and finally
arbitrary values.

@table @samp
@item user.comments
Comments on the user.  Computed by (i) the system's database (the part
of @code{pw_gecos} after the first @samp{,}), (ii) not defined.

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

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

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

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

@end table


@node  Your Delegations
@section Your Delegations
@cindex Delegations
There are some files you don't really want @pack{} to pretty-print,
typically page description files (e.g., PostScript files, @code{roff} files,
etc.).  You can let @pack{} delegate the treatment of these files to other
applications.  The behavior at run time depends upon the option
@samp{--delegate} (@pxref{Input Options}).


@menu
* Defining a Delegation::       Syntax of the definitions of the delegations
* Guide Line for Delegations::  What should be respected
* Predefined Delegations::      Making the best use of these delegations
@end menu

@node Defining a Delegation
@subsection Defining a Delegation

@defvr {Configuration Setting} Delegation: @var{name} @var{in}:@var{out} @var{command}
@cindex @samp{Delegation:}
Define the delegation @var{name}.  It is to be applied upon files of
type @var{in} when output type is @var{out}@footnote{Current @code{a2ps}
only handles PostScript output, i.e. @var{out}=@samp{ps}} thanks to
@var{command}.  Both @var{in} and @var{out} are @pack{} type keys such as
defined in @file{sheets.map} (@pxref{The Entry in sheets.map}).
@end defvr

@var{command} should produce the file on its standard output.  Of course
escapes substitution is performed on @var{command} (@pxref{Escapes}).
In particular, @var{command} should use the input file
@samp{$f}.

@example
# 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
@end example

Advantage should be taken from the variables, to encapsulate the
peculiarities of the various programs.
@example
# 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@}
@end example

Temporary file names (@samp{#f0} to @samp{#f9}) are available for
complex commands.
@example
# 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
@end example

@node Guide Line for Delegations
@subsection 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@footnote{Because hiding its use into @code{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:
@example
%!PS-Adobe-3.0
@end example

@pack{} @strong{needs} the @samp{%%BeginSetup}-@samp{%%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 @code{fixps} right after the PostScript generation:
@example
########## 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@}
@end example

There are some services expected from the delegations.  The delegations
you may write should honor:
@table @asis
@item the input file
available via the escape @samp{$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 @samp{'$f'}.  Some other variables are
affected.  Yes, I know, we need a special mechanism for @samp{'} itself.
Well, we'll see that later @samp{;-)}.

@item the medium
the dimension of the medium selected by the user are available through
@samp{#w} and @samp{#h}.

@item the page layout
the number of virtual pages is @samp{#v}.

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

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

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

The slogan "@emph{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 @code{DVI} file, @code{dvips} knows better the page numbers
than @code{psselect} would.  So a @code{DVI} to PostScript delegation
should ask the page selection (@samp{#p}) to @code{dvips}, instead of
using @code{psselect} later in the chain.  An other obvious reason here
is plain efficiency (globally, less data is processed).

@node Predefined Delegations
@subsection 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 @file{a2ps.cfg}.  We just want to explain some choices,
and give hints on how to make the best use of these delegations.

@defvr {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, @pack{} tries to guess if the file
is landscape by looking for the keyword @samp{landscape} in it, using
@code{strings(1)}:
@example
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
@end example

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

@example
\renewcommand@{\printlandscape@}@{\special@{landscape@}@}
\printlandscape
@end example

@noindent
in the preamble.

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

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

@node Your Internal Details
@section Your Internal Details

There are settings that only meant for @pack{} that you can tune by
yourself.

@defvr {Configuration Setting} FileCommand: @var{command}
@cindex @samp{TemporaryDirectory:}
The command to run to call @code{file(1)} on a file.  If possible, make
it follow the symbolic links.
@end defvr



@c #                               #######
@c #           #    #####          #           #    #       ######   ####
@c #           #    #    #         #           #    #       #       #
@c #           #    #####          #####       #    #       #####    ####
@c #           #    #    #         #           #    #       #            #
@c #           #    #    #         #           #    #       #       #    #
@c #######     #    #####          #           #    ######  ######   ####


@node  Library Files
@chapter Library Files
@cindex Library files

To be general and to allow as much customization as possible, @pack{}
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 @samp{a2ps
--list=defaults}.  Typically its value is:
@example
@cartouche
gargantua ~ $ a2ps --list=defaults
Configuration status of a2ps @value{VERSION}
@emph{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
@end cartouche
@end example

You may change this default path through the configuration files
(@pxref{Your Library Path}).

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

@menu
* Documentation Format::        Special tags to write a documentation
* Map Files::                   Their general shape and rationale
* Font Files::                  Using other fonts
* Style Sheet Files::           Defining pretty printing rules
@end menu


@node Documentation Format
@section 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:
@table @asis
@item @samp{code(}@var{text}@samp{)code}
Typeset @var{text} like a piece of code.  This should be used
for keys, variables, options etc.  For instance the documentation
of the @code{bold} prologue mentions the @code{bw} prologue:
@example
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
@end example

@item @samp{href(}@var{link}@samp{)href(}@var{text}@samp{)href}
Specifies a hyper text @var{link} displayed as @var{text}.

@item @samp{@@example}
@itemx @samp{@@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 @code{gnuc}
style sheet:
@example
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
@end example

@item @samp{@@itemize}
@itemx @samp{@@item} @var{text}
@itemx @samp{@@end itemize}
Typeset a list of items. The opening and closing tags must be alone on
the line.

@end table


@node Map Files
@section Map Files
@cindex Map files
@cindex .map
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:
@itemize @minus
@item
resolve aliases.  For instance the ISO-8859-1 encoding is also called
ISO Latin 1, or Latin 1 for short.  The @file{encoding.map} file will
map these three names to the same Encoding Description File.

@item
cope with broken files systems.  For instance,
the-one-you-know-I-don't-need-to-name cannot handle files named
@file{Courier-BoldOblique.afm}: it is the same as
@file{Courier-Bold.afm}.  The @file{fonts.map} file is here to associate
a font file name to a font name.
@end itemize

The syntax of these files is:
@itemize @minus
@item
any empty line, or any line starting by a @samp{#} is a comment.

@item
a line with the format
@example
@code{***}              @var{path}
@end example

@noindent
requests that the file designated by @var{path} be included at this
point.

@item
any other line has the format

@example
@var{key}               @var{value}
@end example

@noindent
meaning that when looking for @var{key} (e.g., name of a font, an
encoding etc.), @pack{} should use @var{value} (e.g., font file name,
encoding description file name etc.).
@end itemize

The map files used in @pack{} are:
@table @file
@item encoding.map
Resolving encodings aliases.

@item fonts.map
Mapping font names to font file names.

@item sheets.map
Rules to decide what style sheet to use.
@end table



@node Font Files
@section Font Files

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

@menu
* Fonts Map File::              Mapping a font name to a file name
* Fonts Description Files::     Needed files to use a Font
* Adding More Font Support::    Using even more Fonts
@end menu

@node Fonts Map File
@subsection Fonts Map File

@xref{Map Files}, for a description of the map files.  This file
associates the @var{font-key} to a @var{font} name. For instance:
@example
Courier                 pcrr
Courier-Bold            pcrb
Courier-BoldOblique     pcrbo
Courier-Oblique         pcrro
@end example

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

@node Fonts Description Files
@subsection Fonts Description Files
There are two kinds of data @pack{} needs to use a font:
@itemize @minus
@item
@cindex .afm
@cindex AFM
the AFM file (@file{@var{font-key}.afm}), which describes the metrics
information corresponding to @var{font};

@item
@cindex .pfa
@cindex .pfb
in the case @var{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 @var{font}.
@end itemize

@node Adding More Font Support
@subsection Adding More Font Support

@cindex @code{make_fonts_map.sh}

@pack{} can use as many fonts as you want, provided that you teach it the
name of the files in which are stored the fonts (@pxref{Fonts Map
File}).  To this end, a very primitive but still useful shell script is
provided: @code{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 @pack{} sees those
directories.  For instance, add:
@example
AppendLibraryPath: /usr/local/share/ghostscript/fonts
@end example

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

This script asks @pack{} for the library path, wanders in this path
collecting @code{AFM} files, and digging information in them.

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


@node Style Sheet Files
@section Style Sheet Files
@cindex @file{sheets.map}

The style sheets are defined in various files.  See @pxref{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 (@pxref{Map Files}).  This file is
@file{sheets.map}.

Its format is simple:
@example
@var{style-key}: @var{patterns}
@end example

@noindent
or
@example
include(@var{file})
@end example

The @var{patterns} need not be on separate lines.  There are two kinds
of patterns:
@table @asis
@item /@var{pattern}/@var{flags}
if the current file name matches @var{pattern}, then select style
@var{style-key} (i.e. file @file{@var{style-key}.ssh}).

@item <@var{pattern}>@var{flags}
if the result of a call to @code{file(1)} matches @var{pattern}, then
select style @var{style-key}.
@end table

Currently @var{flags} can only be @samp{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 @var{pattern}
as is, i.e., the @var{pattern} should itself be lower case.

The special @var{style-key} @samp{binary} tells @pack{} to consider that
the file should not be printed, and will be ignored, unless option
@samp{--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:
@enumerate
@item
if the file is presented through @code{stdin}, then @pack{} will run
@code{file(1)}.  However, unless you specify a fake file name with
@samp{--stdin}, pattern matching upon the name is turn off.  In general
you can expect correct delegations, but almost never pretty printing.

@item
if @code{file} is wrong on some files, @pack{} may use bad style sheets.
In this case, do try option @samp{--guess}, compare it with the output
of @code{file}, and if the culprit is @code{file}, go and complain to
your system administrator :-), or fix it by defining your own filename
pattern matching rules.
@end enumerate

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

@cartouche
@example
doc % file a2ps.texi
a2ps.texi: Texinfo source text
@end example
@end cartouche

@noindent
Therefore the sheets.map would look like:

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


@c #######
@c #        #    #   ####    ####   #####      #    #    #   ####    ####
@c #        ##   #  #    #  #    #  #    #     #    ##   #  #    #  #
@c #####    # #  #  #       #    #  #    #     #    # #  #  #        ####
@c #        #  # #  #       #    #  #    #     #    #  # #  #  ###       #
@c #        #   ##  #    #  #    #  #    #     #    #   ##  #    #  #    #
@c #######  #    #   ####    ####   #####      #    #    #   ####    ####

@node Encodings
@chapter Encodings

@pack{} 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 @pack{}, and some encodings it supports.

@menu
* What is an Encoding::         The concept of encoding explained
* Encoding Files::              How a2ps handles the encodings
@end menu

@node What is an Encoding
@section What is an Encoding

This section is actually taken from the web pages of
@href{http://www.alis.com/, Alis Technologies inc.}

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


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

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

@enumerate
@item
the code used in the shared document must always be identified
(labeling)

@item
they must agree on a small number of codes - only one, if possible
(standards);

@item
their software must recognize and process all codes (versatility)
@end enumerate

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 @dfn{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 @emph{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.


@node Encoding Files
@section Encoding Files

@menu
* Encoding Map File::           Mapping an encoding name to a file name
* Encoding Description Files::  Specifying an encoding
* Some Encodings::              Classical or standard encodings
@end menu

The support of the encodings in @pack{} 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.

@xref{What is an Encoding}, if you want to know more about this.

@node Encoding Map File
@subsection Encoding Map File

@xref{Map Files}, for a description of the map files.

The meaningful lines of the @file{encoding.map} file have the form:
@example
@var{alias}      @var{key}
iso-8859-1 latin1
latin1     latin1
l1         latin1
@end example

@noindent
where
@table @var
@item alias
specifies any name under which the encoding may be used.  It influences
the option @samp{--encoding}, but also the encodings dynamically
required, as for instance in the @code{mail} style sheet (support for
MIME).

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

@item key
specifies the prefix of the file describing the encoding
(@file{@var{key}.edf}, @ref{Encoding Description Files}).
@end table

@node Encoding Description Files
@subsection Encoding Description Files
@cindex .edf
@cindex EDF

The encoding description file describing the encoding @var{key} is named
@file{@var{key}.edf}.  It is subject to the same rules as any other
@pack{} file:
@itemize @minus
@item
please make the name portable: alpha-numerical, at most 8 characters,

@item
empty lines and lines starting by @samp{#} are ignored.

@end itemize

The entries are
@table @samp
@item Name:
Specifies the full name of the encoding.  Please, try to use the
official name if there is one.
@example
Name: ISO-8859-1
@end example

@item Documentation/EndDocumentation
Introduces the documentation on the encoding (@pxref{Documentation Format}).
Typical informations expected are
the other important names this encoding has, and the languages it covers.
@example
Documentation
Also known as ISO Latin 1, or Latin 1.  It is a superset
of ASCII, and covers most West-European languages.
EndDocumentation
@end example

@item Substitute:
Introduces a font substitution.  The most common fonts (e.g.,
@code{Courier}, @code{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 @code{Courier}, @pack{} allows to
specify that whenever a font is called in an encoding, then another font
should be used.

For instance in @file{iso2.edf} one can read:
@example
@i{# 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
@end example


@item 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 @code{Courier}
equivalent is the best choice.
@example
Default: Courier-Ogonki
@end example


@item 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., @samp{bell} in ASCII
(@code{^G}) should not be named).  The special name @samp{.notdef} is to
be used when the character is not printable.

@strong{Warning.}  Make sure to use real, official, PostScript names.
Using names such as @samp{c123} may be the sign you use unusual names.
On the other hand PostScript names such as @samp{afii8879} are common.
@end table


@node  Some Encodings
@subsection Some Encodings

Most of the following information is a courtesy of
@href{http://www.alis.com/, Alis Technologies inc.} and of
@email{zcyborra@@cs.tu-berlin.de, Roman Czyborra}'s page about
@href{http://czyborra.com/charsets/, The ISO 8859 Alphabet Soup}.
@xref{What is an Encoding}, is an instructive presentation of the
encodings.

@include encoding.texi


@c ######                          ######
@c #     #  #####                  #     #  #####      #    #    #   #####
@c #     #  #    #                 #     #  #    #     #    ##   #     #
@c ######   #    #                 ######   #    #     #    # #  #     #
@c #        #####    ###           #        #####      #    #  # #     #
@c #        #   #    ###           #        #   #      #    #   ##     #
@c #        #    #   ###           #        #    #     #    #    #     #

@node Pretty Printing
@chapter Pretty Printing
@cindex Pretty printing
@cindex Symbol conversion
The main feature of @pack{} is its pretty-printing capabilities.
Two different levels of pretty printing can be reached:
@itemize @minus
@item
basic (normal highlight level) in which what you print is what you
wrote.

@item
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 @samp{<=} and @samp{>=} will be replaced by
the corresponding single character from the font Symbol.
@end itemize

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

@menu
* Syntactic limits::            What can't be done
* Known Style Sheets::          Some supported languages
* Type Setting Style Sheets::   a2ps as a tiny word processor
* Faces::                       Encoding the look of pieces of text
* Style sheets semantics::      What is to be defined
* Style Sheets Implementation::  How they should be defined
* A tutorial on style sheets::  Step by step example
@end menu

@node Syntactic limits
@section Syntactic limits
@pack{} is @emph{not} a powerful syntactic pretty-printer: it just
handles lexical structures, i.e., if in your favorite language
@example
IF IF == THEN THEN THEN := ELSE ELSE ELSE := IF
@end example

@noindent
is legal, then @pack{} is not the tool you need.  Indeed @pack{}
just looks for some keywords, or some @dfn{sequences}.



@node Known Style Sheets
@section Known Style Sheets

@include sheets.texi


@node Type Setting Style Sheets
@section 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).

@menu
* Symbol::                      Access to the glyphs of the Symbol font
* PreScript::                   Typesetting in an a2ps like syntax
* PreTeX::                      Typesetting in a LaTeX like syntax
* TeXScript::                   Typesetting in a mixture of both
@end menu

@node Symbol
@subsection Symbol

The style sheet @code{Symbol} introduces easy to type keywords to obtain
the special characters of the PostScript font @code{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 @ref{A Bit of Syntax}.

If you want to know the correspondence, it is suggested to print the
style sheet file of @code{Symbol}:
@example
a2ps -g symbol.ssh
@end example


@node PreScript
@subsection PreScript
@cindex @code{PreScript}

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

The main advantages for using @code{PreScript} are:
@itemize @minus
@item
it is fairly simple,

@item
@pack{} is small and easy to install, hence it is available on
every UNIX platform.
@end itemize

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

@menu
* Syntax::                      Lexical specifications
* PreScript Commands::
* PreScript examples::
@end menu

@node Syntax
@subsubsection Syntax
Every command name begins with a backslash (@samp{\}). 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 @code{PreScript} is that no command can be used inside
another command. For instance the following line will be badly
interpreted by @pack{}:

@example
\Keyword@{Problems using \keyword@{recursive \copyright@} calls@}
@end example

The correct way to write this in @code{PreScript} is

@example
\Keyword@{Problems using@} \keyword@{recursive@} \copyright \Keyword@{calls@}.
@end example

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

@node PreScript Commands
@subsubsection PreScript Commands
These commands required arguments.

@table @samp
@item \keyword@{@var{text}@}
@itemx \Keyword@{@var{text}@}
Highlight lightly/strongly the given @var{text}.  Should be used only
for a couple of adjacent words.

@item \comment@{@var{text}@}
@itemx \Comment@{@var{text}@}
The @var{text} is given a special face.  The @var{text} may be removed
if option @samp{--strip} is used.

@item \label@{@var{text}@}
@itemx \Label@{@var{text}@}
@var{text} should be considered as a definition, or an important point
in the structure of the whole text.

@item \string@{@var{text}@}
Write @var{text} with string's face (e.g., in font Times).

@item \error@{@var{text}@}
Write @var{text} with error's face (generally a very different face, so
that you see immediately).

@item \symbol@{@var{text}@}
@var{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{} (@pxref{Symbol}).

@item \header@{@var{text}@}
@itemx \footer@{@var{text}@}
Use @var{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.

@item \encoding@{@var{key}@}
Change dynamically the current encoding.  After this command, the text is
printed using the encoding corresponding to @var{key}.
@end table

@node PreScript examples
@subsubsection Examples
@code{PreScript} and @pack{} can be used for one-the-fly
formating. For instance, on the @file{passwd} file:

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

@node PreTeX
@subsection @PreTeX

The aim of the Pre@TeX{} style sheet is to provide something similar to
@code{PreScript}, but with a more @LaTeX{} like syntax.

@menu
* Special characters::
* PreTeX Commands::
* Differences with LaTeX::
@end menu

@node Special characters
@subsubsection Special characters
@samp{$} is ignored in @code{Pre@TeX{}} for compatibility with @LaTeX{},
and @samp{%} introduces a comment. Hence they are the only symbols which
have to be quoted by a @samp{\}.  The following characters should also be
quoted to produce good @LaTeX{} files, but are accepted by
@code{PreScript}: @samp{_}, @samp{&}, @samp{#}.

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

@node PreTeX Commands
@subsubsection @PreTeX Commands
These commands required arguments.

@table @samp
@item \section@{@var{Title}@}
@itemx \subsection@{@var{Title}@}
@itemx \subsubsection@{@var{Title}@}.
Used to specify the title of a section, subsection or subsubsection.

@item \textbf@{@var{text}@}
@itemx \textit@{@var{text}@}
@itemx \textbi@{@var{text}@}
@itemx \textrm@{@var{text}@}
write @var{text} in bold, italic, bold-italic, Times.  Default font is
Courier.

@item \textsy@{@var{text}@}
@var{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 @code{Symbol}).

@item \header@{@var{text}@}
@itemx \footer@{@var{text}@}
Use @var{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.

@item \verb+@var{text}+
Quote @var{text} so that no special sequence will be interpreted.  In
@samp{\verb+@var{quoted string}+} @samp{+} can be any symbol in
@samp{+}, @samp{!}, @samp{|}, @samp{#}, @samp{=}.

@item \begin@{document@}
@itemx \end@{document@}
@itemx \begin@{itemize@}
@itemx \end@{itemize@}
@itemx \begin@{enumerate@}
@itemx \end@{enumerate@}
@itemx \begin@{description@}
@itemx \end@{description@}
These commands are legal in @LaTeX but have no sense in @PreTeX{}.
Hence there are simply ignored and not printed (if immediately followed
by an end-of-line).
@end table

@node Differences with LaTeX
@subsubsection Differences with @LaTeX
The following symbols, inherited from the style sheet @code{Symbol}, are
not supported by @LaTeX{}:

@samp{\Alpha}, @samp{\apple}, @samp{\Beta}, @samp{\carriagereturn},
@samp{\Chi}, @samp{\Epsilon}, @samp{\Eta}, @samp{\florin}, @samp{\Iota},
@samp{\Kappa}, @samp{\Mu}, @samp{\Nu}, @samp{\Omicron}, @samp{\omicron},
@samp{\radicalex}, @samp{\register}, @samp{\Rho}, @samp{\suchthat},
@samp{\Tau}, @samp{\therefore}, @samp{\trademark}, @samp{\varUpsilon},
@samp{\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
@samp{$} signs. For instance, though
@example
If \forall x \in E, x \in F then E \subseteq F.
@end example

@noindent
is perfectly legal in @PreTeX{}, it should be written
@example
If $\forall x \in E, x \in F$ then $E \subseteq F$.
@end example

@noindent
for @LaTeX{}. Since in @PreTeX every @samp{$} is discarded (unless
quoted by a @samp{\}), the second form is also admitted.

@node TeXScript
@subsection @TeXScript

@code{@TeX{}Script} is a replacement of the old version of
@code{PreScript}: it combines both the @pack{}-like and the
@LaTeX{}-like syntaxes through inheritance of both @code{PreScript} and
@code{Pre@TeX{}}.

In addition it provides commands meant to ease processing of file for
@pack{} by @LaTeX{}.

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

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

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

There is no way in @TeXScript to get an automatic numbering.  There is
no equivalent to the @LaTeX{} environment @code{enumerate}.  But every
command beginning by @code{\text} is doubled by a command beginning by
@samp{\magic}.  @pack{} 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
@example
\begin@{enumerate@}
\magicbf@{1.@}\item First line
\magicbf@{2.@}\item Second line
\end@{enumerate@}
@end example

@noindent
will be treated the same way both in @TeXScript and @LaTeX{}.

@samp{\header} and @samp{\footer}, are not understood by @LaTeX{}.


@node Faces
@section Faces
@cindex Face
A @dfn{face} is an attribute given to a piece of text, which specifies
how it should look like.  Since @pack{} 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 @pack{} uses are:
@table @samp
@item Plain
This corresponds to the text body.

@item Keyword
@itemx Keyword_strong
These are related to the keywords that may appear in a text.

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

@item Label
@itemx Label_strong
These are used when a point of extreme importance, or a sectioning
point, is met.  Typically, functions declarations etc.

@item String
Used mainly for string and character literals.

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

Actually, there is also the face @samp{Symbol}, but this one is
particular: it is not legal changing its font.


@c ----------------------------------- Style sheets semantics
@node Style sheets semantics
@section Style Sheets Semantics
@cindex Style sheet

@pack{} pretty prints a source file thanks to @dfn{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
@pack{} does this, and if you don't expect to implement new styles.

@menu
* Name and key::                Both names of a style sheet
* Comments::                    Author name, version etc.
* Alphabets::                   What words are legal
* Case sensitivity::            Is BEGIN different of begin
* P-Rules::                     Pretty Printing Rules
* Sequences::                   Strings, comments etc.
* Optional entries::            Second level of pretty printing
@end menu


@node Name and key
@subsection Name and key
@cindex key
@cindex @file{sheets.map}
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 @pack{} needs to recognize a style sheet by a name, @strong{it
uses the key} (in the @file{sheets.map} file, with the option @samp{-E},
etc.).

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

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


@node Comments
@subsection Comments
ssh files can include the name of its author, a version number, a
documentation note and a requirement on the version of @pack{}.  For
instance, if a style sheet requires @pack{} version 4.9.6, then @pack{}
version 4.9.5 will reject it.

@node Alphabets
@subsection Alphabets
@cindex Alphabets
@cindex Separator
@pack{} 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.

@node Case sensitivity
@subsection Case sensitivity
If the style is case insensitive, then matching is case insensitive
(keywords, operators and sequences).

@node P-Rules
@subsection P-Rules
@cindex Keyword
@cindex Rule
@cindex P-Rule
@cindex Operator

A @dfn{P-rule} (Pretty printing rule), or @dfn{rule} for short, is a
structure which consists of two items:
@table @dfn
@item lhs
@cindex lhs
@itemx left-hand side
its source string, with which the source file is compared;

@item rhs
@cindex rhs
@itemx 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
@itemize @minus
@item
a string, or a reference to a part of the source string
(@pxref{Back-reference Operator,,Back-reference Operator,regex,Regex
manual})

@item
the face to use to print it
@end itemize
@end table

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

If the destination string is empty, then @pack{} 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 @code{foobar} be a case insensitive style sheet including the
rules @samp{(foo, "", Keyword)} and @samp{(bar, bar, Keyword)}.  Then,
on the input @samp{FOO BAR}, @pack{} will produce @samp{FOO bar} in
@code{Keyword}.

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

The first ones are called @dfn{keywords} in @pack{} jargon, and the
seconds are @dfn{operators}.  Operators are matched anywhere they
appear, while keywords need to have separators around them
(@pxref{Alphabets}).

Let us give a more complicated example: that of the @code{Yacc} rules.
A rule in @code{Yacc} is of the form:
@example
a_rule : part1 part2 ;
@end example

Suppose you want to highlight these rules.  To recognize them, you will
write a regular expression specifying that:
@enumerate
@item
it must start at the beginning of the line,

@item
then there is string composed of symbols, which is what you want to
highlight,

@item
and a colon, which can be preceded by blank characters.
@end enumerate

The regexp you want is: @samp{/^[a-zA-Z0-9_]*[\t ]*:/}.  But with the
rule
@example
/^[a-zA-Z0-9_]*[\t ]*:/, "", Label_strong
@end example

@noindent
the blanks and the colon are highlighted too.  Hence you need to
specify some parts in the regexp (@pxref{Back-reference
Operator,,Back-reference Operator,regex,Regex manual}), and use a longer
list of destination strings.  The correct rule is
@example
(/^([a-zA-Z0-9_]*)([\t ]*:)/, \1 Label_strong, \2 Plain)
@end example

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:
@example
(/^([a-zA-Z0-9_]*)/    # \1. Name of the rule
 /([\t ]*:)/           # \2. Trailing space and colon
 \1 Label_strong, \2 Plain)
@end example



@node Sequences
@subsection Sequences
@cindex Sequences
@cindex Markers
A @dfn{sequence} is a string between two @dfn{markers}, along with a
list of exceptions.  A marker is a fixed string.  Typical examples are
comments, string (with usually @samp{"} as opening and closing markers,
and @samp{\\} and @samp{\"} 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.

@node Optional entries
@subsection Optional entries
@cindex Optional entries
There are two levels of pretty-printing encoded in the style sheets.  By
default, @pack{} uses the first level, called @dfn{normal}, unless the
option @samp{-g} is specified, in which case, @dfn{heavy} highlighting
is invoked, i.e., optional keywords, operators and sequences are
considered.

@c ---------------------------------------- Style Sheets Implementation

@node Style Sheets Implementation
@section Style Sheets Implementation

In the previous section (@pxref{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 (@pxref{A tutorial on style
sheets}), exposes a step by step simple example.

@menu
* A Bit of Syntax::             Lexical rules of the ssh language
* Style Sheet Header::          Declaration of a style
* Syntax of the Words::         Classes of the Characters
* Inheriting::                  Extending existing style sheets
* Syntax for the P-Rules::      Atomic Pretty Printing rules
* Declaring keywords and operators::  Special Classes of Identifiers
* Declaring sequences::         Bordered Lexical Entities
* Checking a Style Sheet::      Ask a2ps to Check the Sheet
@end menu

@node A Bit of Syntax
@subsection A Bit of Syntax
Here are the lexical rules underlying the style sheet language:
@itemize @minus
@item
the separators are white space, form feed, new line, and tab.

@item
@samp{#} introduces a comment, ended at the end of the line.

@item
special characters are the separators, plus @samp{#}, @samp{"},
@samp{,}, @samp{(}, @samp{)}, @samp{+} and @samp{/}.  Any other
character is a regular character.

@item
the list of the structuring keywords is
@quotation
@code{alphabet}, @code{alphabets}, @code{are}, @code{case},
@code{documentation}, @code{end}, @code{exceptions}, @code{first},
@code{in}, @code{insensitive}, @code{is}, @code{keywords},
@code{operators}, @code{optional}, @code{second}, @code{sensitive},
@code{sequences}, @code{style}
@end quotation

@item
the list of the keywords designating faces is
@quotation
@code{Comment}, @code{Comment_strong}, @code{Encoding}, @code{Error},
@code{Index1}, @code{Index2}, @code{Index3}, @code{Index4},
@code{Invisible}, @code{Keyword}, @code{Keyword_strong}, @code{Label},
@code{Label_strong}, @code{Plain}, @code{String}, @code{Symbol},
@code{Tag1}, @code{Tag2}, @code{Tag3}, @code{Tag4}
@end quotation

@item
the list of keywords designating special sequences is
@quotation
@code{C-char}, @code{C-string}
@end quotation

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

@item
a string starts and finishes with @samp{"}, and may contain anything.
Regular @code{C} escaping mechanism is used.

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

@item
any sequence of regular characters which is not a keyword, is a string
(consider this as a shortcut, avoiding extraneous @samp{"}).

@end itemize

@node Style Sheet Header
@subsection Style Sheet Header
The definition of the name of the style sheet is:
@display
@code{style} @var{name} @code{is}
  # body of the style sheet
@code{end} @code{style}
@end display

The following constructions are optional:
@table @code

@item version
To define the version number of the style sheet
@example
version is @var{version-number}
@end example


@item written
To define the author(s).
@example
written by @var{authors}
@end example

Giving your email is useful for bug reports about style sheets.
@example
written by "Some Body <Some.Body@@some.whe.re>"
@end example


@item requires
To specify the version of @pack{} it requires.  @pack{} won't accept a file
which requires a higher version number than its own.
@example
requires a2ps @var{a2ps-version-number}
@end example


@item documentation
To leave extra comments people should read.
@example
documentation is
   @var{strings}
end documentation
@end example
@var{strings} may be a list of strings, without comas, in which case new
lines are automatically inserted between each item.  @xref{Documentation
Format}, for details on the format.

Please, write useful comments, not @samp{This style is devoted to C
files}, since the name is here for that, nor @samp{Report errors to
mail@@me.somewhere}, since @code{written by} is there for that.
@example
documentation is
    "Not all the keywords are used, to avoid too much"
    "bolding. Heavy highlighting (code(-g)code), covers"
    "the whole language."
end documentation
@end example
@end table

@node Syntax of the Words
@subsection Syntax of the Words
There are two things @pack{} needs to know: what is symbol consistent,
and whether the style is case insensitive.

@table @code
@item alphabet
To define two different alphabets, use
@example
first alphabet is @var{string}
second alphabet is @var{string}
@end example

If both are identical, you may use the shortcut
@example
alphabets are @var{string}
@end example

The default alphabets are
@example
first alphabet is
  "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_"
second alphabet is
"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_\
0123456789"
@end example

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


@item case
@example
case insensitive        # @i{e.g., C, C++ etc.}
case sensitive          # @i{e.g., Perl, Sather, Java etc.}
@end example

@noindent
The default is @code{case insensitive}.

@end table

@node Inheriting
@subsection Inheriting from Other Style Sheets

It is possible to extend an existing style. The syntax is:
@example
ancestors are
   @var{ancestor_1}[, @var{ancestor_2}...]
end ancestors
@end example

@noindent
where @var{ancestor1} etc. are style sheet keys.

For semantics, the rules are the following:
@itemize @minus
@item
the ancestors are read in order;

@item
the definition of the current style is read last;

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

@end itemize

As an example, both @code{C++} and @code{Objective C} style sheets
extend the @code{C} style sheet:

@example
style "Objective C" is
#@i{[...]}
ancestors are
   c
end ancestors
#@i{[...]}
end style
@end example

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


@node Syntax for the P-Rules
@subsection Syntax for the P-Rules

@xref{P-Rules}, for the definition of @dfn{P-rule}.

Because of various short cuts, there are many ways to declare a rule:
@example
@var{rules}     ::= @var{rule_1} @samp{,} @var{rule_2}...
@var{rule}      ::= @samp{(} @var{lhs} @var{rhs} @samp{)}
           | @var{lhs} @var{srhs} ;
@var{lhs}       ::= @var{string} | @var{regex} ;
@var{rhs}       ::= @var{srhs} @samp{,} ...
@var{srhs}      ::= @var{latex-keyword} | @var{expansion} @var{face}
@var{expansion} ::= @var{string} | @samp{\}@var{num} | <nothing>;
@var{face}      ::= @var{face-keyword} | <nothing>;
@end example

The rules are the following:
@itemize @minus
@item
@cindex Regular expression
If the left-hand side (lhs) is a regular expression, then it is compiled
with the following syntax bits:
@example
#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)
@end example

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


@item
If no @var{expansion} is specified, then the matched string is used.
For instance @samp{(/fo*/, NULL, Keyword)} applied on the source
@samp{fooooo} produces @samp{fooooo} in @code{Keyword}.

@item
If no @var{face} is given, then
@itemize @minus
@item
if the context defines the default face, then this face is used;

@item
if no default face is given, @code{PLAIN} is used.
@end itemize
@end itemize


@node Declaring keywords and operators
@subsection Declaring the keywords and the operators

Basically, keywords and operators are lists of rules.  The syntax is:
@example
keywords are
  @var{rules}
end keywords
@end example

@noindent
or
@example
keywords in @var{face-keyword} are
  @var{rules}
end keywords
@end example

@noindent
in which case the default face is set to @var{face-keyword}.

As an example:
@example
keywords in Keyword_strong are
  /foo*/,
  "bar" "BAR" Keyword,
  -> \rightarrow
end keywords
@end example

@noindent
is valid.

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

This is an extract of the @code{C} style sheet:
@example
optional operators are
   -> \rightarrow,
   && \wedge,
   || \vee,
   != \neq,
   == \equiv,
   # We need to protect these, so that <= is not replaced in <<=
   <<=,
   >>=,
   <= \leq,
   >= \geq,
   ! \not
end operators
@end example

Note how @samp{<<=} and @samp{>>=} are protected (there are defined to
be written as is when met in the source).  This is to prevent the two
last characters of @samp{<<=} 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 @pack{} sorts them at run time, it
may save time if the alphabetical @code{C}-order is more or less
followed.

You should be aware that when declaring a keyword with a regular
expression as lhs, then @pack{} 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
@example
keywords are
  /foo|bar/
end keywords
@end example

@noindent
is exactly the same as
@example
operators are
  /\\b(foo|bar)\\b/
end operators
@end example

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

@xref{Match-word-boundary Operator,,Match-word-boundary
Operator,regex,Regex manual}, for details on @samp{\b}.

@node Declaring sequences
@subsection Declaring the sequences


Sequences admit several declarations too:
@example
@var{sequences}      ::= sequences are
                     @var{sequence_1} @samp{,} @var{sequence_2}...
                   end sequences
@var{sequence}       ::= @var{rule} @var{in_face} @var{close_opt} @var{exceptions_opt}
                 | @code{C-string}
                 | @code{C-char}
                 ;
@var{close_opt}      ::= @var{rule}
                 | closers are
                     @var{rules}
                   end closers
                 | <nothing>
                 ;
@var{exceptions_opt} ::= exceptions are
                     @var{rules}
                   end exceptions
                 | <nothing>
                 ;
@end example

The rules are:
@itemize @minus
@item
The default face is then @var{in_face}.

@item
If no closing rule is given, @samp{"\n"} (i.e., end-of-line) is used.
@end itemize

As a first example, here is the correct definition for a @code{C} string:
@example
sequences are
 "\"" Plain String "\"" Plain
     exceptions are
        "\\\\", "\\\""
     end exceptions
end sequences
@end example
@cindex @code{C-string}
@cindex @code{C-char}
Since a great deal of languages uses this kind of constructs, you may
use @code{C-string} to mean exactly this, and @code{C-char} for
manifest characters defined the @code{C} way.

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

@example
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
@end example

The order between sequences does matter.  For instance in Java,
@samp{/**} introduces strong comments, and @samp{/*} comments.
@samp{/**} @emph{must} be declared before @samp{/*}, 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 @code{C} comments,
@example
/*
 * a comment
 */
@end example

@noindent
cannot be implemented with operators, though @code{C++} comments can:
@example
//
// a comment
//
@end example

@node Checking a Style Sheet
@subsection Checking a Style Sheet

Once your style sheet is written, you may want to let @pack{} 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 @pack{} will not look at it in its library
path, but precisely from when you are.

Suppose for instance you extended the @file{c.ssh} style sheet, which is
in the current directory, and is said case insensitive.  Run
@example
ubu $ a2ps foo.c -Ec.ssh -P void -v sheets
@i{# 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
@end example

@noindent
Here, it is clear that @code{C} is not case insensitive.

@c ---------------------------------------- A tutorial on style sheets

@node A tutorial on style sheets
@section A Tutorial on Style Sheets
In this section a simple example of style sheet is entirely covered:
that of @file{ChangeLog} files.

@file{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.

@menu
* Example and syntax::          ChangeLog files
* Implementation::              Implementation of chlog.ssh
* The Entry in sheets.map::     Getting automatic style selection
* More Sophisticated Rules::    Complex regular expressions
* Distributed Style Sheets::    Additional Constraints
@end menu

@node Example and syntax
@subsection Example and syntax
First of all, here is a sample of a @file{ChangeLog} file, taken from
the @file{misc/} directory of the original @pack{} package:
@example
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.
@end example

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.

@node Implementation
@subsection Implementation
Quite naturally the style will be called @code{ChangeLog}, hence:
@example
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
@end example

A first interesting and easy entry is that of function names, between
@samp{(} and @samp{)}:
@example
sequences are
  "(" Plain Label ")" Plain
end sequences
@end example

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 @pack{}, 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 @samp{:}, 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:

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

Finally, let us say that some words have a higher importance in the core
of text: those about removing or adding something.
@example
keywords in Keyword_strong are
  add, added, remove, removed
end keywords
@end example

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 @samp{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 @file{chlog.ssh}.

@example
# 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
@end example

As a last step, you may which to let @pack{} check your style sheet, both
its syntax, and common errors:
@example
ubu $ a2ps -vsheet -E/tmp/chlog.ssh ChangeLog -P void
@i{Long output deleted}
Checking coherence of "ChangeLog" (/tmp/chlog.ssh)
"ChangeLog" (/tmp/chlog.ssh) is sane.
---------- End of Finalization of /tmp/chlog.ssh
@end example

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


@node The Entry in sheets.map
@subsection The Entry in @file{sheets.map}

The last touch is to include the pattern rules about @file{ChangeLog}
files (which could appear as @file{ChangeLog.old} etc.) in
@file{sheets.map}:
@example
# ChangeLog files
chlog:  /ChangeLog*/
@end example

This won't work...  Well, not always.  Not for instance if you print
@file{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 @samp{*}:
@example
# ChangeLog files
chlog:  /*ChangeLog*/
@end example

@noindent
If you want to be more specific (@file{FooChangeLog} should not
match), use:
@example
# ChangeLog files
chlog:  /ChangeLog*/ /*\/ChangeLog*/
@end example



@node More Sophisticated Rules
@subsection 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:
@example
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>
@end example

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 @samp{<}, and finishes with a @samp{>}.  Its
rule is then @samp{/<[^>]+>/}.  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: @samp{/[[:alpha:]]+([ \t]+[[:alpha:]]+)*/}.
To concatenate the two, we introduce optional blanks, and we put each one
into a pair of @samp{(}-@samp{)} to make each one a recognizable
part:
@example
([[:alpha:]]+([ \t]+[[:alpha:]]+)*)
(.+)
(<[^>]+>)
@end example

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 (@pxref{Grouping
Operators,,Grouping Operators,regex,Regex manual}), we have:
@example
^
([^\t ].*[0-9])
([ \t]+)
([[:alpha:]]+([ \t]+[[:alpha:]]+)*)
(.+)
(<[^>]+>)
@end example

Now the destination is composed of back references to those groups,
together with a face:
@example
# 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
@end example

Notice the way regexps are split, to ease reading.

@node Distributed Style Sheets
@subsection 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.

@table @emph
@item 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.

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

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

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

@item The @file{sheets.map} Entries
Put in a comment on the @file{sheets.map} lines that correspond to your
style sheet.

@item 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.
@end table

Finally, make sure your style sheet behaves well! (@pxref{Checking a
Style Sheet})

@c ######                        #####
@c #     #  ####    ####  ##### #     #   ####   #####   #  #####   #####
@c #     # #    #  #        #   #        #    #  #    #  #  #    #    #
@c ######  #    #   ####    #    #####   #       #    #  #  #    #    #
@c #       #    #       #   #         #  #       #####   #  #####     #
@c #       #    #  #    #   #   #     #  #    #  #   #   #  #         #
@c #        ####    ####    #    #####    ####   #    #  #  #         #

@node PostScript
@chapter PostScript

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

@menu
* Good and Bad PostScript::     How to lose, how to win
* Page Device Options::         Accessing some printers' features
* Statusdict Options::          Some other features
* Colors in PostScript::        Specifying a color or a gray
* a2ps PostScript Files::       Convention for PostScript library files
* Designing PostScript Prologues::  Make it look like what you want
@end menu

@node Good and Bad PostScript
@section Foreword: Good and Bad PostScript
@cindex Optimize for Speed
@cindex Optimize for Portability
@cindex PostScript Quality
@cindex DSC

To read this section, the reader must understand what DSC are
(@pxref{Glossary}).

@quotation
@i{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!}
@end quotation

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 @dfn{Optimize for Speed}, is,
once you arrived to page 51, to download those fonts @strong{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 @strong{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
@quotation
@strong{Non DSC conformant files are not necessarily badly designed
files from broken applications.}
@end quotation

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
@strong{right}.

There is a third possibility, sometimes called @dfn{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 @pack{} 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.


@node Page Device Options
@section Page Device Options
Page device is a PostScript level 2 feature that offers an uniform
interface to control the printer's output device.  @pack{} 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
@samp{-S} option (@samp{--setpagedevice}).  For a complete listing, see
@cite{PostScript Language Reference Manual} (section 4.11 Device Setup
in the second edition, or section 6, Device Control in the third
edition).

@table @code

@item Collate @var{boolean}
how output is organized when printing multiple copies

@item Duplex @var{boolean}
duplex (two side) printing

@item ManualFeed @var{boolean}
manual feed paper tray

@item OutputFaceUp @var{boolean}
print output `face up' or `face down'

@item Tumble @var{boolean}
how opposite sides are positioned in duplex printing
@end table

@node Statusdict Options
@section Statusdict Options
The @code{statusdict} is a special storage entity in PostScript (called
a @dfn{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:

@table @code
@item manualfeed @var{boolean}
Variable which determine that the manual fed paper tray will be used.
Use is @samp{--statusdict=manualfeed::true}.

@item setmanualfeed @var{boolean}
Idem as the previous point, but use is
@samp{--statusdict=setmanualfeed:true}.

@item setduplexmode @var{boolean}
If @var{boolean}, then print Duplex.  Use if
@samp{--statusdict=setduplexmode:true}.
@end table


@node Colors in PostScript
@section Colors in PostScript

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

There are two PostScript instructions you might want to use in your new
PostScript prologue:
@table @code
@item setgray
this instruction must be preceded by a number between 0 (black) and 1
(white).  It defines the gray level used.

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

@end table

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


@node a2ps PostScript Files
@section @pack{} PostScript Files
@pack{} 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:
@example
% code follows this line
@end example


@node Designing PostScript Prologues
@section Designing PostScript Prologues

It is pretty known that satisfying the various human tastes is an
NEXPTIME-hard problem, so @pack{} offers ways to customize its output
through the @dfn{prologue files}.  But since the authors feel a little
small against NEXPTIME, they agreed on the fact that @strong{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 @pack{} output.

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

@menu
* Definition of the faces::     What goes in a characters style
* Prologue File Format::        Including documentation
* A prologue example::          A step by step example
@end menu

@node Definition of the faces
@subsection Definition of the faces
There are three things that define a face:
@table @emph
@item Its font
You should never call the font by yourself, because sometimes @pack{} 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 @pack{} to do it.  This is
done through a line:
@example
%Face: @var{face} @var{real-font-name} @var{size}
@end example

@noindent
This line tells @pack{} that the font of @var{face} is
@var{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 @code{bfs}.


@item Its background color
There are two cases:
@enumerate
@item
You want a background color, then give the @dfn{RGB} (@pxref{Colors in
PostScript}) ratio and @code{true} to @code{BG}:
@example
0.8 0.8 0 true BG
@end example

@item
You don't want a background color, then call @code{BG} with
@code{false}:
@example
false BG
@end example
@end enumerate

@item Its foreground color
As @code{BG}, call @code{FG} with an @dfn{RGB} ratio:
@example
0 0.5 0 FG
@end example

@item Its underlining
@code{UL} requires a boolean argument, depending whether you want
or not the current face to be underlined.
@example
true UL
@end example

@item Its boxing
Requiring a boolean, @code{BX} let's a face have a box drawn around.

@end table

@node Prologue File Format
@subsection Prologue File Format

Prologue files for @pack{} must have @samp{pro} as suffix.  Documentation
(reported with @samp{--list-prologues}) can be included in the comment
part:
@example
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
@end example
@xref{Documentation Format}, for more on the format.

@node A prologue example
@subsection 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 @samp{a2ps
--list=prologues}), to drop it in one of @pack{} directories (say
@samp{$HOME/.a2ps}, and to patch it until you like it.

Here, we will start from @file{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 @emph{amateur}).

Then you need to look for @samp{k} and @samp{K}:
@example
/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
@end example

@noindent
and turn it into:
@example
/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
@end example

Waouh!  It looks great!

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

First, let's look for the font definition:
@example
%%BeginSetup
% The font for line numbering
/f# /Helvetica findfont bfs .6 mul scalefont def
%%EndSetup
@end example

Let it be in Times, twice bigger than the body font.
@example
%%BeginSetup
% The font for line numbering
/f# /Times-Roman findfont bfs 2 mul scalefont def
%%EndSetup
@end example

How about its foreground color?
@example
% 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
@end example

Let it be blue.  Now you know the process: just put @samp{0 0 1} as
@code{FG} arguments.


@c                                  #####
@c  #          #    #####     ##   #     #  #####    ####
@c  #          #    #    #   #  #        #  #    #  #
@c  #          #    #####   #    #  #####   #    #   ####
@c  #          #    #    #  ###### #        #####        #
@c  #          #    #    #  #    # #        #       #    #
@c  ######     #    #####   #    # #######  #        ####

@c @node Programming with the Library, Contributions, PostScript, Top
@c @chapter Programming with the Library
@c @pack{} offers to the programmer an access to its generating routines.
@c This section documents the API.

@c But since this section is empty, or almost, if I were you, I would go in
@c @file{contrib/sample} to see how it works...

@c @menu
@c * Initialization of liba2ps::   Initializing the library
@c * Print Jobs::                  An output session
@c * File Jobs::                   An input session
@c * Printing Functions::          Specifying What to Print
@c @end menu

@c @node Initialization of liba2ps, Print Jobs, Programming with the Library, Programming with the Library
@c @section Initialization and Closing of Calls to @code{liba2ps}

@c @deftypefun {struct a2ps_job *} a2ps_job_new (void)
@c Build a new storage unit for the library.
@c @end deftypefun


@c @deftypefun void a2ps_read_sys_config (struct a2ps_job * @var{job})
@c Set @var{job} with the default settings defined in the configuration
@c file of the system.
@c @end deftypefun


@c @deftypefun void a2ps_read_config (struct a2ps_job * @var{job}, char * @var{path}, char * @var{filename})
@c Set @var{job} with the default settings defined in the configuration
@c file @file{@var{path}/@var{filename}}.  @var{path} can be @code{NULL},
@c @var{filename} cannot.
@c @end deftypefun


@c @node  Print Jobs, File Jobs, Initialization of liba2ps, Programming with the Library
@c @section Print Jobs
@c A print job should be seen as associated to a single output.

@c @deftypefun void a2ps_open_output_session (struct a2ps_job * @var{job})
@c Initialize @var{job} for a new print job.
@c @end deftypefun


@c @deftypefun void a2ps_close_output_session (struct a2ps_job * @var{job})
@c Closes the current print job, and sends the output.
@c @end deftypefun



@c @node File Jobs, Printing Functions, Print Jobs, Programming with the Library
@c @section File Jobs
@c A file job should be seen as a single input.

@c @deftypefun void a2ps_new_input_session (struct a2ps_job * @var{job}, char * @var{name})
@c Create and open a new file job in @var{job}.  @var{name} can be
@c @code{NULL}, in which case its name is defaulted to that of
@c @code{stdin}.
@c @end deftypefun

@c @deftypefun void a2ps_close_input_session (struct a2ps_job * @var{job})
@c End the current input session.
@c @end deftypefun



@c @node Printing Functions,  , File Jobs, Programming with the Library
@c @section Printing Functions
@c These are the functions to be used to send content to @code{liba2ps}.

@c @deftypefun void a2ps_print_char (struct a2ps_job * @var{job}, unsigned char @var{c}, face_t @var{face})
@c Print the char @var{c} in @var{face} in @var{job}.
@c @end deftypefun

@c @deftypefun void a2ps_print_string (struct a2ps_job * @var{job}, unsigned char * @var{string}, face_t @var{face})
@c Print the @code{C} string @var{string} in @var{face} in @var{job}.
@c @end deftypefun


@c @deftypefun void a2ps_print_buffer (struct a2ps_job * @var{job}, unsigned char * @var{buffer}, size_t len, face_t @var{face})
@c Print the @var{len} first characters contained in @var{buffer} with
@c @var{face} into @var{job}.
@c @end deftypefun


@c  #####
@c #     #   ####   #    #   #####  #####      #    #####    ####
@c #        #    #  ##   #     #    #    #     #    #    #  #
@c #        #    #  # #  #     #    #    #     #    #####    ####
@c #        #    #  #  # #     #    #####      #    #    #       #
@c #     #  #    #  #   ##     #    #   #      #    #    #  #    #
@c  #####    ####   #    #     #    #    #     #    #####    ####

@node Contributions
@chapter Contributions

This chapter documents the various shell scripts or other tools that are
distributed with the @pack{} package, but are not @pack{} itself.  The
reader should also look at the documentation of @code{Ogonkify}
(@pxref{top,,Overview,ogonkify,Ogonkify manual}), written by Juliusz
Chroboczek.

@menu
* card::                        Printing Reference Cards
* fixps::                       Fixing Some Ill Designed PostScript Files
* fixnt::                       Fixing Microsoft NT PostScript Files
* pdiff::                       Produce Pretty Comparison of Files
* psmandup::                    Printing Duplex on Simplex Printers
* psset::                       Inserting calls to setpagedevice
@end menu

@c @node a2ps Emacs mode, card, Contributions, Contributions
@c @section @pack{} Emacs mode
@c FIXME: Document me.

@node card
@section @code{card}
Many users of @pack{} have asked for a reference card, presenting a
summary of the options.  In fact, something closely related to the
output of @samp{a2ps --help}.

The first version of this reference card was a PreScript file
(@pxref{PreScript}) to be printed by @pack{}.  Very soon a much better
scheme was found: using a style sheet to pretty print directly the
output of @samp{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 @samp{--help}-like option.


@menu
* Invoking card::               Command Line Interface
* Caution when Using card::     card runs commands
@end menu

@node Invoking card
@subsection Invoking @code{card}

@example
card [@var{options}] @var{applications} [-- @var{@pack{}-options}]
@end example

@noindent
@code{card} is a shell script which tries to guess how to get your
@var{applications}' help message (typically by the options @samp{--help}
or @samp{-h}), and pretty prints it thanks to @pack{} (or the content of
the environment variable @samp{A2PS} if it is set).
@var{@pack{}-options} are passed to @pack{}.

Supported options are:

@defvr {Option} -h
@defvrx {Option} -@b{-}help
print a short help message and exit successfully.
@end defvr

@defvr {Option} -V
@defvrx {Option} -@b{-}version
report the version and exit successfully.
@end defvr

@defvr {Option} -q
@defvrx {Option} -@b{-}quiet
@defvrx {Option} -@b{-}silent
Run silently.
@end defvr

@defvr {Option} -D
@defvrx {Option} -@b{-}debug
enter in debug mode.
@end defvr

@defvr {Option} -l @var{language}
@defvrx {Option} -@b{-}language=@var{language}
specify the language in which the reference card should be printed.
@var{language} should be the symbol used by @code{LC_ALL} etc.
(such as @samp{fr}, @samp{it} etc.).

If the @var{applications} don't support internationalization,
English will be used.
@end defvr

@defvr {Option} -@b{-}command=@var{command}
Don't try to guess the @var{applications}' way to report their
help message, but rather use the call @var{command}.
A typical example is
@example
card --command="cc -flags"
@end example
@end defvr

It is possible to give options to @pack{} (@pxref{Options}) by
specifying them after @samp{--}.  For instance
@example
card gmake gtar --command="cc -flags" -- -Pdisplay
@end example

@noindent
builds the reference card of @code{GNU make}, @code{GNU tar} (automatic
detection of @samp{--help} support), and @code{cc} thanks to
@samp{-flags}.


@node Caution when Using card
@subsection Caution when Using @code{card}

Remember that @code{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 @samp{-h} etc., beware of the result.

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


@node fixps
@section @code{fixps}

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

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

@menu
* Invoking fixps::              Command Line Interface
@end menu

@node Invoking fixps
@subsection Invoking @code{fixps}

@example
fixps [@var{options}] [@var{file}]
@end example

@noindent
sanitize the PostScript @var{file} (or of the standard input if no
@var{file} is given, or if @var{file} is @samp{-}).

Supported options are:

@defvr {Option} -h
@defvrx {Option} -@b{-}help
Print a short help message and a list of the fixes that are
performed.  Exit successfully.
@end defvr

@defvr {Option} -V
@defvrx {Option} -@b{-}version
report the version and exit successfully.
@end defvr

@defvr {Option} -D
@defvrx {Option} -@b{-}debug
enter in debug mode.
@end defvr

@defvr {Option} -q
@defvrx {Option} -@b{-}quiet
@defvrx {Option} -@b{-}silent
Run silently.
@end defvr

@defvr {Option} -o @var{file}
@defvrx {Option} -@b{-}output=@var{file}
specify the @var{file} in which is saved the output.
@end defvr

@defvr {Option} -n
@defvrx {Option} -@b{-}no-fix
Don't actually fix the @var{file} but still honor all of the other
options.  In particular, @samp{fixps -qn @var{file}} is equivalent to
@samp{cat @var{file}}.
@end defvr

@defvr {Option} -c
@defvrx {Option} -@b{-}check
@defvrx {Option} -@b{-}dry-run
Don't actually fix the @var{file}: just report the diagnostics.
Contrary to the option @samp{fixps -qc} does absolutely nothing (while
it does take some time to do it nicely).
@end defvr


@defvr {Option} -f
@defvrx {Option} -@b{-}force
Ask @code{ghoscript} for a full rewrite of the @var{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.
@end defvr

@node fixnt
@section @code{fixnt}

@code{fixnt} (see its
@href{http://www.itsm.uni-stuttgart.de/~bauer/fixnt.html}, home page) is
maintained by @email{bauer@@itsm.uni-stuttgart.de, Holger Bauer} and
@email{rath@@itsm.uni-stuttgart.de, 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).

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

@menu
* Invoking fixnt::              Command Line Interface
@end menu

@node Invoking fixnt
@subsection Invoking @code{fixnt}

@example
fixnt < @samp{file.ps}
@end example

@noindent
sanitize the PostScript file @var{file.ps} and produce the result on
the standard output.

@node pdiff
@section @code{pdiff}

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

@menu
* Invoking pdiff::              Command Line Interface
@end menu

@node Invoking pdiff
@subsection Invoking @code{pdiff}

@example
pdiff [@var{options}] @var{file-1} @var{file-2} [-- @var{@pack{}-options}]
@end example

@noindent
make a pretty comparison between @var{file-1} and @var{file-2}.
@var{@pack{}-options} are passed to @pack{}.

Supported options are:

@defvr {Option} -h
@defvrx {Option} -@b{-}help
print a short help message and exit successfully.
@end defvr

@defvr {Option} -V
@defvrx {Option} -@b{-}version
report the version and exit successfully.
@end defvr

@defvr {Option} -q
@defvrx {Option} -@b{-}quiet
@defvrx {Option} -@b{-}silent
Run silently.
@end defvr

@defvr {Option} -D
@defvrx {Option} -@b{-}debug
enter in debug mode.
@end defvr

@defvr {Option} -w
@defvrx {Option} -@b{-}words
Look for words differences (default).  White space differences are not
considered.
@end defvr

@defvr {Option} -l
@defvrx {Option} -@b{-}lines
Look for lines differences.
@end defvr

It is possible to give options to @pack{} (@pxref{Options}) by
specifying them after @samp{--}.  For instance
@example
pdiff COPYING COPYING.LIB -- -1 -P display
@end example

@noindent
Compares the files @file{COPYING} and @file{COPYING.LIB}, and prints it
on the printer @code{display} (usually @code{Ghostview} or @code{gv}).

@node psmandup
@section @code{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 @code{psmandup}.

@menu
* Invoking psmandup::           Command Line Interface
@end menu

@node Invoking psmandup
@subsection Invoking @code{psmandup}

@example
psmandup [@var{options}] [@var{file}]
@end example

@noindent
produce a manual duplex version of the PostScript @var{file} (or of the
standard input if no @var{file} is given, or if @var{file} is
@samp{-}). Once the first half is printed, put the sheet stack in the
manual feed tray for the second half@footnote{Many people seem to ignore
that you can insert @strong{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 @samp{--back} to recover the
second half.

Supported options are:

@defvr {Option} -h
@defvrx {Option} -@b{-}help
print a short help message and exit successfully.
@end defvr

@defvr {Option} -V
@defvrx {Option} -@b{-}version
report the version and exit successfully.
@end defvr

@defvr {Option} -q
@defvrx {Option} -@b{-}quiet
@defvrx {Option} -@b{-}silent
Run silently.
@end defvr

@defvr {Option} -D
@defvrx {Option} -@b{-}debug
enter in debug mode.
@end defvr

@defvr {Option} -o @var{file}
@defvrx {Option} -@b{-}output=@var{file}
specify the @var{file} in which is saved the output.
@end defvr

@defvr {Option} -n
@defvrx {Option} -@b{-}no-fix
@code{psmandup} will fail on ill designed PostScript (well, actually the
psutils will).  To avoid this, by default the PostScript file is
sanitized by @code{fixps}.

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

@defvr {Option} -f
@defvrx {Option} -@b{-}front
Output only the front pages, with no special PostScript feature request.
@end defvr

@defvr {Option} -b
@defvrx {Option} -@b{-}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.
@end defvr

@code{psmandup} assumes the printer is Level 2, and supports manual
feeding.  The @var{file} should be reasonably sane, otherwise
@code{psmandup} fails miserably.

Typical use is
@example
psmandup file.ps | lp
@end example

@noindent
or can be put into @pack{}' printer commands (@pxref{Your Printers}).

@node psset
@section @code{psset}

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

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

@menu
* Invoking psset::              Command Line Interface
@end menu

@node Invoking psset
@subsection Invoking @code{psset}

@example
psset [@var{options}] [@var{file}]
@end example

@noindent
produce a version of the PostScript @var{file} (or of the standard input
if no @var{file} is given, or if @var{file} is @samp{-}) that makes
protected calls to the PostScript operator @code{setpagedevice}.
Typical use is making @var{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 @samp{-Sfoo:bar}.

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

@c I am not sure people really need to know this.
@c Because they have to protect themselves, the @code{PSUtils} hide the
@c PostScript operator @code{setpagedevice}.  Because @code{psset} needs
@c this operator, it knows how to fool the @code{PSUtils}.  Therefore you
@c should be aware that it is much safer to run the @code{PSUtils} before
@c @code{psset}.

Supported options are:

@defvr {Option} -h
@defvrx {Option} -@b{-}help
Print a short help message and exit successfully.
@end defvr

@defvr {Option} -V
@defvrx {Option} -@b{-}version
report the version and exit successfully.
@end defvr

@defvr {Option} -D
@defvrx {Option} -@b{-}debug
enter in debug mode.
@end defvr

@defvr {Option} -q
@defvrx {Option} -@b{-}quiet
@defvrx {Option} -@b{-}silent
Run silently.
@end defvr

@defvr {Option} -o @var{file}
@defvrx {Option} -@b{-}output=@var{file}
specify the @var{file} in which is saved the output.
@end defvr

@defvr {Option} -n
@defvrx {Option} -@b{-}no-fix
@code{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 @code{fixps}.

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

@defvr {Option} -S @var{key}:@var{value}
@defvrx {Option} -@b{-}setpagedevice=@var{key}:@var{value}
Insert a @code{setpagedevice} call setting @var{key} to @var{value}.
Multiple values accumulate.  Lists of requests separated with @samp{;}
are valid (e.g., @samp{-SDuplex:true;Tumble:false}).
@end defvr

@defvr {Option} -a @var{page}
@defvrx {Option} -@b{-}at=@var{page}
Specify the page where the @code{setpagedevice} call should be done.
The @var{page} 0, which is the default, corresponds to the @samp{Setup}
section of the document.  More precisely, the insertion is performed at
the end of the @samp{Setup} section, so that if there are multiple calls
to @code{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 @var{page}.
@end defvr

@defvr {Option} -m
@defvrx {Option} -@b{-}manualfeed
Alias for @samp{-SManualFeed:true}, i.e., the request to print using the
manual feed tray.
@end defvr

@defvr {Option} -s
@defvrx {Option} -@b{-}simplex
Alias for @samp{-SDuplex:false}, i.e., force simplex printing.
@end defvr

@defvr {Option} -d
@defvrx {Option} -@b{-}duplex
Alias for @samp{-SDuplex:true;Tumble:false}, i.e., the request to print
in duplex mode, binding along the long edge of the paper.
@end defvr

@defvr {Option} -t
@defvrx {Option} -@b{-}tumble
Alias for @samp{-SDuplex:true;Tumble:true}, i.e., duplex printing
such that binding should happen on the short edge of the medium.
@end defvr

@c #######    #     #####
@c #         # #   #     #
@c #        #   #  #     #
@c #####   #     # #     #
@c #       ####### #   # #
@c #       #     # #    #
@c #       #     #  #### #

@node FAQ
@chapter Frequently asked questions

@c @section Security issues
@c @strong{Note.}  I am not really aware of security problems.  I am just
@c making assumptions upon my poor knowledge, so if somebody sees things
@c that should be reported here, or problem I'm not aware of, please
@c contact us so that this note gets extended or fixed.

@c One should understand that any program that has not been written to be
@c secure is never secure. It is of course the case of @pack{}.

@c Do not panic, there are no reason for you to worry.  Nevertheless we can
@c yet imagine ways to obtain illegal rights thanks to some features of
@c @pack{}, especially virtual printers.

@c If @pack{} is run by root, then the files it may create are owned by
@c root.  This can for instance happen if you install @pack{} as one of
@c @code{lp} or @code{lpr} filter.

@c Then, if one of the virtual printer creates say a shell script, it is
@c owned by root too.  With just a bit of habit, it should not be difficult
@c then to access privileged access to the system.

@c In what conditions could it happen?  @strong{Only} if there are some
@c printers defined in the system configuration file of @pack{}, or in
@c root's home directory @file{.a2ps/a2psrc}.  Hence, make sure to carefully
@c write the commands to the preconfigured printers.

@c As you can see, this is quite science fiction, nevertheless, you might
@c wanted to know.


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.

@menu
* Why Does ...?::               Questions on Error
* How Can I ...?::              a2ps' How-To
* Please tell me...::           Existential Questions on a2ps
@end menu

@node Why Does ...?
@section Why Does...?

Error related questions.

@menu
* It Prints Nothing::           The printer issues nothing
* It Prints in Simplex::        While I asked for Duplex
* It Prints in Duplex::         While I asked for Simplex
* It Does Not Fit on the Paper::  Some parts are missing
* It Prints Junk::              Random characters
* It Says my File is Binary::   And refuses to print it
* It Refuses to Change the Font Size::
@end menu

@node  It Prints Nothing
@subsection Why Does it Print Nothing?

@quotation
@i{@pack{} works OK, but the printer prints nothing.}
@end quotation

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

First, @strong{check that the printer received what you sent}.  @pack{}
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 @samp{-S}, @samp{--setpagedevice} (@pxref{Page Device Options})
and @samp{--statusdict} (@pxref{Statusdict Options}).

If the trouble persists, please try again but with the option
@samp{--debug} (a PostScript error handler is downloaded), and then send
us:
@enumerate
@item
the input file that gives problems

@item
the output file created by @pack{} @strong{with the option @samp{--debug}}

@item
the error message that was printed.
@end enumerate


@node It Prints in Simplex
@subsection Why Does it Print in Simplex?

@quotation
@i{Though I ask @pack{} to print Duplex via @samp{--sides}, the job is
printed Simplex.}
@end quotation

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

So you need to
@enumerate
@item
specify that you want Duplex mode: @samp{-s2},

@item
remove by hand the standardized call to the Duplex feature:
@samp{-SDuplex},

@item
add the non standard call to Duplex.  Try
@samp{--statusdict=setduplexmode:true}.
@end enumerate

Since this is painful to hit, a User Option (@pxref{Your Shortcuts})
should help.


@node It Prints in Duplex
@subsection Why Does it Print in Duplex?

@quotation
@i{Though I ask @pack{} to print Simplex via @samp{--sides}, the job is
printed Duplex.}
@end quotation

Actually when you require Simplex, @pack{} issues nothing, for portability
reasons.  Hence, if your printer is defaulted to Duplex, the job will be
Duplexed.  So you have to force @pack{} to issue the Simplex request with
@samp{-SDuplex:false}.  The user options @samp{-=s1} and
@samp{-=simplex} have names easier to remember.

In the next version of @pack{} this kind of portability problems will be
fixed in a user friendly way.


@node It Does Not Fit on the Paper
@subsection Why Does it Not Fit on the Paper?

@quotation
@i{When I print text files with @pack{}, it prints beyond the frame of
the paper.}
@end quotation

You are most probably printing with a bad medium, for instance using A4
paper within @pack{}, while your printer uses Letter paper.  Some jet
printers have a small printable area, and @pack{} may not expect it.  In
both case, read @ref{Sheet Options}, option @samp{--medium} for more.


@node It Prints Junk
@subsection Why Does it Print Junk?

@quotation
@i{What I get on the printer is long and incomprehensible.  It does not
seem to correspond to what I wanted to print.}
@end quotation

You are probably printing a PostScript file or equivalent.  Try to print
with @samp{-Z}: @pack{} will try to do his best to find what is the
program that can help you (@pxref{Your Delegations}).  In case of doubt,
don't hesitate to save into a file, and check the content with
@code{Ghostview}, or equivalent:
@example
@cartouche
$ a2ps my_weird_file -Z -o mwf.ps
$ gv mwf.ps
@end cartouche
@end example

@noindent
If your @pack{} is correctly installed, you can use the @samp{display}
fake-printer:
@example
@cartouche
$ a2ps my_weird_file -Z -P display
@end cartouche
@end example

If it is incorrect, ask for help around you.

@node It Says my File is Binary
@subsection Why Does it Say my File is Binary?

@quotation
@i{@pack{} complains that my file is binary though it is not.}
@end quotation

There are several reasons that can cause @pack{} to consider a file is
binary:
@itemize @minus
@item
there are many non printable characters in the file.  Then you need to
use the option @samp{--print-anyway}.

@item
the file is sane, composed of printable characters.  Then it is very
likely that @code{file(1)} said the type of the file is @samp{data}, in
which case @pack{} prefers not to print the file.  Then you can either:
@itemize @minus
@item
specify the type of the file, for instance @samp{-Eplain};

@item
specify to print in any case, @samp{--print-anyway};

@item
remove the annoying rule from the system's @file{sheets.map}:
@example
binary: <data*>
@end example

@item
insert in your own @file{~/.a2ps/sheets.map} a rule that overrides that
of the system's @file{sheets.map}:
@example
@i{# Load the system's sheets.map}
include(/usr/local/share/a2ps/sheets/sheets.map)

@i{# Override the rule for files with type `data' according to file(1)}
plain: <data*>
@end example

But this is not very good, since then this rule is always the first
tested, which means that any file with type @samp{data} according to
@code{file(1)} will be printed in @samp{plain} style, even if the file
is called @file{foo.c}.

@item
if your files can be recognized, insert a new rule in a
@file{sheets.map}, such as
@example
@i{# file(1) says it's data, but it's pure text}
plain:   /*.txx/
@end example

@end itemize

@end itemize

@node It Refuses to Change the Font Size
@subsection Why Does it Refuse to Change the Font Size

@quotation
@emph{@pack{} does not seem to honor @code{--font-size}
 (or @samp{--lines-per-page}, or @samp{--chars-per-line}).}
@end quotation

This is probably because you used @samp{-1}..@samp{-9} after the
@samp{--font-size}.  This is wrong, because the options
@samp{-1}..@samp{-9} set the font size (so that there are 80 characters
per lines), and many other things (@xref{Page Options}, option
@samp{--font-size}).

Hence @samp{a2ps --font-size=12km -4} is exactly the same thing as
@samp{a2ps -4}, but is different from @samp{a2ps -4 --font-size=12km}.
Note that the `pure' options (no side-effects) to specify the number of
virtual pages are @samp{--columns} and @samp{--rows}.

@c -----------------------------How can I ? ------------------------------
@node How Can I ...?
@section How Can I ...?

A mini how-to on @pack{}.

@menu
* Leave Room for Binding::      Specifying Margins
* Print stdin::                 Using a2ps in a pipe chain
* Change the Fonts::            Tired of Courier?
* The Old Option -b?::          Printing in Bold
* Pass Options to lpr::         Disable the banner
* Non PostScript Printers::     Using GhostScript
* Man Pages with Underlines::   Now it Prints With Italics
@end menu


@node Leave Room for Binding
@subsection How Can I Leave Room for Binding?
The option @samp{--margin[=@var{size}]} is meant for this.  See
@ref{Sheet Options}.

@node Print stdin
@subsection How Can I Print @code{stdin}?
@pack{} prints the standard input if you give no file name, or if you gave
@samp{-} as file name.  Automatic style selection is of course much
weaker: without the file name, @pack{} can only get @code{file(1)}'s
opinion (@pxref{Style Sheet Files}).  In general it means most
delegations are safe, but there will probably be no pretty-printing.

@samp{You} can supply a name to the standard input
(@samp{--stdin=@var{name}}) with which it could guess the language.

@node Change the Fonts
@subsection How Can I Change the Fonts?
@xref{Designing PostScript Prologues}, for details.  Make sure that all
the information @pack{} needs is available (@pxref{Font Files}).

@node The Old Option -b?
@subsection How Can I Simulate the Old Option @samp{-b}?
By the past, @pack{} had an option @samp{-b} with which the fonts were
bold.  Since now the fonts are defined by prologues (@pxref{Designing
PostScript Prologues}) this option no longer makes sense.  A replacement
prologue is provided: @samp{bold}.  To use it, give the option
@samp{--prologue=bold}.

@node Pass Options to lpr
@subsection How Can I Pass Options to @samp{lpr}
@cindex banner
@vindex lp.options
@quotation
@i{How can I tell @code{a2ps} to ask @code{lpr} no to print the banner?}

@i{How can I pass specific options to @code{lp}?}
@end quotation

If your @samp{Printer:} fields in the configuration files were properly
filled (@pxref{Your Printers}), you can use the variable
@samp{lp.options} to pass options to @code{lpr} (or @code{lp}, depending
on your environment):

@example
a2ps -Dlp.options="-h -s" -P printer
@end example

@noindent
You can also define @samp{lp.options} once for all, @xref{Defining
Variables}.

Finally, you can use @samp{Printer:} several times to reach a printer
with different @code{lpr} options.


@node Non PostScript Printers
@subsection How Can I Print on Non PostScript Printers?

@quotation
@i{I use @pack{} at work and wish to use it at home, but my printer is
not PostScript.  How can I do?}
@end quotation

@code{Ghostscript} might be the tool you need (@pxref{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 @code{Ghostscript} documentation for a precise
description of the tuning you need.

Basically, the first step you need is to achieve to call
@code{Ghostscript} in a pipe chain.  In other words, try to find out the
right arguments @code{Ghostscript} needs in order to print with a
command like this:
@example
$ cat file.ps | gs @var{more arguments}
@end example

In general it is the same command as for calling @code{Ghostscript} with
a filename, except that the file name to use is @samp{-}:
@example
$ cat file.ps \
  | gs -q -dNOPAUSE -sDEVICE=deskjet -sOutputFile=- - -c quit\
  | lp -d@var{printer-name}
@end example

Once it works, it is then easy to settle the right @code{Printer:} line
in your configuration file (@pxref{Your Printers}).  For instance:
@example
Printer: djet \
  | gs -q -dNOPAUSE -sDEVICE=deskjet -sOutputFile=- - -c quit\
  | lp -d djet
@end example

@email{scancm@@biobase.dk, Christian Mondrup} uses @pack{} under Windows
with a non PostScript printer.  He uses:
@example
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
@end example

@node Man Pages with Underlines
@subsection How Can I Print Man Pages with Underlines

@quotation
@i{By the past, when I printed a man page with @pack{}, it used
underlines, but now it uses italics.  I want underlines back!}
@end quotation

Use @samp{a2ps --pro=ul}.


@c -------------------------- Please Tell me ? ------------------------------
@node Please tell me...
@section Please tell me...

Wondering something?

@menu
* Is a2ps Y2K compliant?::      Printing dates in short format
* The Options Have Changed::    Respect The Users
* Why not using yacc::          Why Using Style Sheets
* Why do you not use mozilla::  Using remote commands
@end menu

@node Is a2ps Y2K compliant?
@subsection Is @pack{} Y2K compliant?

The famous Y2K@footnote{Year 2000.} problem...

Yes, @pack{} 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 @samp{100} instead of @samp{00}): @samp{%D}, @samp{%W},
@samp{$D}, @samp{$W}.

Nevertheless, please note that if you required a two digit year, expect
to have @samp{Jan 1st, 00} someday.  @strong{You} are responsible of the
format you want for the date: @xref{Escapes}.

@node The Options Have Changed
@subsection Why Have the Options Changed?

@quotation
@i{The options of this @pack{} are not the same as in the previous versions.}
@end quotation

True.  But the old scheme (up to version 4.6.1) prevented us from
offering more options.  We @strong{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 @pack{} configuration
files or in shell scripts), @strong{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.

@node Why not using yacc
@subsection Why not having used @code{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 @pack{} 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 @pack{} 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, @code{PreScript} gives the possibility to have on the one
hand a syntactic parser which would produce @code{PreScript} code, and
on the other hand, @pack{}, 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.
@c FIXME:  (@pxref{Programming with the Library}).

@node Why do you not use mozilla
@subsection 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 @code{saveas()} does not exist. And we
cannot save open file as postscript file.


@c  #####
@c #     #  #        ####    ####    ####     ##    #####    #   #
@c #        #       #    #  #       #        #  #   #    #    # #
@c #  ####  #       #    #   ####    ####   #    #  #    #     #
@c #     #  #       #    #       #       #  ######  #####      #
@c #     #  #       #    #  #    #  #    #  #    #  #   #      #
@c  #####   ######   ####    ####    ####   #    #  #    #     #

@node Glossary
@appendix Glossary
This section settles some terms used through out this document, and
provides the definitions of some terms you probably want to know about.

@table @dfn

@item Adobe
@cindex 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.

@item AFM file
@cindex AFM
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.

@item Charset
@cindex Charset
@itemx Code Set
@cindex Code Set
Cf. Encoding.

@item Delegate
@cindex Delegate
Another filter (application) which @pack{} may call to process some files.
This feature is especially meant for page description files (@pxref{Your
Delegations}).

@item DSC
@cindex DSC
@itemx Document Structuring Conventions
@cindex 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:
@table @asis
@item 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 @code{psnup}, @code{psselect} etc.) can post process
PostScript files.

@item 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.
@end table

The DSC are edited by Adobe.  A document which respects them is said to
be @dfn{DSC conformant}.

@pack{} follows all the DSC.


@item Duplex
@itemx DuplexTumble
@itemx DuplexNoTumble
@cindex Duplex
@cindex DuplexTumble
@cindex DuplexNoTumble
To print @dfn{Duplex} is to print double-sided.  There are two ways to
print Duplex depending whether the second face is printed upside-down or
not:
@table @dfn
@item 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).

@item DuplexNoTumble
DuplexNoTumble corresponds to binding along the long edge of the medium.
A typical case is when printing one-up.
@end table


@item Encoding
@cindex 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 @ref{What is an Encoding}.

@item @code{Ghostscript}
@item @code{gs}
@cindex @code{Ghostscript}
@cindex @code{gs}
@href{http://www.cs.wisc.edu/~ghost/index.html, @code{Ghostscript}},
@code{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:
@table @emph
@item Displaying
It can be used either to view PostScript files (in general thanks to a
graphic interface such as @code{Ghostview} or @code{gv} ...).

@item Converting
To may useful languages/formats: PDF, rewriting in portable PostScript
or Encapsulated PS etc.

@item Translating
to a printer dedicated language, e.g., PCL.  In particular, thanks to
@code{ghostscript}, you may print PostScript files on non PostScript
printers.
@end table

@item Face
@cindex Face
A virtual style given to some text.  For instance, @emph{Keyword},
@emph{Comment} are faces.

@item Headings
@cindex Headings
Everything that goes around the page and is not part of the text body.
Typically the title, footer etc.

@item Key
@cindex Key
Many objects used in @pack{}, such as encodings, have both a key and a name.
The word @dfn{name} is used for a symbol, a label, which is only meant
to be nice to read by a human.  For instance @samp{ISO Latin 1} is a name.
@pack{} never uses a name, but the key.

A @dfn{key} is the identifier of a unique object.  This is information
that @pack{} processes, hence, whenever you need to specify an object to
@pack{}, use the key, not its name.  For instance @samp{latin1} is the
unique identifier of the @samp{ISO Latin 1} encoding.

@item Logical page
@cindex Logical page
Cf. Virtual page.

@item lhs
@itemx left hand side
See @dfn{P-rule}.

@item Medium
@cindex 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.

@item Name
See @dfn{Key}.

@item Page
@cindex Page
A single side of a sheet.

@item Page Description Language
@cindex Page Description Language
A language that describes some text (which may be enriched with
pointers, pictures etc.) and its layout.  @code{HTML}, PostScript,
@LaTeX{}, @code{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.

@item PCL
@cindex PCL
FIXME:

@item PFA file
@cindex PFA file
PostScript Font in ASCII format.  This file can be directly down loaded
to provide support for another font.


@item PFB file
@cindex 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.

@item PostScript
@cindex PostScript
@dfn{PostScript} is a page description language designed for
@emph{Raster output devices}.  It is even more powerful than that:
unlike to @code{HTML}, or @code{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 @code{Ghostscript}.  @code{PDF} has been
invented by Adobe to remedy these problems).

PostScript is a trademark of Adobe Systems Incorporated.

@item PPD file
@cindex PPD file
@itemx 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.

@item ProcSet
@cindex ProcSet
Set of (PostScript) procedures.

@item Prologue
@cindex 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
@dfn{prologue}, and the second, the @dfn{script}.

@item P-rule
@cindex P-rule
Pretty printing rule.  It is composed of a @dfn{left-hand side},
(@dfn{lhs} for short), and a @dfn{right-hand side}, (@dfn{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.
@xref{P-Rules}, for more semantical details, and see @ref{Syntax for the
P-Rules}, for implementation.

@item @code{psutils}
@cindex @code{psutils}
@cindex Angus Duggan
The @href{http://www.dcs.ed.ac.uk/home/ajcd/psutils/index.html,
@dfn{psutils}} is a set of tools for PostScript post processing written
by @href{http://www.dcs.ed.ac.uk/home/ajcd/, Angus Duggan}.  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
@code{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 @code{fix...ps})
to fix typical problems.  @code{fixps} is a collection of recipes on
when to run what @code{fix} tool.

@item Raster Image Processor
@itemx 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.

@item Raster Output Device
@cindex 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 @emph{plot}, i.e., have a pen that they move on the paper.

@item rhs
@itemx right hand side
See @dfn{P-rule}.

@item RIP
See @dfn{Raster Image Processor}.

@item Script
@cindex Script
See @dfn{Prologue}.

@item Sheet
@cindex Sheet
The physical support of the printing: it may support one or two pages,
depending on your printing options.

@item Style sheet
@cindex Style sheet
Set of rules used by @pack{} to give a face to the strings of a
file.  In @pack{}, each programming language which is supported
is defined via one style-sheet.

@item Tumble
@cindex Tumble
See @dfn{Duplex}.

@item Virtual page
@cindex Virtual page
Area on a physical page in which @pack{} draws the content of a file.
There may be several virtual pages on a physical page. (``virtual page''
is the name recommended by Adobe).

@end table

@c #     #
@c #     #     #     ####    #####   ####   #####    #   #
@c #     #     #    #          #    #    #  #    #    # #
@c #######     #     ####      #    #    #  #    #     #
@c #     #     #         #     #    #    #  #####      #
@c #     #     #    #    #     #    #    #  #   #      #
@c #     #     #     ####      #     ####   #    #     #

@node Genesis
@appendix Genesis

Here are some words on @pack{} and its history.

@menu
* History::                     Where does it come from
* Thanks::                      People who really helped
* Translators::                 People who brought support of your tongue
@end menu

@node History
@section History

The initial version was a shell program written by @email{evan@@csli,
Evan Kirshenbaum}.  It was very slow and contained many bugs.

A new version was written in @code{C} by @email{Miguel.Santana@@st.com,
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 @pack{} users in
order to improve it.

From the latest version from Miguel Santana (4.3), Emmanuel Briot
implemented bold faces for keywords in @code{Ada}, @code{C} and
@code{C++}.

From that version, @email{akim@@freefriends.org, Akim Demaille}
generalized the pretty-printing capabilities, implemented more languages
support, and other features.

@node Thanks
@section Thanks
Patrick Andries, from @href{http://www.alis.com/,Alis Technologies inc.}
and Roman Czyborra (see his @href{http://czyborra.com/, home page}),
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 @pack{}.  Without his help, and
the time is devoted to both @pack{} and @code{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 @pack{}.  His comments on both the program
and the documentation are the origin of many pleasant features (such as
@samp{--prologue}).

Alexander Mai provided us with invaluable help in the development.  He
spotted several times subtle bugs in @pack{} and the contributions, he
keeps a vigilant eye on portability issues, he checks and improves the
style sheets, and he maintains a port of @pack{} for OS/2.

Graham Jenkins, with an extraordinary regularity, tortures @pack{} on
weird systems that nobody ever heard of @samp{:)}.  Graham is usually
the ultimate test: if he says I can release @pack{}, I rest reassured
that, yes, this time it @strong{will} compile!  If @pack{} 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 @pack{}.  Of course it doesn't
sound right, yes it sounds a little childish, but we can tell you: we
would @strong{never} have the strength and the faith of building and
maintaining @pack{} without the support of all these guys.

While @pack{} 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!



@node Translators
@section Translators
Some people worked on the translation of @pack{}:
@itemize @minus
@include translators.texi
@end itemize


@c  #####
@c #     #   ####   #####    #   #     #    #    #   ####
@c #        #    #  #    #    # #      #    ##   #  #    #
@c #        #    #  #    #     #       #    # #  #  #
@c #        #    #  #####      #       #    #  # #  #  ###
@c #     #  #    #  #          #       #    #   ##  #    #
@c  #####    ####   #          #       #    #    #   ####

@node   Copying
@appendix Copying
@cindex Copying

   The subroutines and source code in the @pack{} package are
"free"; this means that everyone is free to use them and free to
redistribute them on a free basis.  The @pack{}-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 @pack{}, 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 @pack{}-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
@pack{}.  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 @pack{} are found in the General
Public Licenses that accompany them.

@node Concept Index
@unnumbered Concept Index

@printindex cp

@c This is not really needed yet.
@c @node Function Index,  , Concept Index, Top
@c @unnumbered Function Index

@c @printindex fn

@contents
@bye


@c Local variables:
@c ispell-local-dictionary: "american"
@c texinfo-column-for-description: 32
@c End: