Require at least 2 chars for `no' variants of switches.
[mmh] / docs / README.manpages
1 NMH MANPAGE STYLE GUIDE
2
3 nmh manpages should be in this general form:
4
5 .\"
6 .\" %nmhwarning%
7 .\"
8 .TH COMP %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
9 .SH NAME
10 comp \- compose a message
11 .SH SYNOPSIS
12 .HP 5
13 .B comp
14 .RI [ +folder ]
15 .RI [ msgs ]
16 .RB [ \-form
17 .IR formfile ]
18 .RB [ \-use " | " \-nouse ]
19 .RB [ \-Version ]
20 .RB [ \-help ]
21 .SH DESCRIPTION
22 .B Comp
23 is used to create a new message to be mailed.  It copies something.
24
25 .SH FILES
26 .fc ^ ~
27 .nf
28 .ta \w'/usr/local/nmh/etc/ExtraBigFileName  'u
29 ^%etcdir%/components~^The standard message skeleton
30
31 .SH "PROFILE COMPONENTS"
32 .fc ^ ~
33 .nf
34 .ta 2.4i
35 .ta \w'ExtraBigProfileName  'u
36 ^Path:~^To determine the user's nmh directory
37
38 .SH "SEE ALSO"
39 dist(1), forw(1), repl(1), send(1), whatnow(1), mh-profile(5)
40
41 .SH DEFAULTS
42 .nf
43 .RB ` +folder "' defaults to the current folder"
44
45 .SH CONTEXT
46 None
47
48 .SH BUGS
49 None
50
51 ---------------------------------------
52 In the FILES section, use a spacer of "/usr/local/nmh/etc" for now,
53 we'll parametrize that into %etcdir% later.
54
55
56 Source files
57
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
61         this fragment:
62
63                 .PP
64                 .RS 5
65                 .nf
66                 %components%
67                 .fi
68                 .RE
69                 .PP
70
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
74         Makefile.in like:
75
76                 echo '/%components%/r $(top_srcdir)/etc/components' >> $@
77                 echo ' s,%components%,,g' >> $@
78
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.
84
85 Program names
86
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:
90
91                 .B comp
92                 .BR comp ,
93
94         If this is a manpage reference (outside of the SEE ALSO
95         section, which just uses regular text), use:
96
97                 .BR mh-draft (5)
98
99 SYNPOSIS section
100
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
104         by a "|":
105
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
112
113         References to these flags or parameters in the body text of the
114         manpage should reflect these conventions:
115
116                 You may not supply both a
117                 .B \-form
118                 .I formfile
119                 and a
120                 .I +folder
121                 or
122                 .I msg
123                 argument.
124
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.
128
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.
133
134 Subsections
135
136         Use ".SS" to denote a subsection
137
138 Tables
139
140         The folder manpage has an example of a table.
141
142         .PP
143         .RS 5
144         .nf
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.
150         .fi
151         .RE
152         .PP
153
154 Other italicized text
155
156         Italicize file names, profile entries, and folder names:
157
158                 If a file named
159                 .RI ` components '
160                 exists in the user's nmh directory,
161
162                 If the user's profile contains a
163                 .RI ` "Msg\-Protect: nnn" '
164                 entry, it
165
166                 The `+' after
167                 .I inbox
168                 indicates that it is the current folder.
169
170         Enclose the file names and profile entries in lq/rq
171         quotes, too.
172
173 Pointer manpages
174
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:
178
179                 .so man1/folder.1
180
181         Also, add this manpage to the appropriate section in Makefile.in