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. Spell out the date (no
67 abbreviations or shortcuts):
75 Don't abbreviate the month.
80 In running text, nmh program names should be set in bold,
81 unless you are explicitly referring to the command's
82 documentation, in which case use manpage cross-reference
89 Be careful when referring to programs that are not part of
90 nmh itself. For commands that are almost guaranteed to be
91 part of the base OS, use a manpage cross-reference (e.g.
92 ".IR cat (1)"). For other third-party utilities, it might
93 be best to set the command name in double quotes. Use your
94 best judgement to make it clear when you're referring to
95 tools that might not be present.
100 Set literal text (such as flags) in bold. Set parameters
101 in italic. Mutually exclusive options (like "-foo" and
102 "-nofoo") should be grouped together and separated by a
105 .RI [ +folder ] <---- parameter
106 .RI [ msgs ] <---- parameter
107 .RB [ \-version ] <---- flag
108 .RB [ \-editor <---- flag with
109 .IR editor ] parameter
110 .RB [ \-use " | " \-nouse ] <---- exclusive parameters
112 References to these flags or parameters in the body text of the
113 manpage should reflect these conventions:
115 You may not supply both a
124 In particular, don't enclose them in single quotes.
126 For "-flag param" situations, try to use a .B/.I combination
127 instead of a single .BI, since it allows more flexibility in
128 case of punctuation, and we get an automatic space between
129 flag and param for free, without having to manual force it.
134 Use ".SS" to denote a subsection
139 The folder manpage has an example of a table.
144 .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
145 FOLDER \0\0\0\0\0\0# MESSAGES RANGE CUR (OTHERS)
146 ff has \0no messages.
147 inbox+ has \016 messages (\03\-\022); cur=\05.
148 mh has \076 messages (15\-\076); cur=70.
154 Environment Variables
156 These are always set in roman text. The surrounding text
157 should make clear you are referring to an environment
158 variable. In some cases, like when dealing with all-lower-case
159 variable names, setting the name inside double quotes can
160 help clarify the context.
162 Never prepend a '$' character to an environment variable
163 name, unless you are directly referring to a variable
164 substitution in, say, a pathname.
167 Other Italicized Text
169 Italicize file names, profile entries, and folder names:
172 .RI \*(lq components \*(rq
173 exists in the user's nmh directory,
175 If the user's profile contains a
176 .RI \*(lq "Msg\-Protect: nnn" \*(rq
179 The \*(lq+\*(rq after
181 indicates that it is the current folder.
183 Enclose the file names and profile entries in lq/rq
189 Use .RS 5 / .RE to indent paragraphs, etc. '.IP 5' can
190 be useful, too. Try to use an offset of '5' as much as
191 possible to maintain visual consistency.
196 In PROFILE COMPONENTS, DEFAULTS, ENVIRONMENT, and FILES,
197 use tagged paragraphs with an offset of 20. Do not set
198 the tag in bold or italic, or wrap it in quotes, unless
199 this is absolutely necessary to make the context clear.
205 defaults to the current folder
213 -decodetypes text,application/ics
221 There should be no ".so" commands to source an external file,
222 since these break on Linux, where the man program does not
223 allow source files outside the man/ hierarchy. Instead, insert
234 Of course, replace "components" with a unique identifier that
235 reflects the content being included, like "mts_conf" for
236 etc/mts.conf. Then, add two lines to the man.sed target in
239 echo '/%components%/r $(top_srcdir)/etc/components' >> $@
240 echo ' s,%components%,,g' >> $@
242 At compile time, the contents of the file will physically
243 incorporated into the body of the man page. This is somewhat
244 unfortunate, since later modifications won't be reflected in
245 the manpage, but on the other hand, the manpage will show the
246 default configuration and not local modifications.
251 Certain manpages are shared between one or more programs
252 (such as folder/folders). The secondary program should
253 have a man page that only contains:
257 Also, add this manpage to the appropriate section in Makefile.in
259 AUTHOR and HISTORY Sections
261 These have no place in a manpage. If you want everlasting
262 glory, try the release notes. But note that a HISTORY
263 section might be appropriate for documenting incompatibility
264 with older versions of MH.
266 ------------------------------------------------------------------------------
268 [ This template is a bit behind the times. I will bring it into
269 conformance with the notes above once the notes settle down.
273 .TH COMP %manext1% "DATE" "%nmhversion%"
278 comp \- compose a message
288 .RB [ \-use " | " \-nouse ]
294 is used to create a new message to be mailed.
297 .SH "PROFILE COMPONENTS"
300 Location of the user's MH folder directory
303 The pager command name
308 defaults to the current folder
316 description of filename1
319 description of filename2
328 .\" Leave out the BUGS section if there are none worth describing.
projects / nmh / blob