1 NMH MANPAGE STYLE GUIDE
3 nmh manpages should be in this general form:
5 .TH COMP %manext1% "%nmhdate%" MH.6.8 [%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 In the FILES section, prefer the default .TP indent. The pathnames are
57 variable and long, so any indentation value that works for you won't
58 work for someone else.
63 There should be no ".so" commands to source an external file,
64 since these break on Linux, where the man program does not
65 allow source files outside the man/ hierarchy. Instead, insert
76 Of course, replace "components" with a unique identifier that
77 reflects the content being included, like "mts_conf" for
78 etc/mts.conf. Then, add two lines to the man.sed target in
81 echo '/%components%/r $(top_srcdir)/etc/components' >> $@
82 echo ' s,%components%,,g' >> $@
84 At compile time, the contents of the file will physically
85 incorporated into the body of the man page. This is somewhat
86 unfortunate, since later modifications won't be reflected in
87 the manpage, but on the other hand, the manpage will show the
88 default configuration and not local modifications.
92 All nmh program names should be bolded. If there is punctuation
93 after the name, use a .BR construct to avoid the automatic
94 space that's inserted with just a .B:
99 If this is a manpage reference (outside of the SEE ALSO
100 section, which just uses regular text), use:
106 Literal text (such as flags) should be in bold. Parameters
107 should be italicized. Mutually exclusive options (like
108 "-foo" and "-nofoo") should be grouped together and seperated
111 .RI [ +folder ] <---- parameter
112 .RI [ msgs ] <---- parameter
113 .RB [ \-version ] <---- flag
114 .RB [ \-editor <---- flag with
115 .IR editor ] parameter
116 .RB [ \-use " | " \-nouse ] <---- exclusive parameters
118 References to these flags or parameters in the body text of the
119 manpage should reflect these conventions:
121 You may not supply both a
130 In particular, don't enclose them in single quotes (except
131 in the DEFAULT section, which might be inconsistent, but
132 seems a little clearer.
134 For "-flag param" situations, try to use a .B/.I combination
135 instead of a single .BI, since it allows more flexibility in
136 case of punctuation, and we get an automatic space between
137 flag and param for free, without having to manual force it.
141 Use ".SS" to denote a subsection
145 The folder manpage has an example of a table.
150 .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
151 FOLDER \0\0\0\0\0\0# MESSAGES RANGE CUR (OTHERS)
152 ff has \0no messages.
153 inbox+ has \016 messages (\03\-\022); cur=\05.
154 mh has \076 messages (15\-\076); cur=70.
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
180 Certain manpages are shared between one or more programs
181 (such as folder/folders). The secondary program should
182 have a man page that only contains:
186 Also, add this manpage to the appropriate section in Makefile.in