1 NMH MANPAGE STYLE GUIDE
3 nmh manpages should be in this general form:
9 .TH COMP %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
11 comp \- compose a message
19 .RB [ \-use " | " \-nouse ]
24 is used to create a new message to be mailed. It copies something.
29 .ta \w'/usr/local/nmh/etc/ExtraBigFileName 'u
30 ^%etcdir%/components~^The standard message skeleton
32 .SH "PROFILE COMPONENTS"
36 .ta \w'ExtraBigProfileName 'u
37 ^Path:~^To determine the user's nmh directory
40 dist(1), forw(1), repl(1), send(1), whatnow(1), mh-profile(5)
44 .RB ` +folder "' defaults to the current folder"
52 ---------------------------------------
53 In the FILES section, use a spacer of "/usr/local/nmh/etc" for now,
54 we'll parametrize that into %etcdir% later.
59 There should be no ".so" commands to source an external file,
60 since these break on Linux, where the man program does not
61 allow source files outside the man/ hierarchy. Instead, insert
72 Of course, replace "components" with a unique identifier that
73 reflects the content being included, like "mts_conf" for
74 etc/mts.conf. Then, add two lines to the man.sed target in
77 echo '/%components%/r $(top_srcdir)/etc/components' >> $@
78 echo ' s,%components%,,g' >> $@
80 At compile time, the contents of the file will physically
81 incorporated into the body of the man page. This is somewhat
82 unfortunate, since later modifications won't be reflected in
83 the manpage, but on the other hand, the manpage will show the
84 default configuration and not local modifications.
88 All nmh program names should be bolded. If there is punctuation
89 after the name, use a .BR construct to avoid the automatic
90 space that's inserted with just a .B:
95 If this is a manpage reference (outside of the SEE ALSO
96 section, which just uses regular text), use:
102 Literal text (such as flags) should be in bold. Parameters
103 should be italicized. Mutually exclusive options (like
104 "-foo" and "-nofoo") should be grouped together and seperated
107 .RI [ +folder ] <---- parameter
108 .RI [ msgs ] <---- parameter
109 .RB [ \-version ] <---- flag
110 .RB [ \-editor <---- flag with
111 .IR editor ] parameter
112 .RB [ \-use " | " \-nouse ] <---- exclusive parameters
114 References to these flags or parameters in the body text of the
115 manpage should reflect these conventions:
117 You may not supply both a
126 In particular, don't enclose them in single quotes (except
127 in the DEFAULT section, which might be inconsistent, but
128 seems a little clearer.
130 For "-flag param" situations, try to use a .B/.I combination
131 instead of a single .BI, since it allows more flexibility in
132 case of punctuation, and we get an automatic space between
133 flag and param for free, without having to manual force it.
137 Use ".SS" to denote a subsection
141 The folder manpage has an example of a table.
146 .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
147 FOLDER \0\0\0\0\0\0# MESSAGES RANGE CUR (OTHERS)
148 ff has \0no messages.
149 inbox+ has \016 messages (\03\-\022); cur=\05.
150 mh has \076 messages (15\-\076); cur=70.
155 Other italicized text
157 Italicize file names, profile entries, and folder names:
160 .RI \*(lq components \*(rq
161 exists in the user's nmh directory,
163 If the user's profile contains a
164 .RI \*(lq "Msg\-Protect: nnn" \*(rq
167 The \*(lq+\*(rq after
169 indicates that it is the current folder.
171 Enclose the file names and profile entries in lq/rq
176 Certain manpages are shared between one or more programs
177 (such as folder/folders). The secondary program should
178 have a man page that only contains:
182 Also, add this manpage to the appropriate section in Makefile.in