This document describes GNU @pack{} version 4.13. The latest versions may be found on the @href{http://www.inf.enst.fr/~demaille/a2ps,@pack{} home page}.
We tried to make this document informative and pleasant. It tries to be more than a plain reference guide, and intends to offer information about the concepts or tools etc. that are related to printing PostScript. This is why it is now that big: to offer you all the information you might want, not because @pack{} is difficult to use. See section A. Glossary, for technical words or even general information.
Please, send us emailcards :). Whatever the comment is, or if you
just like @pack{}, write to @email{Miguel.Santana@st.com, Miguel
Santana} and Akim Demaille.
@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{} :).
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 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:
Ogonkify (see section `Overview' in Ogonkify manual),
written by Juliusz Chroboczek.
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 (see section 10. Frequently asked questions), then on the page @href{http://www.inf.enst.fr/~demaille/a2ps/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 (bug-a2ps@gnu.org) which
subject is `a2ps version: short-description' and which
content mentions the name of your machine and OS, the version of
@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
make when it fails etc.).
Be sure to get a quick answer.
There is a mailing list in which are discussed various topics around @pack{}: a2ps@gnu.org. There are also announcements about the version in alpha testing, requests for comments, new sheets, etc.
To subscribe to the list, send a mail to a2ps-request@gnu.org, with `subscribe' in the body.
Please, note that the mailing list is by no means a bug reporting address: use bug-a2ps@gnu.org instead.
If you like @pack{} and if you feel like helping, there are several things you can do.
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{http://www.inf.enst.fr/~demaille/a2ps/po/, the a2ps translation page}.
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 section 3. Invoking @pack{}. For the definition of some words, see section A. Glossary, for questions you have, see section 10. Frequently asked questions.
@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.
To print a file `doc.txt', just give it to @pack{}: the default setting should be the one you'd like:
gargantua ~ $ a2ps doc.txt [doc.txt (plain): 9 pages on 5 sheets] [Total: 9 pages on 5 sheets] sent to the default printer
@pack{} sent the 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 `-2', standing for two virtual pages.
Say you want to print the C file `bar.c', and its header `foo.h', on 4 virtual pages, and save it into the file `foobar.ps'. Just hit:
gargantua $ a2ps foo.h bar.c -4 -o foobar.ps [foo.h (C): 1 page on 1 sheet] [bar.c (C): 3 pages on 1 sheet] [Total: 4 pages on 2 sheets] saved into the file `foobar.ps'
The option `-4' tells @pack{} to make four virtual pages: two rows by two columns. The option `-o foobar.ps' (which is the short version of `--output=foobar.ps') specifies the output file. Long options must always be separated by spaces, though short options with no arguments may be grouped.
Note too that the options may be specified before or after the files, it does not matter.
If you send `foobar.ps' to a printer, you'll discover that the keywords were highlighted, that the strings and comments have a different face. Indeed, @pack{} is a pretty-printer: if it knows the (programming) language in which your file is written, it will try to make it look nice and clear on the paper.
But too bad: `foo.h' is only one virtual page long, and `bar.c' takes three. Moreover, the comments are essential in those files. And even worse: the system's default printer is out of ink. Thanks god, precious options may help you:
gargantua $ a2ps -4 -Av foo.h bar.c --prologue=gray -P lw [foo.h (C): 1 page on 1 sheet] [bar.c (C): 3 pages on 1 sheet] [Total: 4 pages on 1 sheet] sent to the printer `lw'
Here the option `-A' is a short cut for the option `--file-align' which specifies how different files should be separated. This option allows several symbolic arguments: `virtual', `rank', `page', `sheet' (See section 3.1.3 Sheet Options, for more details). The value `virtual' means not to start each file on a different virtual pages.
So to fill the page is asked by `--file-align=virtual', or `-A virtual'. But symbolic arguments can be abbreviated when there are no ambiguity, so here, you can just use `-Av'.
The option `-P lw' means to print on the printer named `lw', and finally, the long option `--prologue' requires the use one of the alternative printing styles. There are other prologues (See section 3.1.6 Input Options, option `--prologue'), and you can even design yours (see section 8.6 Designing PostScript Prologues).
There are three special printers pre-defined.
The first one, void, sends the output to the trash.
Its main use is to see how many pages would have been used.
gargantua ~ $ a2ps -P void parsessh.c [parsessh.c (C): 33 pages on 17 sheets] [Total: 33 pages on 17 sheets] sent to the printer `void'
The second, display sends the output to Ghostview, so that
you can check the output without printing. Of course if you don't have
Ghostview, it won't work... And it is up to you to configure
another displaying application (see section 4.5 Your Printers).
The last, file saves the output into a file named after the
file you printed (e.g., saves into `foo.ps' when you print
`foo.c').
@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, forget that there are delegations. Indeed, the interface with the delegations has been designed so that you don't need to be aware that they exist to use them. Do as usual.
As an example, if you need to print a PostScript file, just hit:
gargantua ~ $ a2ps article.ps -d [article.ps (ps, delegated to PsNup): 7 pages on 4 sheets] [Total: 8 pages on 4 sheets] sent to the default printer
While honoring your defaults settings, @pack{} delegates the task to put
two virtual pages per physical page to psnup, a powerful filter
part of the famous psutils by Angus Duggan.
Suppose now that you want to display a Texinfo file. Then, provided you have all the programs @pack{} needs, just hit
gargantua ~ $ a2ps a2ps.texi -P display [a2ps.texi (texinfo, delegated to texi2dvi): 75 pages on 38 sheets] [Total: 76 pages on 38 sheets] sent to the printer `display'
Once the read documentation, you know you want to print just pages 10 to 20, plus the cover. Just hit:
gargantua ~ $ a2ps a2ps.texi --pages=1,10-20 -d [a2ps.texi (texinfo, delegated to texi2dvi): 13 pages on 7 sheets] [Total: 14 pages on 7 sheets] sent to the default printer
A final word: compressed files can be treated in the very same way:
gargantua ~ $ a2ps a2ps.texi.gz -a1,10-20 -d [a2ps.texi (compressed, delegated to Gzip-a2ps): 13 pages on 7 sheets] [Total: 14 pages on 7 sheets] sent to the default printer
You should be aware that:
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 (See section A. Glossary, for definitions). The option to specify Duplex printing is `--sides=mode' (see section 3.1.9 PostScript Options).
Here is how to print the documentation in Duplex and send it to the Duplex printer `margot':
quasimodo ~ a2ps/doc $ a2ps -s2 -Pmargot a2ps.texi [a2ps.texi (texinfo, delegated to texi2dvi): 109 pages on 28 sheets] [Total: 110 pages on 28 sheets] sent to the printer `margot'
This is also valid for several files.
Actually, you can do something even more tricky: print a small book!
This is much more complicated than printing Duplex, because the pages
needs to be completely reorganized another way. This is precisely the
job of psbook, yet another PsUtil from Angus Duggan. But there
is a user option which encapsulates the magic sequence of options:
`book'. Therefore, just run
quasimodo a2ps/doc $ a2ps -=book -Pmargot a2ps.texi [a2ps.texi (texinfo, delegated to texi2dvi): 109 pages on 109 sheets] [Total: 109 pages on 109 sheets] sent to the printer `margot'
and voila` !, a booklet printed on margot!
We strongly discourage you to try with several files at once, because the tools then easily get lost. And, after all, the result will be exactly the same once you collated all the booklets together.
Another limitation is that this does not work if it is not sent to a printer. This kind of weird limitations will be solved in the future.
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:
~ % a2ps --list=defaults
Configuration status of a2ps 4.12a
==================================
Sheets:
-------
medium = A4, portrait
page layout = 1 x 1, rows first
borders = yes
file alignment = page
interior margin = 0
More stuff deleted here
Internals:
----------
verbosity level = 2
file command = /usr/bin/file -L
temporary directory = /tmp
library path =
/home/akim/.a2ps
/usr/share/a2ps/sheets
/usr/share/a2ps/ps
/usr/share/a2ps/encoding
/usr/share/a2ps/afm
/usr/share/ogonkify/afm
/usr/share/a2ps/ppd
/usr/share/a2ps/fonts
/usr/share/ogonkify/fonts
/usr/share/a2ps
Remember that the on-line help is always available. Moreover, if your
screen is small, you may pipe it into more. Just trust
this:
a2ps --help | more
Many things are parameterizable in @pack{}, but two things are just essential to make sure everything goes right:
Both values may be checked with `a2ps --list=defaults'.
@pack{} provides some Native Language Support, that is speaking your mother tongue. It uses three special features for non-English languages:
To enable these features, properly set your environment variable
LANG (see the documentation of your system, for instance
`man locale', `man environ' etc.).
The problem with this approach is that a lot more than just messages and
time information is affected: especially the way numbers are written
changes, what may cause problems with awk and such.
So if you just want messages and time format to be localized, then define:
set LC_MESSAGES=fr ; export LC_MESSAGES set LC_TIME=fr ; export LC_TIME
Here are some tips on how to use @pack{} with other programs.
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 `mail'. Therefore, for better results, make sure to tell @pack{} the files are mails. The user option `mail' (or `longmail' for longer inputs) encapsulates most typical tuning users want to print mails (for instance, don't print all the headers).
Most specifically, if your mailer is:
elm
pine
# Your printer selection printer=a2ps -=mail -d # Special print command personal-print-command=a2ps -=mail -d
This is actually valid for any program that generates PostScript that you want to post-process with @pack{}. Use the following command:
a2ps
Not too hard, isn't it?
Nevertheless, this setting suppose your world is OK, your file(1)
detects correctly PostScript files, and your @pack{} is configured to
delegate. In case one one these conditions is not met, use:
a2ps -ZEps
Do not forget to tell Netscape whether your printer supports colors, and the type of paper it uses.
Calling @pack{} is fairly simple:
a2ps Options... Files...
If no Files... are given, @pack{} prints its standard input. If `-' appears in the Files..., it designates the standard input too.
To read the options and arguments that you give, @pack{} uses GNU
getopt, hence:
Here after a boolean is considered as true (i.e. setting the option on), if boolean is `yes', or `1'; as false if it equals `no' or `0'; and raise an error otherwise. The corresponding short option takes no arguments, but corresponds to a positive answer.
When an argument is presented between square brackets, it means that it is optional. Optional arguments to short option must never be separated from the option.
Task options specify the task @pack{} will perform. It will not print, it executes the task and exits successfully.
file does: display the (key of the) type of the
Files.
For instance, on a C file, you expect it to answer `c', and
upon a PostScript file, `ps'.
This can be very useful on broken systems to understand why a file is printed with a bad style sheet (see section 5.4 Style Sheet Files).
~ % a2ps --which bw.pro gray.pro /usr/local/share/a2ps/ps/bw.pro /usr/local/share/a2ps/ps/gray.pro
If there are several library files matching the name, only the first one is reported: this allows to check which occurrence of a file is used by @pack{}.
~ % a2ps --glob 'g*.pro' /usr/local/share/a2ps/ps/gray.pro /usr/local/share/a2ps/ps/gray2.pro
There are also options meant for the maintainers only, presented for sake of completeness.
sheet verbosity is set, report version numbers, requirements and
ancestors.
HTML format.
These options are related to the interface between you and @pack{}.
There is also an interface made for the maintainer with finer grained selection of the verbosity level. level is a list of tokens (non ambiguous abbreviations are valid) separated by either `,' or `+'. The tokens may be:
When @pack{} is launched it consults the environment variable
A2PS_VERBOSITY. If it is set, this defines the verbosity level
for the whole session (options `--verbose', and `-q' etc.
have then no influence). The valid values for A2PS_VERBOSITY are
exactly the valid arguments of the option `--verbose'. This helps
tracking down configuration problems that occur before @pack{} had
even a chance to read the command line.
There are a few predefined user-options:
This options specify the general layout, how the sheet should be used.
`A4dj', `Letterdj' are also defined for Desk Jet owners, since that printer needs bigger margins.
The special medium `libpaper' means that you want @pack{} to
ask the library libpaper for the medium to use. This choice is
valid only if libpaper was available when @pack{} was configured.
See the man page of paperconf for more information.
This options are related to the content of the virtual pages.
Please note that the options `-f', `-L', `-l', `-m', and `-1' .. `-9' all have an influence on the font size. Only the last one will win (i.e., `a2ps -L66 -l80' is the same as `a2ps -l80').
To change the fonts used, change the current prologue (see section 8.6 Designing PostScript Prologues.
If your file is actually a UNIX manual 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 (see section 4.10 Your Delegations).
--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 escapes. See section 3.2 Escapes, for details.
The pages referred to are the input pages, not the output pages, that is, in `-2', printing with `-a1' will print the first virtual page, i.e., you will get half the page filled.
Note that page selection does work with the delegations (see section 4.10 Your Delegations).
n
unix
r
mac
nr
pc
rn
any
auto
This is used for instance in the name given to the document from within
the PostScript code (so that Ghostview and others can display a
file with its real title, instead of just the PostScript file name).
It is not the name of the output. It is just a logical title.
-b of a2ps 4.3.
It is a copy of the black and white prologue, but in which all the fonts
are in Bold.
udiff, wdiff
style sheets, to underline the differences. New things are in bold
on a diff background, while removed sequences are in italic.
file(1) what it thinks of the type of the file. If file(1)
answers `data', the file will also be considered as binary, hence
not printed.
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 section 4.10 Your Delegations for information on delegating, and option `--list=delegations' for the applications your @pack{} knows.
#{toc}). If the given format is empty
(i.e., you wrote `--toc='), don't issue the table of contents.
Note that it is most useful to define a variable (see section 4.9 Your Variables), for instance, in a configuration file:
Variable: toc.mine \
\\Keyword{Table of Content}\n\
#-1!f\
|$2# \\keyword{$-.20n} sheets $3s< to $3s> ($2s#) \
pages $3p<-$3p> $4l# lines\n||\
\\Keyword{End of toc}\n
and to give that variable as argument to `--toc': `a2ps *.c --toc=#{toc.mine}'.
Note too that you can generate only the table of content using `--pages':
a2ps *.c --toc -atoc
These options are related to the pretty printing features of @pack{}.
See the documentation of the style sheets (`--list=style-sheets') for a description of `heavy' highlighting.
If language is `key.ssh', then don't look in the library path, but use the file `key.ssh'. This is to ease debugging non installed style sheets.
This option is valuable for instance in java in which case strong
comments are the so called documentation comments, or in SDL for
which some graphical editors pollutes the specification with internal
data as comments.
Note that the current implementation is not satisfactory: some undesired blank lines remain. This is planed to be fixed.
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 `-o', `-P' or `-d', the last one is honored.
The type of backups made can be set with the VERSION_CONTROL
environment variable, which can be overridden by this option. If
VERSION_CONTROL is not set and this option is not given, the
default backup type is `existing'. The value of the
VERSION_CONTROL environment variable and the argument to this
option are like the GNU Emacs `version-control' variable;
they also recognize synonyms that are more descriptive. The valid
values are (unique abbreviations are accepted):
SIMPLE_BACKUP_SUFFIX environment variable, which can be
overridden by this option. If neither of those is given, the default is
`~', as it is in Emacs.
It is possible to pass additional options to lpr or lp via
the variable `lp.options', for more information see section 10.2.5 How Can I Pass Options to `lpr'.
The following options are related only to variations you want to produce onto a PostScript output.
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.).
For example, command
ubu $ a2ps -SDuplex:true -STumble:true NEWS [NEWS (plain): 15 pages on 8 sheets] [Total: 15 pages on 8 sheets] sent to the default printer
prints file `report.pre' in duplex (two sides) tumble (suitable for landscape documents). This is also valid for delegated files:
a2ps -SDuplex:true -STumble:true a2ps.texi
Page device operators are implementation dependent but they are standardized. See section 8.2 Page Device Options, for details.
statusdict operators and variables are implementation dependent;
see the documentation of your printer for details. See section 8.3 Statusdict Options, for details. Several `--statusdict' can be accumulated.
If no value is given, key is removed from the definitions.
With a single colon, pass a call to an operator, for instance:
a2ps --statusdict=setpapertray:1 quicksort.c
prints file `quicksort.c' by using paper from the paper tray 1 (assuming that printer supports paper tray selection).
With two colons, define variable key to equal value. For instance:
a2ps --statusdict=papertray::1 quicksort.c
produces
/papertray 1 def
in the PostScript.
@pack{} quotes the access to that feature, so that non supporting printers won't fail.
The escapes are some sequences of characters that will be replaced by their values. They are very much like variables.
They are used in several places in @pack{}:
All format directives can also be given in format
escape width directive
where
Supported escapes are:
strftime(3) function.
strftime(3) function.
form feed).
new line).
mail-folder
style, tag 1 is the title of the mail, and tag 2 its author.
@pack{} reads several files before the command line options. In the order, they are:
Because @pack{} needs architecture dependent information (such as the
local lpr command) and architecture independent information (such
as the type of your printers), users have found useful that
`a2ps.cfg' be dedicated to architecture dependent information. A
sub configuration file, `a2ps-site.cfg' (see section 4.1 Including Configuration Files) is included from `a2ps.cfg'.
The file `a2ps.cfg' is updated when you update @pack{}, while `a2ps-site.cfg' is not, to preserve local definitions.
In the configuration files, empty lines and lines starting with `#' are comments.
The other lines have all the following form:
Topic: Arguments
where Topic: is a keyword related to what you are customizing, and Arguments the customization. Arguments may be spread on several lines, provided that the last character of a line to continue is a `\'.
In the following sections, each Topic: is detailed.
This is especially useful for the site specific configuration file `etc/a2ps.cfg': you may tune your printers etc. in a separate file for easy upgrade of @pack{} (and hence of its configuration files).
To define the default library path, you can use:
Note that for users configuration files, it is better not to set the library path, because the system's configuration has certainly been built to cope with your system's peculiarities. Use `AppendLibraryPath:' and `PrependLibraryPath:'.
It is the correct way to define the default behavior you expect from
@pack{}. If for instance you want to use Letter as medium, then
use:
Options: --medium=Letter
It is exactly the same as always giving @pack{} the option `--medium=Letter' at run time.
The quoting mechanism is the same as that of a shell. For instance
Options: --right-title="Page $p" --center-title="Hello World!" Options: --title="arg 'Jack said \\\"hi\\\"' has double quotes"
There are two formats supported:
# A4 for Desk Jets # name w h llx lly urx ury Medium: A4dj 595 842 24 50 571 818where wxh are the dimension of the sheet, and the four other stand for lower left x and y, upper right x and y.
# A4 # name w h Medium: A4 595 842is the same as
# A4 # name w h Medium: A4 595 842 24 24 571 818
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'.
The destination must be of one of the following forms:
Escapes expansion is performed on destination (see section 3.2 Escapes). Recall that `#o' is evaluated to the destination name, i.e., the argument given to `-P'.
For instance
# My Default Printer is called dominique
DefaultPrinter: | lp -d dominique
# `a2ps foo.c -P bar' will pipe into `lp -d bar'
UnknownPrinter: | lp -d #o
# `a2ps -P foo' saves into the file `foo'
Printer: foo > foo.ps
Printer: wc | wc
Printer: lw | lp -d printer-with-a-rather-big-name
# E.g. `a2ps foo.c bar.h -P file' will save into `foo.c.ps'
Printer: file > $n.#.
# E.g. `a2ps foo.c bar.h -P home' will save into `foo.ps'
# in user's home
Printer: home > ${HOME}/$N.#.
# Here we address a printer which is not PostScript
Printer: deskj | gs -q -sDEVICE=ljet3d -sOutputFile=- - \
| lpr -P laserwriter -h -l
MS-DOS users, and non-PostScript printer owners should take advantage in getting good configuration of these entries.
You can define some kind of `Macro Options' which stand for a set of options.
Examples are
# This emulates a line printer: no features at all # call a2ps -=lp to use it UserOption: lp -1m --pretty-print=plain -B --borders=no # When printing mail, I want to use the right style sheet with strong # highlight level, and stripping `useless' headers. UserOption: mail -Email -g --strip=1
@pack{} produces full DSC conformant PostScript (see section A. Glossary). Adobe said
Thou shalt start your PostScript DSC conformant files with
%!PS-Adobe-3.0
The bad news is that some printers will reject this header. Then you may change this header without any worry since the PostScript produced by @pack{} is also 100% PostScript level 1(2).
In the PostScript file is dropped information on where sheets begin and
end, so that post processing tools know where is the physical page 1, 2 etc.
With this information can be also stored a label, i.e., a human readable text
(typically the logical page numbers), which
is for instance what Ghostview shows as the list of page numbers.
@pack{} lets you define what you want in this field.
There are many places in @pack{} where one would like to have uniform way of extending things. It once became clear that variables where needed in @pack{}.
As as example, here is a variable for psnup, which encloses all
the option passing one would like. Delegations are then easier to
write:
Variable: psnup psnup -#v -q #?j|-d|| #?r||-c| -w#w -h#h
It is strongly suggested to follow a `.' (dot) separated hierarchy, starting with:
ps.page_label), the header etc.
This naming convention has not fully stabilized. We apologize for the inconvenience this might cause to users.
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 --define (see section 3.1.2 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 getpwuid) and finally
arbitrary values.
pw_gecos after the first `,'), (ii) not defined.
HOME, (ii) the system's database (using getpwuid), (iii)
the empty string.
gethostname
or uname), (ii) the empty string.
LOGNAME, (ii) the environment variable USERNAME,
(iii) the system's database (using getpwuid), (iv) the translated
string `user'.
pw_gecos up to the first `,'), (ii)
capitalized value of the variable `user.login' unless it was the
translated string `user', (iii) the translated string `Unknown
User'.
There are some files you don't really want @pack{} to pretty-print,
typically page description files (e.g., PostScript files, 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
`--delegate' (see section 3.1.6 Input Options).
command should produce the file on its standard output. Of course escapes substitution is performed on command (see section 3.2 Escapes). In particular, command should use the input file `$f'.
# In general, people don't want to pretty-print PostScript files.
# Pass the PostScript files to psnup
Delegation: PsNup ps:ps \
psselect #?V||-q| -p#?p|#p|-| $f | \
psnup -#v -q #?j|-d|| #?r||-c| -w#w -h#h
Advantage should be taken from the variables, to encapsulate the peculiarities of the various programs.
# Passes the options to psnup.
# The files (in and out) are to be given
Variable: psnup psnup -#v #?V||-q| #?j|-d|| #?r||-c| -w#w -h#h
# Passes to psselect for PS page selection
Variable: psselect psselect #?V||-q| -p#?p|#p|-|
# In general, people don't want to pretty-print PostScript files.
# Pass the PostScript files to psnup
Delegation: PsNup ps:ps #{psselect} $f | #{psnup}
Temporary file names (`#f0' to `#f9') are available for complex commands.
# Pass DVI files to dvips.
# A problem with dvips is that even on failure it dumps its prologue,
# hence it looks like a success (output is produced).
# To avoid that, we use an auxiliary file and a conditional call to
# psnup instead of piping.
Delegation: dvips dvi:ps #{dvips} $f -o #f0 && #{psnup} #f0
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(4). As a thumb rule, you should check that the PostScript generating applications produce files that start by:
%!PS-Adobe-3.0
@pack{} needs the `%%BeginSetup'-`%%EndSetup' section
in order to output correctly the page device definitions. It can happen
that your filters don't output this section. In that case, you should
insert a call to fixps right after the PostScript generation:
########## ROFF files
# Pass the roff files to groff. Ask grog how groff should be called.
# Use fixps to ensure there is a %%BeginSetup/%%EndSetup section.
Delegation: Groff roff:ps \
eval `grog -Tps '$f'` | fixps #?V!!-q! | #{d.psselect} | #{d.psnup}
There are some services expected from the delegations. The delegations you may write should honor:
groff).
If ever you need several commands, do not use `;' to separate them, since it may prevent detection of failure. Use `&&' instead.
The slogan "the sooner, the better" should be applied here: in
the processing chain, it is better to ask a service to the first
application that supports it. An example will make it clear: when
processing a DVI file, dvips knows better the page numbers
than psselect would. So a DVI to PostScript delegation
should ask the page selection (`#p') to dvips, instead of
using psselect later in the chain. An other obvious reason here
is plain efficiency (globally, less data is processed).
The purpose of this section is not to document all the predefined delegations, for this you should read the comments in the system configuration file `a2ps.cfg'. We just want to explain some choices, and give hints on how to make the best use of these delegations.
strings(1):
Delegation: dvips dvi:ps\
if strings $f | sed 3q | fgrep landscape > /dev/null 2>&1; then \
#{d.dvips} -T#hpt,#wpt $f -o #f0 && #?o|cat|#{d.psnup} -r| #f0;\
else \
#{d.dvips} $f -o #f0 && #{d.psnup} #f0; \
fi
In order to have that rule work correctly, it is expected from the TeX, or @LaTeX{} file to include something like:
\renewcommand{\printlandscape}{\special{landscape}}
\printlandscape
in the preamble.
We don't use a pipe because dvips always outputs data (its prologue) even if it fails, what prevents error detection.
texi2dvi, from the
package Texinfo, which runs makeindex, bibtex and
latex as many times as needed. You should be aware that if the
file includes files from other directories, it may miss some
compilation steps. Other cases (most typical) are well handled.
There are settings that only meant for @pack{} that you can tune by yourself.
file(1) on a file. If possible, make
it follow the symbolic links.
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 `a2ps --list=defaults'. Typically its value is:
gargantua ~ $ a2ps --list=defaults
Configuration status of a2ps 4.13
More stuff deleted here
Internals:
verbosity level = 2
file command = /usr/ucb/file -L
temporary directory =
library path =
/inf/soft/infthes/demaille/.a2ps
/usr/local/share/a2ps/sheets
/usr/local/share/a2ps/ps
/usr/local/share/a2ps/encoding
/usr/local/share/a2ps/afm
/usr/local/share/a2ps/printers
/usr/local/share/a2ps
You may change this default path through the configuration files (see section 4.2 Your Library Path).
If you plan to define yourself some files for @pack{}, they should be in one of those directories.
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:
bold prologue mentions the bw prologue:
Documentation This style is meant to replace the old option code(-b)code of a2ps 4.3. It is a copy of the black and white prologue, but in which all the fonts are in Bold. EndDocumentation
gnuc
style sheet:
documentation is "Declaration of functions are highlighted" "emph(only)emph if you start the function name" "in the first column, and it is followed by an" "opening parenthesis. In other words, if you" "write" "@example" "int main (void)" "@end example" "it won't work. Write:" "@example" "int" "main (void)" "@end example" end documentation
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:
The syntax of these files is:
*** path
requests that the file designated by path be included at this
point.
key valuemeaning that when looking for key (e.g., name of a font, an encoding etc.), @pack{} should use value (e.g., font file name, encoding description file name etc.).
The map files used in @pack{} are:
Even when a PostScript printer knows the fonts you want to use, using these fonts requires some description files.
See section 5.2 Map Files, for a description of the map files. This file associates the font-key to a font name. For instance:
Courier pcrr Courier-Bold pcrb Courier-BoldOblique pcrbo Courier-Oblique pcrro
associates to font named Courier, the key pcrr. To be
recognized, the font name must be exact: courier and
COURIER are not admitted.
There are two kinds of data @pack{} needs to use a font:
@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 (see section 5.3.1 Fonts Map File). To this end, a very primitive but still useful shell script is
provided: make_fonts_map.sh.
First, you need to find the directories which store the fonts you want to use, and extend the library path so that @pack{} sees those directories. For instance, add:
AppendLibraryPath: /usr/local/share/ghostscript/fonts
Then run make_fonts_map.sh. It should be located in the
`afm/' directory of the system's @pack{} hierarchy. Typically
`/usr/local/share/a2ps/afm/make_fonts_map.sh'.
This script asks @pack{} for the library path, wanders in this path
collecting AFM files, and digging information in them.
Once the script has finished, a file `fonts.map.new' was created. Check its integrity, and if it's correct, either replace the old `fonts.map' with it, or rename `fonts.map.new' as `fonts.map' and place it higher in the the library path (for instance in your `~/.a2ps/' directory).
The style sheets are defined in various files. See see section 7. Pretty Printing for the structure of these files. As for most other features, there is main file, a road map, which defines in which condition a style sheet should be used (see section 5.2 Map Files). This file is `sheets.map'.
Its format is simple:
style-key: patterns
or
include(file)
The patterns need not be on separate lines. There are two kinds of patterns:
file(1) matches pattern, then
select style style-key.
Currently flags can only be `i', standing for an insentive match. Please note that the matching is not truly case insensitive: rather, a lower case version of the string is compared to the pattern as is, i.e., the pattern should itself be lower case.
The special style-key `binary' tells @pack{} to consider that the file should not be printed, and will be ignored, unless option `--print-anyway' is given.
If a style name can't be found, the plain style is used.
The map file is read bottom up, so that the "last" match is honored.
Two things are to retain from this:
stdin, then @pack{} will run
file(1). However, unless you specify a fake file name with
`--stdin', pattern matching upon the name is turn off. In general
you can expect correct delegations, but almost never pretty printing.
file is wrong on some files, @pack{} may use bad style sheets.
In this case, do try option `--guess', compare it with the output
of file, and if the culprit is file, go and complain to
your system administrator :-), or fix it by defining your own filename
pattern matching rules.
Consider the case of Texinfo files as an example (the language in which
this documentation is written). Files are usually named
`foo.texi', `bar.txi', or even `baz.texinfo'.
file(1) is able to recognize Texinfo files:
doc % file a2ps.texi a2ps.texi: Texinfo source text
Therefore the sheets.map would look like:
# Texinfo files
texinfo: /*.txi/ /*.texi/ /*.texinfo/
<Texinfo source*>
@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.
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,
Certain character sets stand out either because of their status as an official national or international standard, or simply because of their widespread use.
First off, there is the ISO 8859 standards series that standardize a dozen character sets that are useful for a large number of languages using the Latin, Cyrillic, Arabic, Greek and Hebrew alphabets. These standards have a limited range of application (8 bits per character, a maximum of 190 characters, no combining) but where they suffice (as they do for 10 of the 20 most widely used languages), they should be used on the Internet in preference to other codes. For all other languages, national standards should preferably be chosen or, if none are available, a well-known and widely-used code should be the second choice.
Even when we limit ourselves to the most widely used standards, the overabundance remains considerable, and this significantly complicates life for truly international software developers and users of several languages, especially when such languages can only be represented by a single code. It was to resolve this problem that both Unicode and the ISO 10646 International standard were created. Two standards? Oh no! Their designers soon realized the problem and were able to cooperate to the extent of making the character set repertoires and coding identical.
ISO 10646 (and Unicode) contain over 30,000 characters capable of representing most of the living languages within a single code. All of these characters, except for the Han (Chinese characters also used in Japanese and Korean), have a name. And there is still room to encode the missing languages as soon as enough of the necessary research is done. Unicode can be used to represent several languages, using different alphabets, within the same electronic document.
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.
See section 6.1 What is an Encoding, if you want to know more about this.
See section 5.2 Map Files, for a description of the map files.
The meaningful lines of the `encoding.map' file have the form:
alias key iso-8859-1 latin1 latin1 latin1 l1 latin1
where
mail style sheet (support for
MIME).
When encoding is asked, the lower case version of encoding
must be equal to alias.
The encoding description file describing the encoding key is named `key.edf'. It is subject to the same rules as any other @pack{} file:
The entries are
Name: ISO-8859-1
Documentation Also known as ISO Latin 1, or Latin 1. It is a superset of ASCII, and covers most West-European languages. EndDocumentation
Courier, Times-Roman...) do not support many encodings
(for instance it does not support Latin 2). To avoid that Latin 2 users
have to replace everywhere calls to Courier, @pack{} allows to
specify that whenever a font is called in an encoding, then another font
should be used.
For instance in `iso2.edf' one can read:
# Fonts from Ogonkify offer full support of ISO Latin 2 Substitute: Courier Courier-Ogonki Substitute: Courier-Bold Courier-Bold-Ogonki Substitute: Courier-BoldOblique Courier-BoldOblique-Ogonki Substitute: Courier-Oblique Courier-Oblique-Ogonki
Courier
equivalent is the best choice.
Default: Courier-Ogonki
^G) should not be named). The special name `.notdef' is to
be used when the character is not printable.
Warning. Make sure to use real, official, PostScript names.
Using names such as `c123' may be the sign you use unusual names.
On the other hand PostScript names such as `afii8879' are common.
Most of the following information is a courtesy of @href{http://www.alis.com/, Alis Technologies inc.} and of Roman Czyborra's page about @href{http://czyborra.com/charsets/, The ISO 8859 Alphabet Soup}. See section 6.1 What is an Encoding, is an instructive presentation of the encodings.
The known encodings are:
The lack of the new C=-resembling Euro currency symbol U+20AC has opened the discussion of a new Latin0.
Support is provided thanks to Ogonkify.
Support is provided thanks to Ogonkify.
Support is provided thanks to Ogonkify.
The Cyrillic alphabet was created by St. Cyril in the 9th century from the upper case letters of the Greek alphabet. The more ancient Glagolithic (from the ancient Slav glagol, which means "word"), was created for certain dialects from the lower case Greek letters. These characters are still used by Dalmatian Catholics in their liturgical books. The kings of France were sworn in at Reims using a Gospel in Glagolithic characters attributed to St. Jerome.
Note that Russians seem to prefer the KOI8-R character set to the ISO set for computer purposes. KOI8-R is composed using the lower half (the first 128 characters) of the corresponding American ASCII character set.
Support is provided thanks to Ogonkify.
Support is provided thanks to Ogonkify.
Support is provided thanks to Ogonkify.
Very few fonts yet offer the possibility to print the Euro sign.
The main feature of @pack{} is its pretty-printing capabilities. Two different levels of pretty printing can be reached:
Note that the difference is up to the author of the style sheet.
@pack{} is not a powerful syntactic pretty-printer: it just handles lexical structures, i.e., if in your favorite language
IF IF == THEN THEN THEN := ELSE ELSE ELSE := IF
is legal, then @pack{} is not the tool you need. Indeed @pack{} just looks for some keywords, or some sequences.
configure.in and library m4 files.
To provide a high degree of expressivity, Claire uses:
To achieve its goal of readability, Claire uses
More information on claire can be found on @href{http://www.ens.fr/~laburthe/claire.html,claire home page}.
Names of defstructs are not highlighted because this would not work with defstruct options.
The language itself is not just a programming language but also covers analysis, design and implementation.
Heavy highlight uses symbols to represent common math operators.
The style sheets for77kwds and for90kwds implements keywords only,
while the style sheets for-fixed and for-free implements comments
only.
This style sheet tries to support any of the various flavors (Fortran 77/90/95, fixed or free form). For more specific uses, you should use either:
See the documentation of the style sheet fortran for more details.
See the documentation of the style sheet fortran for more details.
See the documentation of the style sheet fortran for more details.
int main (void)
it won't work. Write:
int main (void)
Whenever the changes of encoding are clear, a2ps sets itself the encoding for the parts concerned.
Tag 1 is the subject, and Tag 2 the author of the mail/news.
Note: This style sheet is _very_ difficult to write. Please don't report behavior you don't like. Just send me improvements, or write a Bison parser for mails.
This sheet was designed based on @href{http://www.research.digital.com/SRC/modula-3/html/home.html,Modula 3 home page}.
Implementation of the sheet based on @href{http://www.math.tau.ac.il/~laden/Oberon.html,The Oberon Reference Site}.
It can be a good choice of destination language for people who want to produce text to print (e.g. pretty-printing, automated documentation etc.) but who definitely do not want to learn PostScript, nor to require the use of LaTeX.
It provides by the use of LaTeX like commands, a way to describe the pages that this program should produce.
The Python interpreter and the extensive standard library are freely available in source or binary form for all major platforms from the @href{http://www.python.org,Python web site}, and can be freely distributed.
The same site also contains distributions of and pointers to many free third party Python modules, programs and tools, and additional documentation.
The Python interpreter is easily extended with new functions and data types implemented in C or C++ (or other languages callable from C). Python is also suitable as an extension language for customizable applications.
program --help | a2ps -Ecard
Implementation of the sheet based on the @href{http://www.icsi.berkeley.edu/~sather/index.html,Sather home page}.
Heavy highlighting uses symbols for common mathematical operators.
Typical use of this style is:
diff -u old new | a2ps -Eudiff
The prologue diff helps to highlight the differences
(`a2ps -Ewdiff --prologue=diff').
wdiff. wdiff is a utility that underlines the differences
of words between to files. Where diff make only the difference between
lines that have changed, wdiff reports words that have changed inside the lines.
Typical use of this style is:
wdiff old new | a2ps -Ewdiff
wdiff can be found in usual GNU repositories. The prologue diff
helps to highlight the differences (`a2ps -Ewdiff --prologue=diff').
This style sheet highlights some classical program names and builtins in the second level of pretty-printing.
This section presents a few style sheets that define page description languages (compared to most other style sheet meant to pretty print source files).
The style sheet Symbol introduces easy to type keywords to obtain
the special characters of the PostScript font Symbol. The
keywords are named to provide a @LaTeX{} taste. These keywords are also
the names used when designing a style sheet, hence to get the full list,
see section 7.6.1 A Bit of Syntax.
If you want to know the correspondence, it is suggested to print the
style sheet file of Symbol:
a2ps -g symbol.ssh
PreScript 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 an ssh syntax (see section 7.6 Style Sheets Implementation).
The main advantages for using PreScript are:
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 the following line will be badly
interpreted by @pack{}:
\Keyword{Problems using \keyword{recursive \copyright} calls}
The correct way to write this in PreScript is
\Keyword{Problems using} \keyword{recursive} \copyright \Keyword{calls}.
Everything from an unquoted % to the end of line is ignored (comments).
These commands required arguments.
PreScript and @pack{} can be used for one-the-fly
formating. For instance, on the `passwd' file:
ypcat passwd |
awk -F: \
'{print "\Keyword{" $5 "} (" $1 ") \rightarrow\keyword{" $7 "}"}'\
| a2ps -Epre -P
The aim of the PreTeX style sheet is to provide something similar to
PreScript, but with a more @LaTeX{} like syntax.
`$' is ignored in PreTeX for compatibility with @LaTeX{},
and `%' introduces a comment. Hence they are the only symbols which
have to be quoted by a `\'. The following characters should also be
quoted to produce good @LaTeX{} files, but are accepted by
PreScript: `_', `&', `#'.
Note that inside a command, like \textbf, the quotation
mechanism does not work in PreScript (\textrm{#$%}
writes `#$%') though @LaTeX{} still requires quotation. Hence whenever
special characters or symbols are introduced, they should be at the
outer most level.
These commands required arguments.
Symbol).
The following symbols, inherited from the style sheet Symbol, are
not supported by @LaTeX{}:
`\Alpha', `\apple', `\Beta', `\carriagereturn', `\Chi', `\Epsilon', `\Eta', `\florin', `\Iota', `\Kappa', `\Mu', `\Nu', `\Omicron', `\omicron', `\radicalex', `\register', `\Rho', `\suchthat', `\Tau', `\therefore', `\trademark', `\varUpsilon', `\Zeta'.
@LaTeX{} is more demanding about special symbols. Most of them must be in so-called math mode, which means that the command must be inside `$' signs. For instance, though
If \forall x \in E, x \in F then E \subseteq F.
is perfectly legal in @PreTeX{}, it should be written
If $\forall x \in E, x \in F$ then $E \subseteq F$.
for @LaTeX{}. Since in @PreTeX every `$' is discarded (unless quoted by a `\'), the second form is also admitted.
TeXScript is a replacement of the old version of
PreScript: it combines both the @pack{}-like and the
@LaTeX{}-like syntaxes through inheritance of both PreScript and
PreTeX.
In addition it provides commands meant to ease processing of file for @pack{} by @LaTeX{}.
Everything between `%%TeXScript:skip' and `%%TeXScript:piks'
will be ignored in @TeXScript, so that there can be inserted
command definitions for @LaTeX{} exclusively.
The commands `\textbi' (for bold-italic) and `\textsy' (for symbol) do not exist in @LaTeX{}. They should be defined in the preamble:
%%TeXScript:skip
\newcommand{\textbi}[1]{\textbf{\textit{#1}}}
\newcommand{\textsy}[1]{#1}
%%TeXScript:piks
There is no way in @TeXScript to get an automatic numbering. There is
no equivalent to the @LaTeX{} environment enumerate. But every
command beginning by \text is doubled by a command beginning by
`\magic'. @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 @TeXScript and @LaTeX{}.
`\header' and `\footer', are not understood by @LaTeX{}.
A 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:
Actually, there is also the face `Symbol', but this one is particular: it is not legal changing its font.
@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 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 `sheets.map' file, with the option `-E', etc.).
As an example, C++ is implemented in a file called `cxx.ssh', in which the name is declared to be `C++'.
The rationale is that not every system accepts any character in the file name (e.g., no `+' in MS-DOS). Moreover, it allows to make symbolic links on the ssh files (e.g., `ln -s cxx.ssh c++.ssh' let's you use `-E c++').
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.
@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.
If the style is case insensitive, then matching is case insensitive (keywords, operators and sequences).
A P-rule (Pretty printing rule), or rule for short, is a structure which consists of two items:
Just a short example: `(foo, bar, Keyword_strong)' as a rule
means that every input occurrence of `foo' will be replaced by
`bar', written with the Keyword_strong face.
If the destination string is empty, then @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 foobar be a case insensitive style sheet including the
rules `(foo, "", Keyword)' and `(bar, bar, Keyword)'. Then,
on the input `FOO BAR', @pack{} will produce `FOO bar' in
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 `unsigned' and `int' in C, which are
definitely not the same thing as `unsignedint'), and others not (in
C, `!=' is "different from" both in `a != b' and
`a!=b').
The first ones are called keywords in @pack{} jargon, and the seconds are operators. Operators are matched anywhere they appear, while keywords need to have separators around them (see section 7.5.3 Alphabets).
Let us give a more complicated example: that of the Yacc rules.
A rule in Yacc is of the form:
a_rule : part1 part2 ;
Suppose you want to highlight these rules. To recognize them, you will write a regular expression specifying that:
The regexp you want is: `/^[a-zA-Z0-9_]*[\t ]*:/'. But with the rule
/^[a-zA-Z0-9_]*[\t ]*:/, "", Label_strong
the blanks and the colon are highlighted too. Hence you need to specify some parts in the regexp (see section `Back-reference Operator' in Regex manual), and use a longer list of destination strings. The correct rule is
(/^([a-zA-Z0-9_]*)([\t ]*:)/, \1 Label_strong, \2 Plain)
Since it is a bit painful to read, regexps can be spread upon several lines. It is strongly suggested to break them by groups, and to document the group:
(/^([a-zA-Z0-9_]*)/ # \1. Name of the rule /([\t ]*:)/ # \2. Trailing space and colon \1 Label_strong, \2 Plain)
A sequence is a string between two markers, along with a list of exceptions. A marker is a fixed string. Typical examples are comments, string (with usually `"' as opening and closing markers, and `\\' and `\"' as exceptions) etc. Three faces are used: one for the initial marker, one for the core of the sequence, and a last one for the final maker.
There are two levels of pretty-printing encoded in the style sheets. By default, @pack{} uses the first level, called normal, unless the option `-g' is specified, in which case, heavy highlighting is invoked, i.e., optional keywords, operators and sequences are considered.
In the previous section (see section 7.5 Style Sheets Semantics) were explained the various items needed to understand the machinery involved in pretty printing. Here, their implementation, i.e., how to write a style sheet file, is explained. The next section (see section 7.7 A Tutorial on Style Sheets), exposes a step by step simple example.
Here are the lexical rules underlying the style sheet language:
alphabet,alphabets,are,case,documentation,end,exceptions,first,in,insensitive,is,keywords,operators,optional,second,sensitive,sequences,style
Comment,Comment_strong,Encoding,Error,Index1,Index2,Index3,Index4,Invisible,Keyword,Keyword_strong,Label,Label_strong,Plain,String,Symbol,Tag1,Tag2,Tag3,Tag4
C-char,C-string
It is a good idea to print the style sheet `symbols.ssh' to see them:
---,\Alpha,\Beta,\Chi,\Delta,\Downarrow,\Epsilon,\Eta,\Gamma,\Im,\Iota,\Kappa,\Lambda,\Leftarrow,\Leftrightarrow,\Mu,\Nu,\Omega,\Omicron,\Phi,\Pi,\Psi,\Re,\Rho,\Rightarrow,\Sigma,\Tau,\Theta,\Uparrow,\Upsilon,\Xi,\Zeta,\aleph,\alpha,\angle,\approx,\beta,\bullet,\cap,\carriagereturn,\cdot,\chi,\circ,\clubsuit,\cong,\copyright,\cup,\delta,\diamondsuit,\div,\downarrow,\emptyset,\epsilon,\equiv,\eta,\exists,\florin,\forall,\gamma,\geq,\heartsuit,\in,\infty,\int,\iota,\kappa,\lambda,\langle,\lceil,\ldots,\leftarrow,\leftrightarrow,\leq,\lfloor,\mu,\nabla,\neq,\not,\not\in,\not\subset,\nu,\omega,\omicron,\oplus,\otimes,\partial,\perp,\phi,\pi,\pm,\prime,\prod,\propto,\psi,\radicalex,\rangle,\rceil,\register,\rfloor,\rho,\rightarrow,\sigma,\sim,\spadesuit,\subset,\subseteq,\suchthat,\sum,\supset,\supseteq,\surd,\tau,\theta,\therefore,\times,\trademark,\uparrow,\upsilon,\varUpsilon,\varcopyright,\vardiamondsuit,\varphi,\varpi,\varregister,\varsigma,\vartheta,\vartrademark,\vee,\wedge,\wp,\xi,\zeta
a2ps symbols.ssh
C escaping mechanism is used.
C escaping mechanism is used. Regexps can be
split in several parts, a` la C strings (i.e., `/part 1/ /part
2/').
The definition of the name of the style sheet is:
stylenameis# body of the style sheetendstyle
The following constructions are optional:
version
version is version-number
written
written by authorsGiving your email is useful for bug reports about style sheets.
written by "Some Body <Some.Body@some.whe.re>"
requires
requires a2ps a2ps-version-number
documentation
documentation is strings end documentationstrings may be a list of strings, without comas, in which case new lines are automatically inserted between each item. See section 5.1 Documentation Format, for details on the format. Please, write useful comments, not `This style is devoted to C files', since the name is here for that, nor `Report errors to mail@me.somewhere', since
written by is there for that.
documentation is
"Not all the keywords are used, to avoid too much"
"bolding. Heavy highlighting (code(-g)code), covers"
"the whole language."
end documentation
There are two things @pack{} needs to know: what is symbol consistent, and whether the style is case insensitive.
alphabet
first alphabet is string second alphabet is stringIf both are identical, you may use the shortcut
alphabets are stringThe default alphabets are
first alphabet is "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_" second alphabet is "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_\ 0123456789"Note that it is on purpose that no characters interval are used.
case
case insensitive # e.g., C, C++ etc. case sensitive # e.g., Perl, Sather, Java etc.The default is
case insensitive.
It is possible to extend an existing style. The syntax is:
ancestors are ancestor_1[, ancestor_2...] end ancestors
where ancestor1 etc. are style sheet keys.
For semantics, the rules are the following:
As an example, both C++ and Objective C style sheets
extend the C style sheet:
style "Objective C" is #[...] ancestors are c end ancestors #[...] end style
To the biggest surprise of the author, mutually dependent style sheets do work!
See section 7.5.5 P-Rules, for the definition of P-rule.
Because of various short cuts, there are many ways to declare a rule:
rules ::= rule_1 `,' rule_2...
rule ::= `(' lhs rhs `)'
| lhs srhs ;
lhs ::= string | regex ;
rhs ::= srhs `,' ...
srhs ::= latex-keyword | expansion face
expansion ::= string | `\'num | <nothing>;
face ::= face-keyword | <nothing>;
The rules are the following:
#define RE_SYNTAX_A2PS \
(/* Allow char classes. */ \
RE_CHAR_CLASSES \
/* Be picky. */ \
| RE_CONTEXT_INVALID_OPS \
/* Allow intervals with `{' and `}', forbid invalid ranges. */\
| RE_INTERVALS | RE_NO_BK_BRACES | RE_NO_EMPTY_RANGES \
/* `(' and `)' are the grouping operators. */ \
| RE_NO_BK_PARENS \
/* `|' is the alternation. */ \
| RE_NO_BK_VBAR)
Basically it means that all of the possible operators are used, and that
they are in non-backslashed form. For instance `(' and `)'
stand for the group operator, while `\\(' stands for the character
`('. See section `Regular Expression Syntax' in Regex manual, for a detailed description of the regular
expressions.
Keyword.
PLAIN is used.
Basically, keywords and operators are lists of rules. The syntax is:
keywords are rules end keywords
or
keywords in face-keyword are rules end keywords
in which case the default face is set to face-keyword.
As an example:
keywords in Keyword_strong are /foo*/, "bar" "BAR" Keyword, -> \rightarrow end keywords
is valid.
The syntax for the operators is the same, and both constructs can be
qualified with an optional flag, in which case they are taken
into account in the heavy highlighting mode (see section 3.1.7 Pretty Printing Options).
This is an extract of the C style sheet:
optional operators are -> \rightarrow, && \wedge, || \vee, != \neq, == \equiv, # We need to protect these, so that <= is not replaced in <<= <<=, >>=, <= \leq, >= \geq, ! \not end operators
Note how `<<=' and `>>=' are protected (there are defined to be written as is when met in the source). This is to prevent the two last characters of `<<=' from being converted into a `less or equal' sign.
The order in which you define the elements of a category (but the
sequences) does not matter. But since @pack{} sorts them at run time, it
may save time if the alphabetical C-order is more or less
followed.
You should be aware that when declaring a keyword with a regular expression as lhs, then @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
keywords are /foo|bar/ end keywords
is exactly the same as
operators are /\\b(foo|bar)\\b/ end operators
This can cause problems if you use anchors (e.g. $, or ^)
in keywords: the matcher will be broken. In this particular case,
define your keywords as operators, taking care of the `\\b' by
yourself.
See section `Match-word-boundary Operator' in Regex manual, for details on `\b'.
Sequences admit several declarations too:
sequences ::= sequences are
sequence_1 `,' sequence_2...
end sequences
sequence ::= rule in_face close_opt exceptions_opt
| C-string
| C-char
;
close_opt ::= rule
| closers are
rules
end closers
| <nothing>
;
exceptions_opt ::= exceptions are
rules
end exceptions
| <nothing>
;
The rules are:
As a first example, here is the correct definition for a C string:
sequences are
"\"" Plain String "\"" Plain
exceptions are
"\\\\", "\\\""
end exceptions
end sequences
Since a great deal of languages uses this kind of constructs, you may
use C-string to mean exactly this, and C-char for
manifest characters defined the C way.
The following example comes from `ssh.ssh', the style sheet for
style sheet files, in which there are two kinds of pseudo-strings: the
strings (`"example"'), and the regular expressions
(`/example/'). We do not want the content of the pseudo-strings in
the face String.
sequences are
# The comments
"#" Comment,
# The name of the style sheet
"style " Keyword_strong (Label + Index1) " is" Keyword_strong,
# Strings are exactly the C-strings, though we don't want to
# have them in the "string" face
"\"" Plain "\""
exceptions are
"\\\\", "\\\""
end exceptions,
# Regexps
"/" Plain "/"
exceptions are
"\\\\", "\\\/"
end exceptions
end sequences
The order between sequences does matter. For instance in Java, `/**' introduces strong comments, and `/*' comments. `/**' must be declared before `/*', or it will be hidden.
There are actually some sequences that could have been implemented as
operators with a specific regular expression (that goes up to the
closer). Nevertheless be aware of a big difference: regular expression
are applied to a single line of the source file, hence, they cannot
match on several lines. For instance, the C comments,
/* * a comment */
cannot be implemented with operators, though C++ comments can:
// // a comment //
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 `c.ssh' style sheet, which is in the current directory, and is said case insensitive. Run
ubu $ a2ps foo.c -Ec.ssh -P void -v sheets # Long output deleted Checking coherence of "C" (c.ssh) a2ps: c.ssh:`FILE' uses upper case characters a2ps: c.ssh:`NULL' uses upper case characters "C" (c.ssh) is corrupted. ---------- End of Finalization of c.ssh
Here, it is clear that C is not case insensitive.
In this section a simple example of style sheet is entirely covered: that of `ChangeLog' files.
`ChangeLog' files are some kind of memory of changes done to files, so that various programmers can understand what happened to the sources. This helps a lot, for instance, in guessing what recent changes may have introduced new bugs.
First of all, here is a sample of a `ChangeLog' file, taken from the `misc/' directory of the original @pack{} package:
Sun Apr 27 14:29:22 1997 Akim Demaille <demaille@inf.enst.fr>
* base.ps: Merged in color.ps, since now a lot is
common [added box and underline features].
Fri Apr 25 14:05:20 1997 Akim Demaille <demaille@inf.enst.fr>
* color.ps: Added box and underline routines.
Mon Mar 17 20:39:11 1997 Akim Demaille <demaille@gargantua.enst.fr>
* base.ps: Got rid of CourierBack and reencoded_backspace_font.
Now the C has to handle this by itself.
Sat Mar 1 19:12:22 1997 Akim Demaille <demaille@gargantua.enst.fr>
* *.enc: they build their own dictionaries, to ease multi
lingual documents.
The syntax is really simple: A line specifying the author and the date of the changes, then a list of changes, all of them starting with an star followed by the name of the files concerned, then optionally between parentheses the functions affected, and then some comments.
Quite naturally the style will be called ChangeLog, hence:
style ChangeLog is written by "Akim Demaille <demaille@inf.enst.fr>" version is 1.0 requires a2ps 4.9.5 documentation is "This is a tutorial style sheet.\n" end documentation ... end style
A first interesting and easy entry is that of function names, between `(' and `)':
sequences are
"(" Plain Label ")" Plain
end sequences
A small problem that may occur is that there can be several functions mentioned separated by commas, that we don't want to highlight this way. Commas, here, are exceptions. Since regular expressions are not yet implemented in @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 `:', or when starts the list of functions. Then, we define two sequences, each one with one of the possible closers, the exceptions being attached to the first one:
sequences are
"* " Plain Label_strong ":" Plain
exceptions are
", " Plain, "," Plain
end exceptions,
"* " Plain Label_strong " " Plain
end sequences
Finally, let us say that some words have a higher importance in the core of text: those about removing or adding something.
keywords in Keyword_strong are add, added, remove, removed end keywords
Since they may appear in lower or upper, of mixed case, the style will be defined as case insensitive.
Finally, we end up with this style sheet file, in which an optional highlighting of the mail address of the author is done. Saving the file is last step. But do not forget that a style sheet has both a name as nice as you may want (such as `Common Lisp'), and a key on which there are strict rules: the prefix must be alpha-numerical, lower case, with no more than 8 characters. Let's chose `chlog.ssh'.
# This is a tutorial on a2ps' style sheets
style ChangeLog is
written by "Akim Demaille <demaille@inf.enst.fr>"
version is 1.0
requires a2ps 4.9.5
documentation is
"Second level of high lighting covers emails."
end documentation
sequences are
"(" Plain Label ")" Plain
exceptions are
", " Plain, "," Plain
end exceptions,
"* " Plain Label_strong ":" Plain
exceptions are
", " Plain, "," Plain
end exceptions,
"* " Plain Label_strong " " Plain
end sequences
keywords in Keyword_strong are
add, added, remove, removed
end keywords
optional sequences are
< Plain Keyword > Plain
end sequences
end style
As a last step, you may which to let @pack{} check your style sheet, both its syntax, and common errors:
ubu $ a2ps -vsheet -E/tmp/chlog.ssh ChangeLog -P void Long output deleted Checking coherence of "ChangeLog" (/tmp/chlog.ssh) "ChangeLog" (/tmp/chlog.ssh) is sane. ---------- End of Finalization of /tmp/chlog.ssh
It's all set, your style sheet is ready!
The last touch is to include the pattern rules about `ChangeLog' files (which could appear as `ChangeLog.old' etc.) in `sheets.map':
# ChangeLog files chlog: /ChangeLog*/
This won't work... Well, not always. Not for instance if you print `misc/ChangeLog'. This is not a bug, but truly a feature, since sometimes one gets more information about the type of a file from its path, than from the file name.
Here, to match the preceding path that may appear, just use `*':
# ChangeLog files chlog: /*ChangeLog*/
If you want to be more specific (`FooChangeLog' should not match), use:
# ChangeLog files chlog: /ChangeLog*/ /*\/ChangeLog*/
The example we have presented until now uses only basic features, and does not take advantage of the regexp. In this section we should how to write more evolved pretty printing rules.
The target will be the lines like:
Sun Apr 27 14:29:22 1997 Akim Demaille <demaille@inf.enst.fr> Fri Apr 25 14:05:20 1997 Akim Demaille <demaille@inf.enst.fr>
There are three fields: the date, the name, the mail. These lines all start at the beginning of line. The last field is the easier to recognize: is starts with a `<', and finishes with a `>'. Its rule is then `/<[^>]+>/'. It is now easier to specify the second: it is composed only of words, at least one, separated by blanks, and is followed by the mail: `/[[:alpha:]]+([ \t]+[[:alpha:]]+)*/'. To concatenate the two, we introduce optional blanks, and we put each one into a pair of `('-`)' to make each one a recognizable part:
([[:alpha:]]+([ \t]+[[:alpha:]]+)*) (.+) (<[^>]+>)
Now the first part is rather easy: it starts at the beginning of the line, finishes with a digit. Once again, it is separated from the following field by blanks. Split by groups (see section `Grouping Operators' in Regex manual), we have:
^ ([^\t ].*[0-9]) ([ \t]+) ([[:alpha:]]+([ \t]+[[:alpha:]]+)*) (.+) (<[^>]+>)
Now the destination is composed of back references to those groups, together with a face:
# We want to highlight the date and the maintainer name optional operators are (/^([^\t ].*[0-9])/ # \1. The date /([ \t]+)/ # \2. Spaces /([[:alpha:]]+([ \t]+[[:alpha:]]+)*)/ # \3. Name /(.+)/ # \5. space and < /(<[^>]+)>/ # \6. email \1 Keyword, \2 Plain, \3 Keyword_strong, \5 Plain, \6 Keyword, > Plain) end operators
Notice the way regexps are split, to ease reading.
This section is meant for people who wish to contribute style sheets. There is a couple of additional constraints, explained here.
Finally, make sure your style sheet behaves well! (see section 7.6.8 Checking a Style Sheet)
This chapter is devoted to the information which is only relevant to PostScript.
To read this section, the reader must understand what DSC are (see section A. Glossary).
Why are there good PostScript files, easy to post-process, and bad files that none of my tools seem to understand? They print fine though!
Once you understood that PostScript is not a page description format (like PDF is), you'll have understood most of the problem. Let's imagine for a second that you are a word processor.
The user asks you to print his/her 100 page document in PostScript. Up to page 50, there are few different fonts used. Then, on pages 51 to 80, there are now many different heavy fonts.
When/where will you download the fonts?
The most typical choice, sometimes called Optimize for Speed, is, once you arrived to page 51, to download those fonts once for the rest of the document. The global processing chain will have worked quite quickly: little effort from the software, same from the printer; better yet: you can start sending the file to the printer even before it is finished! The problem is that this is not DSC conformant, and it is easy to understand why: if somebody wants to print only the page 60, then s/he will lack the three fonts which were defined in page 51... This document is not page independent.
Another choice is to download the three fonts in each page ranging from 51 to 80, that is the PostScript file contains 30 times the definition of each font. It is easy for the application to do that, but the file is getting real big, and the printer will have to interpret 30 times the same definitions of fonts. But it is DSC conformant! And you can still send the file while you make it.
Now you understand why
Non DSC conformant files are not necessarily badly designed files from broken applications.
They are files meant to be sent directly to the printer (they are still perfect PostScript files after all!), they are not meant to be post-processed. And the example clearly shows why they are right.
There is a third possibility, sometimes called Optimize for Portability: downloading the three fonts in the prologue of the document, i.e., the section before the first page where are given all the common definitions of the whole file. This is a bit more complicated to implement (the prologue, which is issued first though, grows at the same time as you process the file), and cannot be sent concurrently with the processing (you have to process the whole file to design the prologue). This file is small (the fonts are downloaded once only), and DSC conformant. Well, there are problems, of course... You need to wait before sending the output, it can be costly for the computer (which cannot transfer as it produces), and for the printer (you've burnt quite a lot of RAM right since the beginning just to hold fonts that won't be used before page 51... This can be a real problem for small printers).
This is what @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.
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 `-S' option (`--setpagedevice'). For a complete listing, see PostScript Language Reference Manual (section 4.11 Device Setup in the second edition, or section 6, Device Control in the third edition).
Collate boolean
Duplex boolean
ManualFeed boolean
OutputFaceUp boolean
Tumble boolean
The statusdict is a special storage entity in PostScript (called
a dictionary), in which some variables and operators determine the
behavior of the printer. This is an historic horror that existed before
page device definitions were defined. They are even more printer
dependent, and are provided only for the people who don't have a level
printer. In any case, refer to the documentation of your printer for
supported options.
Here are some statusdict definitions in which you might be interested:
manualfeed boolean
setmanualfeed boolean
setduplexmode boolean
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
@pack{} uses two higher level procedures, BG and FG, but
both use an argument as in setrgbcolor. So if you wanted a gray
shade, just give three times the same ratio.
@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:
% code follows this line
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 prologue files. But since the authors feel a little small against NEXPTIME, they agreed on the fact that you are the one who will design the look you like.
Hence in this section, you will find what you need to know to be able to customize @pack{} output.
Basically, @pack{} uses faces which are associated to their "meaning" in the text. @pack{} let's you change the way the faces look.
There are three things that define a face:
%Face: face real-font-name sizeThis line tells @pack{} that the font of face is real-font-name. It will replace this line by the correct PostScript line to call the needed font, and will do everything needed to set up the font. The size of the text body is
bfs.
true to BG:
0.8 0.8 0 true BG
BG with
false:
false BG
BG, call FG with an RGB ratio:
0 0.5 0 FG
UL requires a boolean argument, depending whether you want
or not the current face to be underlined.
true UL
BX let's a face have a box drawn around.
Prologue files for @pack{} must have `pro' as suffix. Documentation (reported with `--list-prologues') can be included in the comment part:
Documentation This prologue is the same as the prologue code(pb)code, but using the bold version of the fonts. EndDocumentation % code follows this line
See section 5.1 Documentation Format, for more on the format.
We strongly suggest our readers not to start from scratch, but to copy one of the available styles (see the result of `a2ps --list=prologues'), to drop it in one of @pack{} directories (say `$HOME/.a2ps', and to patch it until you like it.
Here, we will start from `color.pro', trying to give it a funky look.
Say you want the keywords to be in Helvetica, drawn in a flashy pink on a light green. And strong keywords, in Times Bold Italic in brown on a soft Hawaiian sea green (you are definitely a fine art amateur).
Then you need to look for `k' and `K':
/k {
false BG
0 0 0.9 FG
%Face: Keyword Courier bfs
Show
} bind def
/K {
false BG
0 0 0.8 FG
%Face: Keyword_strong Courier-Bold bfs
Show
} bind def
and turn it into:
/k {
0.2 1 0.2 true BG
1 0.2 1 FG
%Face: Keyword Helvetica bfs
Show
} bind def
/K {
0.4 0.2 0 true BG
0.5 1 1 FG
%Face: Keyword_strong Times-BoldItalic bfs
Show
} bind def
Waouh! It looks great!
A bit trickier: let change the way the line numbers are printed.
First, let's look for the font definition:
%%BeginSetup % The font for line numbering /f# /Helvetica findfont bfs .6 mul scalefont def %%EndSetup
Let it be in Times, twice bigger than the body font.
%%BeginSetup % The font for line numbering /f# /Times-Roman findfont bfs 2 mul scalefont def %%EndSetup
How about its foreground color?
% Function print line number (<string> # -)
/# {
gsave
sx cw mul 2 div neg 0 rmoveto
f# setfont
0.8 0.1 0.1 FG
c-show
grestore
} bind def
Let it be blue. Now you know the process: just put `0 0 1' as
FG arguments.
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 Ogonkify
(see section `Overview' in Ogonkify manual), written by Juliusz
Chroboczek.
cardMany users of @pack{} have asked for a reference card, presenting a summary of the options. In fact, something closely related to the output of `a2ps --help'.
The first version of this reference card was a PreScript file (see section 7.3.2 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 `a2ps --help'! A first advantage is then that the reference cards can be printed in the tongue you choose.
A second was that this treatment could be applied to any application supporting a `--help'-like option.
card
card [options] applications [-- @pack{-options}]
card is a shell script which tries to guess how to get your
applications' help message (typically by the options `--help'
or `-h'), and pretty prints it thanks to @pack{} (or the content of
the environment variable `A2PS' if it is set).
@pack{-options} are passed to @pack{}.
Supported options are:
LC_ALL etc.
(such as `fr', `it' etc.).
If the applications don't support internationalization, English will be used.
card --command="cc -flags"
It is possible to give options to @pack{} (see section 3.1 Command line options) by specifying them after `--'. For instance
card gmake gtar --command="cc -flags" -- -Pdisplay
builds the reference card of GNU make, GNU tar (automatic
detection of `--help' support), and cc thanks to
`-flags'.
card
Remember that card runs the programs you give it, and the
commands you supplied. Hence if there is a silly programs that has a
weird behavior given the option `-h' etc., beware of the result.
It is even clearer using `--command': avoid running `card --command="rm -rf *"', because the result will be exactly what you think it will be!
fixps
The shell script fixps tries its best to fix common problems in
PostScript files that may prevent post processing. It makes heavy use
of the psutils. It is a good idea to use fixps in the
PostScript delegations.
It first tries to make simple fixes, but some really broken files may
require a much deeper treatment. If fixps feels the need for
such a major surgery act, it may give up local changes and ask
Ghostscript for a global rewriting.
fixpsfixps [options] [file]
sanitize the PostScript file (or of the standard input if no file is given, or if file is `-').
Supported options are:
ghoscript for a full rewrite of the file. The output
file is really sane, but can be much longer than the original. For this
reason and others, it is not always a good idea to make a full rewrite.
This option should be used only for files that give major problems.
fixnt
fixnt (see its
@href{http://www.itsm.uni-stuttgart.de/~bauer/fixnt.html}, home page) is
maintained by Holger Bauer and
Michael Rath. It is meant to fix
the problems of the PostScript files generated by the Microsoft
PostScript driver under Windows NT (3.5 and 4.0).
fixps is aware of the cases where fixnt should be used,
hence you should not worry of when to use fixnt.
fixntfixnt < `file.ps'
sanitize the PostScript file file.ps and produce the result on the standard output.
pdiff
The shell script pdiff aims to pretty print diffs between files.
It basically uses GNU diff (see section `Overview' in Comparing and Merging Files) or GNU wdiff (see section `The word difference finder' in GNU wdiff) to extract the diff, then calls
@pack{} with the correct settings to get a nice, printed contextual diff.
pdiff
pdiff [options] file-1 file-2 [-- @pack{-options}]
make a pretty comparison between file-1 and file-2. @pack{-options} are passed to @pack{}.
Supported options are:
It is possible to give options to @pack{} (see section 3.1 Command line options) by specifying them after `--'. For instance
pdiff COPYING COPYING.LIB -- -1 -P display
Compares the files `COPYING' and `COPYING.LIB', and prints it
on the printer display (usually Ghostview or gv).
psmandupI personally hate to print documents of hundreds of pages on a single sided printer. Too bad, here there are no Duplex printers. The idea is then simply first to print the odd pages, then the even in reversed order. To make sure one flips the page in the meanwhile, the second half should be printed from the manual feed tray.
Make a shell script that automates this, and you get psmandup.
psmanduppsmandup [options] [file]
produce a manual duplex version of the PostScript file (or of the standard input if no file is given, or if file is `-'). Once the first half is printed, put the sheet stack in the manual feed tray for the second half(5).
Be aware that there is a time out for manually fed jobs, usually short, hence do not miss the moment when the printer asks for the stack. If ever you missed that moment, see option `--back' to recover the second half.
Supported options are:
psmandup will fail on ill designed PostScript (well, actually the
psutils will). To avoid this, by default the PostScript file is
sanitized by fixps.
When given this option, don't run fixps. This is meant to be
used when fixps has already been used higher in the processing
chain.
This option is especially useful when the manual feed time out expired before you could insert back the stack in the manual feed tray.
psmandup assumes the printer is Level 2, and supports manual
feeding. The file should be reasonably sane, otherwise
psmandup fails miserably.
Typical use is
psmandup file.ps | lp
or can be put into @pack{}' printer commands (see section 4.5 Your Printers).
psset
The shell script psset inserts calls to setpagedevice in a
PostScript file. This is useful for instance to add Tumble or Manual
feed request. Actually, psmandup uses psset.
You should know nevertheless that @pack{} is able to make the calls to
setpagedevice by itself, i.e., you can run `a2ps
-SManualFeed foo' to print `foo' onto the manually fed tray, or run
`a2ps -s2 foo' to print Duplex. There are no need of psset
from @pack{}.
pssetpsset [options] [file]
produce a version of the PostScript file (or of the standard input
if no file is given, or if file is `-') that makes
protected calls to the PostScript operator setpagedevice.
Typical use is making file print duplex, or on the manual tray
etc.
The call is protected so that the resulting file is safe, i.e., will still be portable, even with requests such as `-Sfoo:bar'.
It is safe to run psset with no feature requests. Depending upon
the option `--no-fix', it is either equivalent to doing nothing, or
to running fixps (see section 9.2 fixps).
Supported options are:
psset will fail on ill designed PostScript. Actually it is the
psutils that fail. To avoid this, by default the PostScript file is
sanitized by fixps.
When given this option, don't run fixps. This is meant to be
used when fixps has already been used higher in the processing
chain.
setpagedevice call setting key to value.
Multiple values accumulate. Lists of requests separated with `;'
are valid (e.g., `-SDuplex:true;Tumble:false').
setpagedevice call should be done.
The page 0, which is the default, corresponds to the `Setup'
section of the document. More precisely, the insertion is performed at
the end of the `Setup' section, so that if there are multiple calls
to psset on the same document (which is of course, a bad idea),
the last call is winning.
In a typical use you should not change the page.
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.
Error related questions.
@pack{ works OK, but the printer prints nothing.}
There are two ways that printing can fail: silently, or with a diagnostic.
First, check that the printer received what you sent. @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 `-S', `--setpagedevice' (see section 8.2 Page Device Options) and `--statusdict' (see section 8.3 Statusdict Options).
If the trouble persists, please try again but with the option `--debug' (a PostScript error handler is downloaded), and then send us:
Though I ask @pack{ to print Duplex via `--sides', the job is printed Simplex.}
If your printer is too old, then @pack{} will not be able to send it the code it needs when `-s2' is specified. This is because your printer uses an old and not standardized interface for special features.
So you need to
Since this is painful to hit, a User Option (see section 4.6 Your Shortcuts) should help.
Though I ask @pack{ to print Simplex via `--sides', the job is printed Duplex.}
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 `-SDuplex:false'. The user options `-=s1' and `-=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.
When I print text files with @pack{, it prints beyond the frame of the paper.}
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 section 3.1.3 Sheet Options, option `--medium' for more.
What I get on the printer is long and incomprehensible. It does not seem to correspond to what I wanted to print.
You are probably printing a PostScript file or equivalent. Try to print
with `-Z': @pack{} will try to do his best to find what is the
program that can help you (see section 4.10 Your Delegations). In case of doubt,
don't hesitate to save into a file, and check the content with
Ghostview, or equivalent:
$ a2ps my_weird_file -Z -o mwf.ps $ gv mwf.ps
If your @pack{} is correctly installed, you can use the `display' fake-printer:
$ a2ps my_weird_file -Z -P display
If it is incorrect, ask for help around you.
@pack{ complains that my file is binary though it is not.}
There are several reasons that can cause @pack{} to consider a file is binary:
file(1) said the type of the file is `data', in
which case @pack{} prefers not to print the file. Then you can either:
binary: <data*>
# Load the system's sheets.map include(/usr/local/share/a2ps/sheets/sheets.map) # Override the rule for files with type `data' according to file(1) plain: <data*>But this is not very good, since then this rule is always the first tested, which means that any file with type `data' according to
file(1) will be printed in `plain' style, even if the file
is called `foo.c'.
# file(1) says it's data, but it's pure text plain: /*.txx/
@pack{ does not seem to honor
--font-size(or `--lines-per-page', or `--chars-per-line').}
This is probably because you used `-1'..`-9' after the `--font-size'. This is wrong, because the options `-1'..`-9' set the font size (so that there are 80 characters per lines), and many other things (See section 3.1.4 Page Options, option `--font-size').
Hence `a2ps --font-size=12km -4' is exactly the same thing as `a2ps -4', but is different from `a2ps -4 --font-size=12km'. Note that the `pure' options (no side-effects) to specify the number of virtual pages are `--columns' and `--rows'.
A mini how-to on @pack{}.
The option `--margin[=size]' is meant for this. See section 3.1.3 Sheet Options.
stdin?
@pack{} prints the standard input if you give no file name, or if you gave
`-' as file name. Automatic style selection is of course much
weaker: without the file name, @pack{} can only get file(1)'s
opinion (see section 5.4 Style Sheet Files). In general it means most
delegations are safe, but there will probably be no pretty-printing.
`You' can supply a name to the standard input (`--stdin=name') with which it could guess the language.
See section 8.6 Designing PostScript Prologues, for details. Make sure that all the information @pack{} needs is available (see section 5.3 Font Files).
By the past, @pack{} had an option `-b' with which the fonts were bold. Since now the fonts are defined by prologues (see section 8.6 Designing PostScript Prologues) this option no longer makes sense. A replacement prologue is provided: `bold'. To use it, give the option `--prologue=bold'.
How can I tell
a2psto asklprno to print the banner?How can I pass specific options to
lp?
If your `Printer:' fields in the configuration files were properly
filled (see section 4.5 Your Printers), you can use the variable
`lp.options' to pass options to lpr (or lp, depending
on your environment):
a2ps -Dlp.options="-h -s" -P printer
You can also define `lp.options' once for all, See section 4.9.1 Defining Variables.
Finally, you can use `Printer:' several times to reach a printer
with different lpr options.
I use @pack{ at work and wish to use it at home, but my printer is not PostScript. How can I do?}
Ghostscript might be the tool you need (see section A. Glossary). It
support conversion to many different non PostScript printers.
Here are some tips on how to use a non PostScript printer. If somebody feels like writing a more precise documentation, she really is welcome.
Please refer to the Ghostscript documentation for a precise
description of the tuning you need.
Basically, the first step you need is to achieve to call
Ghostscript in a pipe chain. In other words, try to find out the
right arguments Ghostscript needs in order to print with a
command like this:
$ cat file.ps | gs more arguments
In general it is the same command as for calling Ghostscript with
a filename, except that the file name to use is `-':
$ cat file.ps \ | gs -q -dNOPAUSE -sDEVICE=deskjet -sOutputFile=- - -c quit\ | lp -dprinter-name
Once it works, it is then easy to settle the right Printer: line
in your configuration file (see section 4.5 Your Printers). For instance:
Printer: djet \ | gs -q -dNOPAUSE -sDEVICE=deskjet -sOutputFile=- - -c quit\ | lp -d djet
Christian Mondrup uses @pack{} under Windows with a non PostScript printer. He uses:
DefaultPrinter: | //c/gstools/gs5.10/Gswin32c.exe \ -Ic:\gstools\gs5.10;c:\gstools\gs5.10\fonts \ -sDEVICE=ljet4 -sPAPERSIZE=a4 -dNOPAUSE -r300 -dSAFER \ -sOutputFile="\\spool\HP LaserJet 5L (PCL)" \ -q - -c quit
By the past, when I printed a man page with @pack{, it used underlines, but now it uses italics. I want underlines back!}
Use `a2ps --pro=ul'.
Wondering something?
The famous Y2K(6) 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 `100' instead of `00'): `%D', `%W', `$D', `$W'.
Nevertheless, please note that if you required a two digit year, expect to have `Jan 1st, 00' someday. You are responsible of the format you want for the date: See section 3.2 Escapes.
The options of this @pack{ are not the same as in the previous versions.}
True. But the old scheme (up to version 4.6.1) prevented us from offering more options. We had to drop it, and to fully redesign the options handling.
Since that profound change, we try to change as little as possible between versions. Nevertheless, as the time passes, we discover that some never used options should be renamed, or used for something else. In these cases, compatibility code is left for a long time.
Anywhere you put options but the command line (e.g., in @pack{} configuration files or in shell scripts), avoid using short options, since short options are much more likely to be changed (there are not so many, so it is a precious resource). Since there are as many long options as one wants, we can leave compatibility code with the long options.
yacc and suchThere 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, 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. If it is still not enough for you, you
can use the library.
This section settles some terms used through out this document, and provides the definitions of some terms you probably want to know about.
psnup, psselect etc.) can post process
PostScript files.
Ghostscript
gs
Ghostscript},
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:
Ghostview or gv ...).
ghostscript, you may print PostScript files on non PostScript
printers.
HTML, PostScript,
@LaTeX{}, roff and others are such languages. A file written in
those languages is not made to be read as is by a human, but to be
transformed (or compiled) into a readable form.
HTML, or roff, but as TeX and @LaTeX{}, it is
truly a programming language which main purpose is to draw (on sheets).
Most programs are a list of instructions that describes lines, shades of
gray, or text to draw on a page. This is the language that most
printers understand.
Note that the fact that PostScript is a programming language is
responsible of both its success and its failure. It is a big win for
the PostScript programmer who can easily implement a lot of nice visual
effects. It is a big loss because the page descriptions can have an
arbitrary complexity, hence rendering can be really slow (remember the
first Laser you had, or even Ghostscript. PDF has been
invented by Adobe to remedy these problems).
PostScript is a trademark of Adobe Systems Incorporated.
psutils
psutils to run correctly, the PostScript files must be DSC
conformant, and the bad news is that many PostScript drivers produce
files which are not. For some common cases (e.g., Micro$oft tools),
Angus Duggan included in the package some tools (named fix...ps)
to fix typical problems. fixps is a collection of recipes on
when to run what fix tool.
Here are some words on @pack{} and its history.
The initial version was a shell program written by Evan Kirshenbaum. It was very slow and contained many bugs.
A new version was written in C by Miguel Santana to improve execution speed and portability. Many new
features and improvements have been added since this first version.
Many contributions (changes, fixes, ideas) were done by @pack{} users in
order to improve it.
From the latest version from Miguel Santana (4.3), Emmanuel Briot
implemented bold faces for keywords in Ada, C and
C++.
From that version, Akim Demaille generalized the pretty-printing capabilities, implemented more languages support, and other features.
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 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 `--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 `:)'. Graham is usually the ultimate test: if he says I can release @pack{}, I rest reassured that, yes, this time it 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 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!
Some people worked on the translation of @pack{}:
Ogonkify (see section `Overview' in Ogonkify manual).
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.
Jump to: % - . - : - a - b - c - d - e - f - g - h - i - k - l - m - n - o - p - r - s - t - u - v - w
A2PS_VERBOSITY
C-char
C-string
display
elm
file
Ghostscript
gs
libpaper
make_fonts_map.sh
paperconf
pine
PreScript
psutils
setpagedevice
statusdict
void
A classical Unix trick to make the difference between the option `-2', and the file `-2' is to type `./-2'.
That is to say, there are no PostScript printers that don't understand these files.
Current a2ps
only handles PostScript output, i.e. out=`ps'
Because hiding its use into a2ps just makes
it even more difficult to the users to know why it failed. Let them use
it by hand.
Many people seem to ignore that you can insert several sheets in the manual feed tray. Try at least once, it will save you from hours spent feeding page per page by hand!
Year 2000.
This document was generated on 5 April 2000 using texi2html 1.56k.