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