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 ---------------------------------------------------------------------
57 The DATE in the .TH macro should reflect the most recent non-trivial
58 update to the content of the manpage; formatting changes don't count.
59 Spell out the date in English prose: Month Day, Year
68 Don't include a CONTEXT section if contexts don't directly apply to what the
72 In the FILES section, prefer the default .TP indent. The pathnames are
73 variable and long, so any indentation value that works for you won't
74 work for someone else.
77 The BUGS section goes last.
82 There should be no ".so" commands to source an external file,
83 since these break on Linux, where the man program does not
84 allow source files outside the man/ hierarchy. Instead, insert
95 Of course, replace "components" with a unique identifier that
96 reflects the content being included, like "mts_conf" for
97 etc/mts.conf. Then, add two lines to the man.sed target in
100 echo '/%components%/r $(top_srcdir)/etc/components' >> $@
101 echo ' s,%components%,,g' >> $@
103 At compile time, the contents of the file will physically
104 incorporated into the body of the man page. This is somewhat
105 unfortunate, since later modifications won't be reflected in
106 the manpage, but on the other hand, the manpage will show the
107 default configuration and not local modifications.
111 All nmh program names should be bolded. If there is punctuation
112 after the name, use a .BR construct to avoid the automatic
113 space that's inserted with just a .B:
118 If this is a manpage reference (outside of the SEE ALSO
119 section, which just uses regular text), use:
125 Literal text (such as flags) should be in bold. Parameters
126 should be italicized. Mutually exclusive options (like
127 "-foo" and "-nofoo") should be grouped together and seperated
130 .RI [ +folder ] <---- parameter
131 .RI [ msgs ] <---- parameter
132 .RB [ \-version ] <---- flag
133 .RB [ \-editor <---- flag with
134 .IR editor ] parameter
135 .RB [ \-use " | " \-nouse ] <---- exclusive parameters
137 References to these flags or parameters in the body text of the
138 manpage should reflect these conventions:
140 You may not supply both a
149 In particular, don't enclose them in single quotes (except
150 in the DEFAULT section, which might be inconsistent, but
151 seems a little clearer.
153 For "-flag param" situations, try to use a .B/.I combination
154 instead of a single .BI, since it allows more flexibility in
155 case of punctuation, and we get an automatic space between
156 flag and param for free, without having to manual force it.
160 Use ".SS" to denote a subsection
164 The folder manpage has an example of a table.
169 .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
170 FOLDER \0\0\0\0\0\0# MESSAGES RANGE CUR (OTHERS)
171 ff has \0no messages.
172 inbox+ has \016 messages (\03\-\022); cur=\05.
173 mh has \076 messages (15\-\076); cur=70.
178 Other italicized text
180 Italicize file names, profile entries, and folder names:
183 .RI \*(lq components \*(rq
184 exists in the user's nmh directory,
186 If the user's profile contains a
187 .RI \*(lq "Msg\-Protect: nnn" \*(rq
190 The \*(lq+\*(rq after
192 indicates that it is the current folder.
194 Enclose the file names and profile entries in lq/rq
199 Certain manpages are shared between one or more programs
200 (such as folder/folders). The secondary program should
201 have a man page that only contains:
205 Also, add this manpage to the appropriate section in Makefile.in