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 Don't use UTF-8 characters in the manpage source. We still
31 build and run on systems that can't handle this. And most
32 anything you would want to use has an internal troff character
33 escape sequence, anyway.
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 should reflect the most recent
65 *non-trivial* update to the *content* of the manpage;
66 formatting changes don't count, nor does expanding the `SEE
67 ALSO' list. The date is in `yyyy-mm-dd' format.
72 In running text, nmh program names should be set in bold,
73 unless you are explicitly referring to the command's
74 documentation, in which case use manpage cross-reference
81 Be careful when referring to programs that are not part of
82 nmh itself. For commands that are almost guaranteed to be
83 part of the base OS, use a manpage cross-reference (e.g.
84 ".IR cat (1)"). For other third-party utilities, it might
85 be best to set the command name in double quotes. Use your
86 best judgement to make it clear when you're referring to
87 tools that might not be present.
92 Set literal text (such as flags) in bold. Set parameters
93 in italic. Mutually exclusive options (like "-foo" and
94 "-nofoo") should be grouped together and separated by a
97 .RI [ +folder ] <---- parameter
98 .RI [ msgs ] <---- parameter
99 .RB [ \-version ] <---- flag
100 .RB [ \-editor <---- flag with
101 .IR editor ] parameter
102 .RB [ \-use " | " \-nouse ] <---- exclusive parameters
104 References to these flags or parameters in the body text of the
105 manpage should reflect these conventions:
107 You may not supply both a
116 In particular, don't enclose them in single quotes.
118 For "-flag param" situations, try to use a .B/.I combination
119 instead of a single .BI, since it allows more flexibility in
120 case of punctuation, and we get an automatic space between
121 flag and param for free, without having to manual force it.
126 Use ".SS" to denote a subsection
131 The folder manpage has an example of a table.
136 .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
137 FOLDER \0\0\0\0\0\0# MESSAGES RANGE CUR (OTHERS)
138 ff has \0no messages.
139 inbox+ has \016 messages (\03\-\022); cur=\05.
140 mh has \076 messages (15\-\076); cur=70.
146 Environment Variables
148 These are always set in roman text. The surrounding text
149 should make clear you are referring to an environment
150 variable. In some cases, like when dealing with all-lower-case
151 variable names, setting the name inside double quotes can
152 help clarify the context.
154 Never prepend a '$' character to an environment variable
155 name, unless you are directly referring to a variable
156 substitution in, say, a pathname.
159 Other Italicized Text
161 Italicize file names, profile entries, and folder names:
164 .RI \*(lq components \*(rq
165 exists in the user's nmh directory,
167 If the user's profile contains a
168 .RI \*(lq "Msg\-Protect: nnn" \*(rq
171 The \*(lq+\*(rq after
173 indicates that it is the current folder.
175 Enclose the file names and profile entries in lq/rq
181 Use .RS 5 / .RE to indent paragraphs, etc. '.IP 5' can
182 be useful, too. Try to use an offset of '5' as much as
183 possible to maintain visual consistency.
188 In PROFILE COMPONENTS, DEFAULTS, ENVIRONMENT, and FILES,
189 use tagged paragraphs with an offset of 20. Do not set
190 the tag in bold or italic, or wrap it in quotes, unless
191 this is absolutely necessary to make the context clear.
197 defaults to the current folder
205 -decodetypes text,application/ics
213 There should be no ".so" commands to source an external file,
214 since these break on Linux, where the man program does not
215 allow source files outside the man/ hierarchy. Instead, insert
226 Of course, replace "components" with a unique identifier that
227 reflects the content being included, like "mts_conf" for
228 etc/mts.conf. Then, add two lines to the man.sed target in
231 echo '/%components%/r $(top_srcdir)/etc/components' >> $@
232 echo ' s,%components%,,g' >> $@
234 At compile time, the contents of the file will physically
235 incorporated into the body of the man page. This is somewhat
236 unfortunate, since later modifications won't be reflected in
237 the manpage, but on the other hand, the manpage will show the
238 default configuration and not local modifications.
243 Certain manpages are shared between one or more programs
244 (such as folder/folders). The secondary program should
245 have a man page that only contains:
249 Also, add this manpage to the appropriate section in Makefile.in
251 AUTHOR and HISTORY Sections
253 These have no place in a manpage. If you want everlasting
254 glory, try the release notes. But note that a HISTORY
255 section might be appropriate for documenting incompatibility
256 with older versions of MH.
258 ------------------------------------------------------------------------------
260 [ This template is a bit behind the times. I will bring it into
261 conformance with the notes above once the notes settle down.
265 .TH COMP %manext1% "DATE" "%nmhversion%"
270 comp \- compose a message
280 .RB [ \-use " | " \-nouse ]
286 is used to create a new message to be mailed.
289 .SH "PROFILE COMPONENTS"
292 Location of the user's MH folder directory
295 The pager command name
300 defaults to the current folder
308 description of filename1
311 description of filename2
320 .\" Leave out the BUGS section if there are none worth describing.
projects / nmh / blob