@macro pack
a2ps
@dircategory Printing utilities @direntry * a2ps:: ASCII to PostScript converter * PreScript: (a2ps) PreScript Input language for a2ps
Copyright (C) 1988, 89, 90, 91, 92, 93 Miguel Santana
Copyright (C) 1995, 96, 97 Akim Demaille, Miguel Santana
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 Foundation.
This document describes @pack version 4.7.20. The latest versions may be found on (decrease order of service quality):
@pack formats named files for printing in a PostScript printer; if no file is given, @pack reads from the standard input. The output may be sent to the printer or to the standard output or saved into a file.
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.
Compared to the previous versions, @pack version 4.7.20 provides:
GNU enscript
(see section Command line options);
@pack is not a powerful syntactic pretty-printer: it just handles lexical structures, i.e., if in your favorite language
IF IF == THEN THEN ELSE := IF ELSE ELSE := THEN
is legal, then @pack is not the tool you need. Indeed @pack
just looks for some keywords, or some sequences, i.e., sequences
of characters which are opened by a given marker, and ended the same
way. For instance in C, the comments are opened by `/*',
and ended by `*/'.
It is for the same reason that you can't expect @pack to highlight
the function definitions in C.
This section settles some terms that are going to be used through out this document.
Calling @pack is fairly simple:
a2ps Options... Files...
@pack uses GNU getopt, hence:
Here after bool stands for boolean. It is considered as true (i.e. setting the option on), if bool is `yes', or `1'; as false if it equals `no' or `0'; and raise an error otherwise. The corresponding short option takes no arguments, but corresponds to a positive answer.
file does: it
returns for each file the language in which @pack believes the
file is written. This can be very useful on broken systems to
understand why a file is written with a bad style sheet
(see section Automatic style).
--interpret=no is given.
These are the options through which you may define the information you want to see all around the pages.
All these options support text as an argument, which is composed of plain strings and meta sequences. See section Meta sequences for details.
a2ps -DDuplex:true report.preprints file `report.pre' in duplex (two side) mode. Page device operators are implementation dependent but they are standardized. See section Page device options for details.
statusdict operators and variables are implementation dependent;
see printer's documentation for details. See section Statusdict options for
details.
If no value is given, key is removed from the definitions.
With a single colon, pass a call to an operator, for instance:
a2ps -Ssetpapertray:1 quicksort.cprints file `quicksort.c' by using paper from the paper tray 1 (assuming that printer supports paper tray selection). With teo colons, define variable key to equal value. For instance:
a2ps -Spapertray::1 quicksort.cproduces
/papertray 1 defin the PostScript.
java in which case strong
comments are the so called documentation comments, or in SDL for
which some graphical editors pollutes the specification with internal
data as comments.
Note that the current implementation is not satisfactory: some undesired
blank lines remain. This is planed to be fixed.
Headers, footers, titles and the water mark are strings in which some meta sequences are later replaced by their actual values. In general `%' are related to general information, while `$' meta sequences are related to the current file.
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 meta sequences (e.g., `$L', `$l').
Currently @pack support the following meta sequences:
strftime(3) function.
strftime(3) function.
mail-folder
style, tag 1 is the title of the mail, and tag 2 its author.
All format directives can also be given in format
escape width directive
where width specifies the width of the column to which the escape is printed. For example, escape `$5%' will expand to something like ` 12'. If the width is negative, the value will be printed left-justified.
Page device is a PostScript level 2 feature that offers an uniform interface to control printer's output device. a2ps protects all page device options inside an if block so they have no effect in level 1 interpreters. Although all level 2 interpreters support page device, they do not have to support all page device options. For example some printers can print in duplex mode and some can not. Refer to the documentation of your printer for supported options.
Here are some usable page device options which can be selected with the `-D' option (`--setpagedevice'). For a complete listing, see PostScript Language Reference Manual: section 4.11 Device Setup.
Collate boolean
Duplex boolean
ManualFeed boolean
OutputFaceUp boolean
Tumble boolean
The statusdict is a special storage entity in PostScript (called
a dictionnary), in which some variables and operators determine
the behavior of the printer. As for page device, those variables are
device dependent: refer to the documentation of your printer for
supported options.
Here are some statusdict definitions in which you might be interested:
manualfeed boolean
@pack reads several files before the command line options. In the order, they are:
In these files, empty lines and lines starting with `#' are comments. All other lines have the format:
Options: --right-title='Page $p'is wrong. Write
Options: '--right-title=Page $p'
Promela programmers use the suffix `pr' for their
file, though @pack hard codes `pr' to SDL. To override this
rule, use:
Pattern: *.pr promela
@pack uses several files: its PostScript prologue, encoding related files, and such. @pack looks for these files in the following path:
$HOME/.a2ps:/usr/local/share/a2ps
You may change this default path with the environment variable
A2PS_LIBRARY.
If you plan to define yourself some header files for @pack (option `--prologue'), they should be in one of those directory, with a `.pro' suffix.
@pack provides some Native Language Support, that is speaking your mother tongue. It uses two special features wrt non-English languages: on the one hand, the interface between you and it, and on the other hand, the format of the dates and times.
To use these features, you may set your environment variable LANG
to the standard code representing your language (currently `fr' for
French and `it' for Italian).
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 which awk and such.
So if you just want messages and time format to be localized, then define:
set LC_MESSAGES=fr set LC_TIME=fr export LC_MESSAGES export LC_TIME
Note that the `make install' must have been done in order to have NLS support.
Please, help us internationalizing @pack{}. If you want to do a profound translation work, contact us. But we need in urgency small pieces of information: everything that appears on page.
This includes the standard date and time format, the word for `page' etc. A walk through the file `po/a2ps.pot' will give you the information you need.
The following exit values are returned:
The main feature of @pack is its pretty-printing capabilities. Two different levels of pretty printing can be reached:
Many things cannot be done with @pack{}: see section Syntactic limits for details.
The heuristic @pack uses to find out in which language is written a file is fairly simple:
file(3) its opinion on the file. If the answer looks
like a language, @pack trusts file, but for the C,
since file has the bad habit to consider that quite everything is
written in C.
Two things are to retain from this:
file is wrong on some files, @pack will use bad style
sheets. In this case, do try option `--guess', compare it with the
output of file, and if the culprit is file, go and
complain to your system administrator :-), or fix it by defining
your own filename pattern matching rules (see section Configuration files).
@pack version 4.7.20 supports the following languages:
ada
C
C++
caml (ml)
Claire (cl)
@url{http://www.ens.fr/~laburthe/claire.html}
coq-vernacular (coq)
Common-lisp (lsp)
Eiffel (e)
Fortran (f)
java
lace (ace)
mailfolder (mail)
elm, use `a2ps
-2mgEmail %s'. This style also suits news files.
Modula-3 (m3)
68000
o2c
Oberon
Ora
Pascal (pas)
perl (pl)
PL-SQL
PostScript (ps)
PreScript (pre)
prolog (pro)
promela (pml)
python (py)
Sather (sa)
Scheme (scm)
SDL-88 (sdl)
SDL may be the language for which `--strip-level=2'
is the most useful: it cancels the graphical information left by graphic
editors. Only the pure specification is then printed.
sh
SQL
SQL92
tcl
tk
Unity
Verilog
VHDL
zsh
@pack pretty prints a source file thanks to style sheets, one per language. In the following is described how the style sheets are defined. You may skip this section if you don't care how @pack does this, and if you don't expect to implement new styles.
Every style has a unique name (reported with `--list-features'). It has also a list of abbreviations (which should include usual suffix for the language, such as `e' for the Eiffel language).
Any of the name or abbreviations can be used with option `-E'.
When automatic pretty-printing is enabled, first @pack calls
file to see whether the language is recognizable. Otherwise, the
suffix of the file is compared with every name and abbreviation. On
failure, plain style is used.
@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.
A keyword if recognized, is just written in a special font. A symbol, when recognized, is replaced by the corresponding character in the symbol font. To be recognized, both need to start by a character in the first alphabet and to be immediately followed by a character which does not belong to the second alphabet.
They need not to be preceded and followed by characters belonging to the alphabet. For instance in `caml', `not' is a regular symbol: it represents boolean negation; but in neither `nota' or `notnot', the three first letters represent `not'. On the contrary `<>' always means `not equal', even in `a<>b'.
Both regular and special symbols are transformed only if option `--graphic-symbols' was given.
Sequences are string is a string between two markers. A marker is a fixed string. Typical examples are strings (with usually `"' as opening and closing markers), comments etc. Three fonts are used: one for the initial marker, one for the core of the sequence, and a last one for the final maker.
Escapes are immediately copied when found in a sequence. Their main use is to avoid a sequence from being terminated too soon, e.g., the string `"\""' is legal in C, hence it is necessary to specify in @pack that `\\' and `\"' have to be written has such when in a sequence: they are escapes.
Verbatims are immediately copied wherever met. It has been implemented for ada in which `"'' is the constant character `''. @pack must not understand it as opening of a sequence (first quote), closing of the sequence (second quote), opening of a sequence (third quote). Nor is it possible to specify that `'' is an escape...
If the style is case insensitive, the case does not matter for the keyword, symbol and sequence recognition. Other categories are not concerned by case sensitivity.
To be able to define new style sheets one needs GNU m4. Also,
never update `styles.c' by hand, but its precursor
`styles.c.in'.
There is a couple of things to know about the process. But in anyway,
please use the already defined languages as examples, and see the
prologue of `styles.c.in' where many m4 macros are defined
to ease the implementation. Read also `styles.h' where information
is given on the struct used for the style sheets.
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 C-order is more or less
followed.
For the particular case of the special symbols, note that you may have
to protect the symbols which are prefixed by them. For instance if in
Pascal you define `=' to be a special symbol, you have to
protect the `=' in `:='. Otherwise @pack will see a
`;', written such as, but will transform the `=' in the symbol
you specified. Hence declare `a2_not_symbol(:=)'.
It is possible to specify that a sequence may only begin at the start of a line, prefixing the opening marker with a `^'. If the marker starts with a `\', that character is always ignored (hence `\^' if you need to use `^' without constraint on the position in the line).
A closing marker may require to end on end-of-line. Use `$' to specify this. If the marker is ended by a `\', that caracter is ignored, hence with `money$\', `money$' is closing anywhere on the line.
It is also possible to specify several closing markers, just by putting
them one after the other, for instance (taken for the ada style
sheet):
a2_sequence(procedure , keyword_strong, label, ` is', keyword_strong),
a2_sequence(procedure , keyword_strong, label, ` (', courier),
a2_sequence(procedure , keyword_strong, label, `(', courier),
a2_sequence(procedure , keyword_strong, label, `$', courier),
a2_sequence(procedure , keyword_strong, label, `;', courier),
Please note that:
Please, respect the alphabetical order in which the languages are
introduced. Don't forget to update `STYLE' in `styles.h', and
to add your language in the macro a2_styles at the bottom of
`styles.c.in'.
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: PreScript became an input language for @pack{},
where special font treatments are specified in a LaTeX-like syntax.
The main advantages for using PreScript are:
PreScript
files do compile with LaTeX)
It can be a good candidate for generation of PostScript output (syntactic pretty-printers, generation of various reports etc.).
Every command name begins with a backslash (`\'). If the command uses an argument, it is given between curly braces with no spaces between the command name and the argument.
The main limit on PreScript is that no command can be used inside
another command. For instance, though it is perfectly legal in LaTeX,
the following line will be badly interpreted by @pack{}:
\textbf{Problems using \textit{PreScript} instead of \LaTeX}
The correct way to write this in PreScript is
\textbf{Problems using} \textbi{PreScript} \textbf{instead of} \LaTeX.
Everything from an unquoted % to the end of line is ignored (comments).
PreScript commandsThese commands required arguments.
There is a big menagerie of symbols. To get a list, it is suggested to
print @pack{}'s report about PreScript using the command
line:
a2ps --report=PreScript | a2ps -EPreScript
The reader should be aware that LaTeX is more demanding about special symbols. Most of them must be in so-called math mode, which means that the command must be inside $ signs. For instance, though
If \forall x \in E, x \in F then E \subseteq F.
is perfectly legal in PreScript, it should be written
If $\forall x \in E, x \in F$ then $E \subseteq F$.
for LaTeX. Since in PreScript every `$' is discarded (unless
quoted by a `\'), the second form is also admitted.
`$' is ignored in PreScript for compatibility with LaTeX,
and `%' introduces a comment. Hence they are the only symbols which
have to be quoted by a `\'. The following characters should also be
quoted to produce good LaTeX files, but are accepted by
PreScript: `_', `&', `#'.
Note that inside a command, like \textbf, the quotation
mechanism does not work in PreScript (\textrm{#$%}
writes `#$%') though LaTeX still requires quotation. Hence whenever
special characters or symbols are introduced, they should be at the
outer most level.
There is a general mechanism to avoid special sequences from being interpreted: the commands `\verb+quoted string+', where `+' can be any symbol in `+', `!', `|', `#', `='.
PreScript
Some LaTeX commands have no equivalent in PreScript, but are
simply skipped at compilation time (if immediately followed by an
end-of-line):
Everything between `%%PreScript:skip' and `%%PreScript:piks'
will be ignored in PreScript, so that there can be inserted
command definitions for LaTeX exclusively.
The commands `\textbi' (for bold-italic) and `\textsy' (for symbol) do not exist in LaTeX. They should be defined in the preamble:
%%PreScript:skip
\newcommand{\textbi}[1]{\textbf{\textit{#1}}}
\newcommand{\textsy}[1]{#1}
%%PreScript:piks
There is no way in PreScript to get an automatic numbering.
There is no equivalent to the LaTeX environment enumerate. But
every command beginning by \text is doubled by a command
beginning by `\magic'. @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
\begin{enumerate}
\magicbf{1.}\item First line
\magicbf{2.}\item Second line
\end{enumerate}
will be treated the same way both in PreScript and LaTeX.
`header' and `\footer', are not understood by LaTeX.
Some symbols are available in PreScript but not in LaTeX:
`\Alpha', `\apple', `\Beta', `\carriagereturn', `\Chi', `\Epsilon', `\Eta', `\florin', `\Iota', `\Kappa', `\Mu', `\Nu', `\Omicron', `\omicron', `\radicalex', `\register', `\Rho', `\suchthat', `\Tau', `\therefore', `\trademark', `\varUpsilon', `\Zeta'.
A good example of a LaTeX preamble to get LaTeX to compile
PreScript files is given by the report of @pack{}.
PreScript and @pack can be used for one-the-fly
formating. For instance, on the `passwd' file:
ypcat passwd |
awk -F: \
'{print "\textbf{" $5 "} (" $1 ") \rightarrow\textit{" $7 "}"}'\
| a2ps -Epre -P
In this chapter is collected what had no place in the rest of this document.
You are currently printing with a bad media, for instance using A4 paper within @pack{}, while your printer uses Letter paper. See section Global behavior, option `--media' for more.
There seems to be as many tastes as there are humans, so... don't expect from me the design of the style you like :).
Nevertheless, here are some tips on how to design your PostScript styles. It is strongly recommended to use `gray.pro' or `color.pro' as a template.
There are two PostScript instructions you might want to use in your new PostScript prologue:
setgray
setrgbcolor
yacc and suchThere are several reasons why we decided not to use grammars to parse the files.
First it would have made the design of the style sheets much more tricky, and today @pack would know only 4 or 5 languages.
Second, it limits the number of persons who could build a style sheet.
Third, mixing several parsers within one program is not easy. Moreover, its size would have ten times what it is.
Fourth, we did not feel the need for such a powerful tool: handling the keywords and the sequences is just what the users expect.
And last but not least, using a parser requires that the sources are syntactic bug free, which is a strong requirement.
Nevertheless, PreScript gives the possibility to have on the one
hand a syntactic parser which would produce PreScript code, and
on the other hand, @pack{}, which would make it PostScript. This schema
seems to us a good compromise.
There are no man pages because now the documentation is written in Texinfo. What you are reading comes from this initial Texinfo file.
Nevertheless, man pages may be back from Hell the day a
texi2roff filter appears.
No you can't. Fonts are hard coded in @pack{}(1), to get good execution results, and because it is easier. Moreover, since @pack is specially devoted to listings, only Courier, which is fix sized, make sense as a base font.
If you need to deal with several various fonts, then GNU enscript
is exactly the tool you need.
It would be great if @pack could easily print files written in ISO Latin
2. Currently I don't know how to do that, but ogonkiky may be of
valuable help. If you encoded new encodings support, please contact us.
@pack should be able to generate EPS files in a short while.
When printing a human file (only English may be supported), spelling should be checked. When pretty-printing, syntax errors should be underlined.
No just kidding :). Do it yourself...
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 C by Miguel Santana for improve
speed execution and portability. Many new features and improvements
have been added since this first version. Many contributions (changes,
fixes, ideas) were done by a2ps users in order to improve it.
From the latest known version from Miguel Santana (4.3), Emmanuel Briot implemented bold faces for keywords in ada, c and c++.
From that version, Akim Demaille generalized the pretty-printing capabilities, implemented more languages support, and quite a lot other things.
Since the very beginning of @pack{}, many people have brought help:
Some people helped to the translation:
A big thank must be given to Markku Rossi (the author of GNU
enscript), for the advises he gave, and for portions of his code which
are now used in @pack{}. Even portions of this very documentation are
taken from the GNU enscript man pages.
Denis Girou brought a constant and valuable support through out the genesis of pretty-printing @pack{}.
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.
PreScript
PreScript
setpagedevice
statusdict
This document was generated on 9 June 1997 using the texi2html translator version 1.51.