1 NMH MANPAGE STYLE GUIDE
3 nmh manpages should be in this general form:
5 .TH COMP %manext1% "DATE" "%nmhversion%"
10 comp \- compose a message
17 .RB [ \-use " | " \-nouse ]
22 is used to create a new message to be mailed. It copies something.
26 description of filename1
29 description of filename2
30 .SH "PROFILE COMPONENTS"
33 Location of the user's MH folder directory
36 The pager command name
47 defaults to the current folder
51 .\" Leave out the BUGS section if there are none worth describing.
55 ---------------------------------------
56 The DATE in the .TH macro should reflect the most recent non-trivial
57 update to the content of the manpage; formatting changes don't count.
58 Spell out the date (no abbreviations or shortcuts):
66 Don't abbreviate the month.
69 In the FILES section, prefer the default .TP indent. The pathnames are
70 variable and long, so any indentation value that works for you won't
71 work for someone else.
76 There should be no ".so" commands to source an external file,
77 since these break on Linux, where the man program does not
78 allow source files outside the man/ hierarchy. Instead, insert
89 Of course, replace "components" with a unique identifier that
90 reflects the content being included, like "mts_conf" for
91 etc/mts.conf. Then, add two lines to the man.sed target in
94 echo '/%components%/r $(top_srcdir)/etc/components' >> $@
95 echo ' s,%components%,,g' >> $@
97 At compile time, the contents of the file will physically
98 incorporated into the body of the man page. This is somewhat
99 unfortunate, since later modifications won't be reflected in
100 the manpage, but on the other hand, the manpage will show the
101 default configuration and not local modifications.
105 All nmh program names should be bolded. If there is punctuation
106 after the name, use a .BR construct to avoid the automatic
107 space that's inserted with just a .B:
112 If this is a manpage reference, use:
118 Literal text (such as flags) should be in bold. Parameters
119 should be italicized. Mutually exclusive options (like
120 "-foo" and "-nofoo") should be grouped together and seperated
123 .RI [ +folder ] <---- parameter
124 .RI [ msgs ] <---- parameter
125 .RB [ \-version ] <---- flag
126 .RB [ \-editor <---- flag with
127 .IR editor ] parameter
128 .RB [ \-use " | " \-nouse ] <---- exclusive parameters
130 References to these flags or parameters in the body text of the
131 manpage should reflect these conventions:
133 You may not supply both a
142 In particular, don't enclose them in single quotes (except
143 in the DEFAULT section, which might be inconsistent, but
144 seems a little clearer.
146 For "-flag param" situations, try to use a .B/.I combination
147 instead of a single .BI, since it allows more flexibility in
148 case of punctuation, and we get an automatic space between
149 flag and param for free, without having to manual force it.
153 Use ".SS" to denote a subsection
157 The folder manpage has an example of a table.
162 .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
163 FOLDER \0\0\0\0\0\0# MESSAGES RANGE CUR (OTHERS)
164 ff has \0no messages.
165 inbox+ has \016 messages (\03\-\022); cur=\05.
166 mh has \076 messages (15\-\076); cur=70.
171 Other italicized text
173 Italicize file names, profile entries, and folder names:
176 .RI \*(lq components \*(rq
177 exists in the user's nmh directory,
179 If the user's profile contains a
180 .RI \*(lq "Msg\-Protect: nnn" \*(rq
183 The \*(lq+\*(rq after
185 indicates that it is the current folder.
187 Enclose the file names and profile entries in lq/rq
192 Certain manpages are shared between one or more programs
193 (such as folder/folders). The secondary program should
194 have a man page that only contains:
198 Also, add this manpage to the appropriate section in Makefile.in
202 Don't include a CONTEXT section when contexts are out of context.
205 AUTHOR and HISTORY sections
207 These have no place in a manpage. If you want everlasting glory,
208 try the release notes.
212 The BUGS section goes last.