Go to the first, previous, next, last section, table of contents.

5 Library Files

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

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

gargantua ~ $ a2ps --list=defaults
Configuration status of a2ps 4.12
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 a2ps, they should be in one of those directories.

5.1 Documentation Format

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

These tags are:

`code('text`)code'

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

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

`href('link`)href('text`)href'

Specifies a hyper text link displayed as text.

`@example'

`@end example'

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

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

`@itemize'

`@item' text

`@end itemize'

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

5.2 Map Files

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

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

The syntax of these files is:

any empty line, or any line starting by a `#' is a comment.
a line with the format
```
***              path
```
requests that the file designated by path be included at this point.
any other line has the format
```
key               value
```
meaning that when looking for key (e.g., name of a font, an encoding etc.), a2ps should use value (e.g., font file name, encoding description file name etc.).

The map files used in a2ps are:

`encoding.map': Resolving encodings aliases.
`fonts.map': Mapping font names to font file names.
`sheets.map': Rules to decide what style sheet to use.

5.3 Font Files

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

5.3.1 Fonts Map File

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

5.3.2 Fonts Description Files

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

the AFM file (`font-key.afm'), which describes the metrics information corresponding to font;
in the case font is not known from the printer, the PFA or PFB file which is down loaded to the printer. These files are actually the PostScript programs which execution produces the characters to be drawn on the page, in this font.

5.3.3 Adding More Font Support

a2ps can use as many fonts as you want, provided that you teach it the name of the files in which are stored the fonts (see 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 a2ps sees those directories. For instance, add:

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

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

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

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

5.4 Style Sheet Files

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

It format is simple:

`pattern style-key'

if the current file name matches pattern, then select style style-key (i.e. file `style-key.ssh'). The special style-key `binary' tells a2ps to consider that the file should not be printed, and will be ignored, unless option `--print-anyway' is given.

`** pattern style-key'

if the result of a call to file(1) matches pattern, then select style style-key. Note that only the first two fields of the answer of file(1) are considered. E.g., in the following case

gargantua $ file a2ps
a2ps:   ELF 32-bit MSB executable SPARC Version 1,\
        dynamically linked, stripped

`ELF32-bit' will be matched against pattern.

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

Two things are to retain from this:

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

Go to the first, previous, next, last section, table of contents.