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 (outside of the SEE ALSO
113 section, which just uses regular text), use:
119 Literal text (such as flags) should be in bold. Parameters
120 should be italicized. Mutually exclusive options (like
121 "-foo" and "-nofoo") should be grouped together and seperated
124 .RI [ +folder ] <---- parameter
125 .RI [ msgs ] <---- parameter
126 .RB [ \-version ] <---- flag
127 .RB [ \-editor <---- flag with
128 .IR editor ] parameter
129 .RB [ \-use " | " \-nouse ] <---- exclusive parameters
131 References to these flags or parameters in the body text of the
132 manpage should reflect these conventions:
134 You may not supply both a
143 In particular, don't enclose them in single quotes (except
144 in the DEFAULT section, which might be inconsistent, but
145 seems a little clearer.
147 For "-flag param" situations, try to use a .B/.I combination
148 instead of a single .BI, since it allows more flexibility in
149 case of punctuation, and we get an automatic space between
150 flag and param for free, without having to manual force it.
154 Use ".SS" to denote a subsection
158 The folder manpage has an example of a table.
163 .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
164 FOLDER \0\0\0\0\0\0# MESSAGES RANGE CUR (OTHERS)
165 ff has \0no messages.
166 inbox+ has \016 messages (\03\-\022); cur=\05.
167 mh has \076 messages (15\-\076); cur=70.
172 Other italicized text
174 Italicize file names, profile entries, and folder names:
177 .RI \*(lq components \*(rq
178 exists in the user's nmh directory,
180 If the user's profile contains a
181 .RI \*(lq "Msg\-Protect: nnn" \*(rq
184 The \*(lq+\*(rq after
186 indicates that it is the current folder.
188 Enclose the file names and profile entries in lq/rq
193 Certain manpages are shared between one or more programs
194 (such as folder/folders). The secondary program should
195 have a man page that only contains:
199 Also, add this manpage to the appropriate section in Makefile.in
203 Don't include a CONTEXT section when contexts are out of context.
206 AUTHOR and HISTORY sections
208 These have no place in a manpage. If you want everlasting glory,
209 try the release notes.
213 The BUGS section goes last.