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
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
NMH MANPAGE STYLE GUIDE
nmh manpages should be in this general form and section order:
.TH COMP %manext1% "DATE" "%nmhversion%"
.\"
.\" %nmhwarning%
.\"
.SH NAME
comp \- compose a message
.\"
.SH SYNOPSIS
.HP 5
.na
.B comp
.RI [ +folder ]
.RI [ msgs ]
.RB [ \-form
.IR formfile ]
.RB [ \-use " | " \-nouse ]
.RB [ \-version ]
.RB [ \-help ]
.ad
.SH DESCRIPTION
.B Comp
is used to create a new message to be mailed. It copies something.
.\"
.SH "PROFILE COMPONENTS"
.TP
Path
Location of the user's MH folder directory
.TP
moreproc
The pager command name
.\"
.SH DEFAULTS
.TP
.RI + folder
defaults to the current folder
.\"
.SH CONTEXT
None
.\"
.SH FILES
.TP
filename1
description of filename1
.TP
filename2
description of filename2
.\"
.SH "SEE ALSO"
.BR dist (1),
.BR forw (1),
.BR repl (1),
.BR send (1),
.BR whatnow (1),
.BR mh-profile (5)
.\" Leave out the BUGS section if there are none worth describing.
.SH BUGS
None
---------------------------------------
The DATE in the .TH macro should reflect the most recent non-trivial
update to the content of the manpage; formatting changes don't count.
Spell out the date (no abbreviations or shortcuts):
January 2, 1904
not the unparseable
01/02/04
Don't abbreviate the month.
In the FILES section, prefer the default .TP indent. The pathnames are
variable and long, so any indentation value that works for you won't
work for someone using a different directory layout.
Source files
There should be no ".so" commands to source an external file,
since these break on Linux, where the man program does not
allow source files outside the man/ hierarchy. Instead, insert
this fragment:
.PP
.RS 5
.nf
%components%
.fi
.RE
.PP
Of course, replace "components" with a unique identifier that
reflects the content being included, like "mts_conf" for
etc/mts.conf. Then, add two lines to the man.sed target in
Makefile.in like:
echo '/%components%/r $(top_srcdir)/etc/components' >> $@
echo ' s,%components%,,g' >> $@
At compile time, the contents of the file will physically
incorporated into the body of the man page. This is somewhat
unfortunate, since later modifications won't be reflected in
the manpage, but on the other hand, the manpage will show the
default configuration and not local modifications.
Program names
All nmh program names should be bolded. If there is punctuation
after the name, use a .BR construct to avoid the automatic
space that's inserted with just a .B:
.B comp
.BR comp ,
The first reference to a documented command should be in the form of
a manpage reference:
.BR comp (1)
SYNPOSIS section
Literal text (such as flags) should be in bold. Parameters
should be italicized. Mutually exclusive options (like
"-foo" and "-nofoo") should be grouped together and seperated
by a "|":
.RI [ +folder ] <---- parameter
.RI [ msgs ] <---- parameter
.RB [ \-version ] <---- flag
.RB [ \-editor <---- flag with
.IR editor ] parameter
.RB [ \-use " | " \-nouse ] <---- exclusive parameters
References to these flags or parameters in the body text of the
manpage should reflect these conventions:
You may not supply both a
.B \-form
.I formfile
and a
.I +folder
or
.I msg
argument.
In particular, don't enclose them in single quotes (except
in the DEFAULT section, which might be inconsistent, but
seems a little clearer.
For "-flag param" situations, try to use a .B/.I combination
instead of a single .BI, since it allows more flexibility in
case of punctuation, and we get an automatic space between
flag and param for free, without having to manual force it.
Subsections
Use ".SS" to denote a subsection
Tables
The folder manpage has an example of a table.
.PP
.RS 5
.nf
.ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
FOLDER \0\0\0\0\0\0# MESSAGES RANGE CUR (OTHERS)
ff has \0no messages.
inbox+ has \016 messages (\03\-\022); cur=\05.
mh has \076 messages (15\-\076); cur=70.
.fi
.RE
.PP
Other italicized text
Italicize file names, profile entries, and folder names:
If a file named
.RI \*(lq components \*(rq
exists in the user's nmh directory,
If the user's profile contains a
.RI \*(lq "Msg\-Protect: nnn" \*(rq
entry, it
The \*(lq+\*(rq after
.I inbox
indicates that it is the current folder.
Enclose the file names and profile entries in lq/rq
quotes, too.
Pointer manpages
Certain manpages are shared between one or more programs
(such as folder/folders). The secondary program should
have a man page that only contains:
.so man1/folder.1
Also, add this manpage to the appropriate section in Makefile.in
CONTEXT
Don't include a CONTEXT section when contexts are not
applicable.
AUTHOR and HISTORY sections
These have no place in a manpage. If you want everlasting glory,
try the release notes.
BUGS
The BUGS section goes last.
|
