1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
.\" 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.
|
