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
|
This directory has GL man pages.
./style gives some style guidelines.
./template is a template that can be used as a starting point
when writing new man pages.
./standard contains man page source and a Makefile for making
various targets using nroff and troff. The suffix
for man page source in this directory is '.gl'.
Two awk scripts and m4 are run over GL man page source before it is
processed in the same way that standard man pages are. This allows
a writer to avoid most annoying troff'isms.
Several macros are provided to simplify man page writing. These
are:
_header(name,desc)
Gives the name of the command to be used at the
top and bottom of the man page and in the _cmnd macro
(below). Also give the one line description of the
command.
_names(base,regexp)
_names(base,regexp,noheader)
Generates the 'C SPECIFICATIONS' for all forms of
a command with the indicated base name and an
extension matching the given regular expression.
This is done by using the name and expression to search the
known GL commands. A function header is generated for
each matching command. The second form of the command,
with a third argument (any argument will do) suppresses
the generation of the 'C SPECIFICATION' section heading
for the matched names (useful when a single man page
describes diverse commands).
_cmnd Without an argument, generates the correctly prefixed and
_cmnd(arg) capitalized base command name. Use \& (troff zero-width
space) to separate it from immediately following letters,
digits, underscores or parentheses. With an argument, it
generates the prefixed command name (currently the argument
is not matched against the known GL commands).
The command is automatically emboldened.
_param<i> Generates the italicized <i>th parameter to the command.
_param<i>(n) Without an argument, it gets the <i>th argument to forms
of the command matching the last _names() invocation.
With an argument, gives the <i>th argument to forms of
the command matching the nth _names() invocation.
_eqnparam<i> Same as _param, but does not italicize, and can therefore
_eqnparam<i>(n) be used in equations.
_phead(param) Used when generating a parameter description of 'param'.
Parameter description immediately follows.
_const(arg) Generates a prefixed and emboldened GL constant 'arg'.
_econst(arg) Same as _const but for use inside equations.
_hex(arg) Generates "0x'arg'".
_C_ Comment; everything following up to and including the next
newline is ignored
_define define an M4 macro. See the M4 man page. Most of the
M4 macros having common names that could clash with words
in the text have been undefined or redefined to have
underscores preceeding their names. Be sure to use _C_
(or M4's 'dnl') at the end of a macro definition to
avoid extraneous newlines in the troff source.
If '_filters' is defined before the use of '_header' (see the template
for an example that is commented out) then the processed text is run
through the shell commands given in '_filters' just before being sent to
troff. Useful when tables or equations appear in the text.
Two standard macros may be redefined in special situations. '_basename'
is the base command name. Normally it is set to the filename of the
man page being generated, sans suffix, and appears in the banner on
every page of the man page. 'gl' is automatically prepended to this
name. '_samething' is the message to be printed when there are
multiple commands under the same heading. See the template for
commented out examples.
Troff macro names .BR and .BP appear in various manpages. These are
placeholders for .br and .bp macros that were added for the Addison
Wesley publication, but are not valid for other printings. Since these
macros are not defined anywhere, they are ignored by troff/nroff.
A final and important note: the file MUST begin with an '_'
(probably as in '_header' or '_define(_filters,...)_C_) or
the aforementioned processing will not be applied and you will
be obliged to use the frightful standard man page troff constructs.
|
