.\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.)
.\" Copyright (c) 2002 Colin Watson.
.\"
.\" You may distribute under the terms of the GNU General Public
.\" License as specified in the file docs/COPYING.GPLv2 that comes with the
.\" man-db distribution.
.\"
.\" Thu Sep 21 19:22:47 BST 1995  Wilf. (G.Wilford@ee.surrey.ac.uk)
.\"
.BS 1 "Formatting"
.lp
As already pointed out in the introduction, there are two primary
formatters common to \*U: \*N and \*T.
.lp
In the following sections, I
will use the term \*T to describe the typesetter formatter and \*N to
describe the typewriter formatter.
The term \*R will be used to describe a generic formatter.
.BS 2 "\*G"
.lp
If using the \*G package, there is a further choice, \*G itself.
Essentially, \*G forms a pipeline of processors including \*T and an output
processor which translates the ditroff produced by \*T into the appropriate
output format.
The default output format, or device, for \*G is \*P.
Anything else must be specified using the device argument.
To illustrate \*G, the command
.ip
.bx "groff \-Tdvi /dev/null"
.lp
will form the following pipeline
.ip
troff \-Tdvi /dev/null | grodvi
.lp
If \*G is tied to
.b man 's
.b \-T
option, it is still possible for
.b man
to produce ditroff via use of the
.b \-Z
option.
.lp
In \*G 1.09, \*N is bundled as a shell script that calls \*G, which in turn
calls \*T with the default options
.b "\-Wall \-mtty-char \-Tascii" ,
passing the result through
.b grotty
before it finally reaches the screen.
.lp
It is imperative that the script does not pass pre-processing options
to \*G's
command line as
.b man
takes care of this separately.
.BS 2 Devices
.lp
Both \*N and \*G may allow output device selection.
As mentioned previously,
classic \*N produces output suitable for a typewriter device, classic
\*T produces output suitable for a
.b C/A/T
and \*G produces output suitable for a \*P interpreting device by default.
.BS 2 "Macros"
.lp
There are several \*R macro sets in existence that are suitable for manual
pages.
Unfortunately, they tend to be incompatible with each other.
.lp
During configuration,
.b configure
will attempt to determine a suitable macro set for the local system's manual
page collection.
It attempts to use \*N with the following three macro packages:

.TS
center box tab(@);
l | l | l .
macro package@macro filename@nroff command
_
andoc@tmac.andoc or andoc.tmac@nroff \-mandoc
an@tmac.an or an.tmac@nroff \-man
doc@tmac.doc or doc.tmac@nroff \-mdoc
.TE

The first that succeeds is used.
The
.b andoc
macro set is suitable for manual pages written using either
.b an
or
.b doc
macro commands, but not a combination of both.
.lp
.BS 2 "Pre-format processors (pre-processors)"
.lp
Manual pages may require pre-processing by any of the following

.TS
center box tab(@);
l | l | l .
Program@ID@Pre-processes
_
eqn@e@equations
tbl@t@tables
grap@g@graphs
pic@p@pictures
refer@r@A bibliography
vgrind@v@program listings
.TE

It is possible to assign a default pre-processor list that all
manual pages will be passed through prior to the primary formatter.
By default, this is empty.
To define a default list, edit
.i include/manconfig.h
and un-comment the following line
.lp
/* #define DEFAULT_MANROFFSEQ   "t" */
.lp
which will enable
.b tbl
processing by default.
To change the list, replace the
.b t
with a suitable string of processor ID's.
.lp
Pre-process options may be provided at run time in various forms, but in
general the pre-processors required by each manual page is indicated in the
first line of the manual page itself.
See
.b man (1)
for details.
.lp
If a manual page does not contain a pre-processor string in its first line,
it will be scanned for well-known \*R requests used to pass input to
certain pre-processors.
Thus, the pre-processor string is often unnecessary for correct output,
but should nevertheless be included for efficiency.
.BS 2 "Format scripts"
.lp
It is very likely that alternate systems manual pages may require
non-standard macro packages or possibly even special pre-processors.
To tackle such problems, special format scripts may be created on a per
manual hierarchy basis.
.lp
If the file
.ip
.i <manual_hierarchy>/mandb_nfmt
.lp
exists and is executable, it is expected to be able to correctly format a
manual page originating from
.i <manual_hierarchy>
to its standard output.
It will be supplied with either two or three arguments:
.(l
\(bu manual page filename
\(bu pre-processor string
\(bu output device (optional)
.)l
Similarly, if the option
.b \-T\c
.i <device>
.r
or
.b \-t
was supplied to
.b man
and the file
.ip
.i <manual_hierarchy>/mandb_tfmt
.lp
exists and is executable, it will be used in the same way.
.lp
An example of such a script, supplied by Markus Armbruster
<armbru@pond.sub.org>, who provided support for external formatter scripts,
can be found as
.i tools/mandb_fmt\-script
.lp
The script can be used as both an \*N and \*T/\*G format script and can be
installed as
.i mandb_nfmt
and hard linked to
.i mandb_tfmt
after modification appropriate for your particular site.