diplodocus.org Git - nmh/blob - docs/README.manpages

   1 NMH MANPAGE STYLE GUIDE
   2
   3 nmh manpages should be in this general form and section order:
   4
   5 .TH COMP %manext1% "DATE" "%nmhversion%"
   6 .\"
   7 .\" %nmhwarning%
   8 .\"
   9 .SH NAME
  10 comp \- compose a message
  11 .\"
  12 .SH SYNOPSIS
  13 .HP 5
  14 .na
  15 .B comp
  16 .RI [ +folder ]
  17 .RI [ msgs ]
  18 .RB [ \-form
  19 .IR formfile ]
  20 .RB [ \-use " | " \-nouse ]
  21 .RB [ \-version ]
  22 .RB [ \-help ]
  23 .ad
  24 .SH DESCRIPTION
  25 .B Comp
  26 is used to create a new message to be mailed.  It copies something.
  27 .\"
  28 .SH "PROFILE COMPONENTS"
  29 .TP
  30 Path
  31 Location of the user's MH folder directory
  32 .TP
  33 moreproc
  34 The pager command name
  35 .\"
  36 .SH DEFAULTS
  37 .TP
  38 .RI + folder
  39 defaults to the current folder
  40 .\"
  41 .SH CONTEXT
  42 None
  43 .\"
  44 .SH FILES
  45 .TP
  46 filename1
  47 description of filename1
  48 .TP
  49 filename2
  50 description of filename2
  51 .\"
  52 .SH "SEE ALSO"
  53 .BR dist (1),
  54 .BR forw (1),
  55 .BR repl (1),
  56 .BR send (1),
  57 .BR whatnow (1),
  58 .BR mh-profile (5)
  59 .\" Leave out the BUGS section if there are none worth describing.
  60 .SH BUGS
  61 None
  62
  63 ---------------------------------------
  64 The DATE in the .TH macro should reflect the most recent non-trivial
  65 update to the content of the manpage; formatting changes don't count.
  66 Spell out the date (no abbreviations or shortcuts):
  67
  68   January 2, 1904
  69
  70 not the unparseable
  71
  72   01/02/04
  73
  74 Don't abbreviate the month.
  75
  76
  77 In the FILES section, prefer the default .TP indent. The pathnames are
  78 variable and long, so any indentation value that works for you won't
  79 work for someone using a different directory layout.
  80
  81
  82 Source files
  83
  84         There should be no ".so" commands to source an external file,
  85         since these break on Linux, where the man program does not
  86         allow source files outside the man/ hierarchy. Instead, insert
  87         this fragment:
  88
  89                 .PP
  90                 .RS 5
  91                 .nf
  92                 %components%
  93                 .fi
  94                 .RE
  95                 .PP
  96
  97         Of course, replace "components" with a unique identifier that
  98         reflects the content being included, like "mts_conf" for
  99         etc/mts.conf. Then, add two lines to the man.sed target in
 100         Makefile.in like:
 101
 102                 echo '/%components%/r $(top_srcdir)/etc/components' >> $@
 103                 echo ' s,%components%,,g' >> $@
 104
 105         At compile time, the contents of the file will physically
 106         incorporated into the body of the man page. This is somewhat
 107         unfortunate, since later modifications won't be reflected in
 108         the manpage, but on the other hand, the manpage will show the
 109         default configuration and not local modifications.
 110
 111 Program names
 112
 113         All nmh program names should be bolded. If there is punctuation
 114         after the name, use a .BR construct to avoid the automatic
 115         space that's inserted with just a .B:
 116
 117                 .B comp
 118                 .BR comp ,
 119
 120         The first reference to a documented command should be in the form of
 121         a manpage reference:
 122
 123                 .BR comp (1)
 124
 125 SYNPOSIS section
 126
 127         Literal text (such as flags) should be in bold. Parameters
 128         should be italicized. Mutually exclusive options (like
 129         "-foo" and "-nofoo") should be grouped together and seperated
 130         by a "|":
 131
 132                 .RI [ +folder ]              <---- parameter
 133                 .RI [ msgs ]                 <---- parameter
 134                 .RB [ \-version ]            <---- flag
 135                 .RB [ \-editor               <---- flag with
 136                 .IR editor ]                       parameter
 137                 .RB [ \-use " | " \-nouse ]  <---- exclusive parameters
 138
 139         References to these flags or parameters in the body text of the
 140         manpage should reflect these conventions:
 141
 142                 You may not supply both a
 143                 .B \-form
 144                 .I formfile
 145                 and a
 146                 .I +folder
 147                 or
 148                 .I msg
 149                 argument.
 150
 151         In particular, don't enclose them in single quotes (except
 152         in the DEFAULT section, which might be inconsistent, but
 153         seems a little clearer.
 154
 155         For "-flag param" situations, try to use a .B/.I combination
 156         instead of a single .BI, since it allows more flexibility in
 157         case of punctuation, and we get an automatic space between
 158         flag and param for free, without having to manual force it.
 159
 160 Subsections
 161
 162         Use ".SS" to denote a subsection
 163
 164 Tables
 165
 166         The folder manpage has an example of a table.
 167
 168         .PP
 169         .RS 5
 170         .nf
 171         .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
 172         FOLDER  \0\0\0\0\0\0# MESSAGES  RANGE   CUR     (OTHERS)
 173         ff      has \0no messages.
 174         inbox+  has \016 messages       (\03\-\022);    cur=\05.
 175         mh      has \076 messages       (15\-\076);     cur=70.
 176         .fi
 177         .RE
 178         .PP
 179
 180 Other italicized text
 181
 182         Italicize file names, profile entries, and folder names:
 183
 184                 If a file named
 185                 .RI \*(lq components \*(rq
 186                 exists in the user's nmh directory,
 187
 188                 If the user's profile contains a
 189                 .RI \*(lq "Msg\-Protect: nnn" \*(rq
 190                 entry, it
 191
 192                 The \*(lq+\*(rq after
 193                 .I inbox
 194                 indicates that it is the current folder.
 195
 196         Enclose the file names and profile entries in lq/rq
 197         quotes, too.
 198
 199 Pointer manpages
 200
 201         Certain manpages are shared between one or more programs
 202         (such as folder/folders). The secondary program should
 203         have a man page that only contains:
 204
 205                 .so man1/folder.1
 206
 207         Also, add this manpage to the appropriate section in Makefile.in
 208
 209
 210 CONTEXT
 211     Don't include a CONTEXT section when contexts are not
 212     applicable.
 213
 214
 215 AUTHOR and HISTORY sections
 216
 217     These have no place in a manpage.  If you want everlasting glory,
 218     try the release notes.
 219
 220 BUGS
 221
 222     The BUGS section goes last.