1 NMH MANPAGE STYLE GUIDE
2 =======================
4 Nmh manpages generally follow the traditional Bell Labs formatting
5 conventions. We do adopt a few conventions from BSD (primarily,
6 section ordering), and have a few of our own (mostly related to
12 Proper sentences end with a period followed by a newline:
15 It is followed by another, longer, sentence, but
16 which makes no more sense than the previous one.
20 This is a sentence. It is followed by another,
21 longer, sentence, but which makes no more sense
22 than the previous one.
24 This allows troff to set the correct inter-sentence spacing
25 based on the output device.
27 When quoting, use \*(lq and \*(rq. This ensures correct
28 formatting on typesetter-like devices.
30 A man page's source is ASCII, not UTF-8. troff has escapes for
31 non-ASCII characters, e.g. \(em for an em-dash, U+2014, that are
32 mapped onto whatever the output device supports, e.g. UTF-8 or
38 Always present sections in the following order:
54 Sections marked with a [*] are mandatory. Only include
55 the others if they are specifically applicable.
57 DIAGNOSTICS must document any non-zero exit codes, and can
58 provide context to error messages. Obviously it only applies
59 to section 1 and 8 manpages.
64 The DATE in the .TH macro is in `yyyy-mm-dd' format, and should
65 reflect the most recent *non-trivial* update to the *content* of
66 the manpage; formatting changes don't count, nor does expanding
67 the `SEE ALSO' list. Ask "Would the familiar user wish to
68 re-read this page to learn of this change?"
73 In running text, nmh program names should be set in bold,
74 unless you are explicitly referring to the command's
75 documentation, in which case use manpage cross-reference
82 Be careful when referring to programs that are not part of
83 nmh itself. For commands that are almost guaranteed to be
84 part of the base OS, use a manpage cross-reference (e.g.
85 ".IR cat (1)"). For other third-party utilities, it might
86 be best to set the command name in double quotes. Use your
87 best judgement to make it clear when you're referring to
88 tools that might not be present.
93 Set literal text (such as flags) in bold. Set parameters
94 in italic. Mutually exclusive options (like "-foo" and
95 "-nofoo") should be grouped together and separated by a
98 .RI [ +folder ] <---- parameter
99 .RI [ msgs ] <---- parameter
100 .RB [ \-version ] <---- flag
101 .RB [ \-editor <---- flag with
102 .IR editor ] parameter
103 .RB [ \-use " | " \-nouse ] <---- exclusive parameters
105 References to these flags or parameters in the body text of the
106 manpage should reflect these conventions:
108 You may not supply both a
117 In particular, don't enclose them in single quotes.
119 For "-flag param" situations, try to use a .B/.I combination
120 instead of a single .BI, since it allows more flexibility in
121 case of punctuation, and we get an automatic space between
122 flag and param for free, without having to manual force it.
127 Use ".SS" to denote a subsection
132 The folder manpage has an example of a table.
137 .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
138 FOLDER \0\0\0\0\0\0# MESSAGES RANGE CUR (OTHERS)
139 ff has \0no messages.
140 inbox+ has \016 messages (\03\-\022); cur=\05.
141 mh has \076 messages (15\-\076); cur=70.
147 Environment Variables
149 These are always set in roman text. The surrounding text
150 should make clear you are referring to an environment
151 variable. In some cases, like when dealing with all-lower-case
152 variable names, setting the name inside double quotes can
153 help clarify the context.
155 Never prepend a '$' character to an environment variable
156 name, unless you are directly referring to a variable
157 substitution in, say, a pathname.
160 Other Italicized Text
162 Italicize file names, profile entries, and folder names:
165 .RI \*(lq components \*(rq
166 exists in the user's nmh directory,
168 If the user's profile contains a
169 .RI \*(lq "Msg\-Protect: nnn" \*(rq
172 The \*(lq+\*(rq after
174 indicates that it is the current folder.
176 Enclose the file names and profile entries in lq/rq
182 Use .RS 5 / .RE to indent paragraphs, etc. '.IP 5' can
183 be useful, too. Try to use an offset of '5' as much as
184 possible to maintain visual consistency.
189 In PROFILE COMPONENTS, DEFAULTS, ENVIRONMENT, and FILES,
190 use tagged paragraphs with an offset of 20. Do not set
191 the tag in bold or italic, or wrap it in quotes, unless
192 this is absolutely necessary to make the context clear.
198 defaults to the current folder
206 -decodetypes text,application/ics
214 There should be no ".so" commands to source an external file,
215 since these break on Linux, where the man program does not
216 allow source files outside the man/ hierarchy. Instead, insert
227 Of course, replace "components" with a unique identifier that
228 reflects the content being included, like "mts_conf" for
229 etc/mts.conf. Then, add two lines to the man.sed target in
232 echo '/%components%/r $(top_srcdir)/etc/components' >> $@
233 echo ' s,%components%,,g' >> $@
235 At compile time, the contents of the file will physically
236 incorporated into the body of the man page. This is somewhat
237 unfortunate, since later modifications won't be reflected in
238 the manpage, but on the other hand, the manpage will show the
239 default configuration and not local modifications.
244 Certain manpages are shared between one or more programs
245 (such as folder/folders). The secondary program should
246 have a man page that only contains:
250 Also, add this manpage to the appropriate section in Makefile.in
252 AUTHOR and HISTORY Sections
254 These have no place in a manpage. If you want everlasting
255 glory, try the release notes. But note that a HISTORY
256 section might be appropriate for documenting incompatibility
257 with older versions of MH.
259 Common errors and subjective conventions
261 Try to mention `nmh' in the NAME section if it's not too awkward.
262 The command-line `-foo' is an option, not a switch.
263 Describe the default behaviour, then how it can be altered,
265 It's `see foo(1)', not `see the foo(1) man page for more detail'.
267 A hyphen is input as an ASCII minus sign, `non-standard',
268 not as `\-' which is the input to output a minus sign.
269 Use an unbreakable space for RFCs: `RFC\ 822'.
270 Hyphenate compound adjectives, e.g. `mail-drop format'.
271 Don't SHOUT for emphasis.
272 Use `.I' for normal emphasis and `.B' for strongest.
274 Use `Unix', not `UNIX'.
275 Use `zeroed', not `zero'd'.
276 Use `mail drop', not `maildrop' or `drop box'.
277 Use `messages', not `message(s)', ditto `folders', etc.
278 Use `e.g.', not `eg.', and `i.e.', not `ie.'.
280 Use a pair of commas, like this, for parenthetical asides.
281 Use `that' when the clause is essential, without a comma.
282 Use comma then `which' when it's non-essential.
283 `Hence' means `from here'; it's `thus' to introduce a conclusion.
285 ------------------------------------------------------------------------------
287 [ This template is a bit behind the times. I will bring it into
288 conformance with the notes above once the notes settle down.
292 .TH COMP %manext1% "DATE" "%nmhversion%"
297 comp \- compose a message
307 .RB [ \-use " | " \-nouse ]
313 is used to create a new message to be mailed.
316 .SH "PROFILE COMPONENTS"
319 Location of the user's MH folder directory
322 The pager command name
327 defaults to the current folder
335 description of filename1
338 description of filename2
347 .\" Leave out the BUGS section if there are none worth describing.
projects / nmh / blob