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 .IR dist (1),
  54 .IR forw (1),
  55 .IR repl (1),
  56 .IR send (1),
  57 .IR whatnow (1),
  58 .IR 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         If this is a manpage reference, use:
 121
 122                 .IR mh-draft (5)
 123
 124 SYNPOSIS section
 125
 126         Literal text (such as flags) should be in bold. Parameters
 127         should be italicized. Mutually exclusive options (like
 128         "-foo" and "-nofoo") should be grouped together and seperated
 129         by a "|":
 130
 131                 .RI [ +folder ]              <---- parameter
 132                 .RI [ msgs ]                 <---- parameter
 133                 .RB [ \-version ]            <---- flag
 134                 .RB [ \-editor               <---- flag with
 135                 .IR editor ]                       parameter
 136                 .RB [ \-use " | " \-nouse ]  <---- exclusive parameters
 137
 138         References to these flags or parameters in the body text of the
 139         manpage should reflect these conventions:
 140
 141                 You may not supply both a
 142                 .B \-form
 143                 .I formfile
 144                 and a
 145                 .I +folder
 146                 or
 147                 .I msg
 148                 argument.
 149
 150         In particular, don't enclose them in single quotes (except
 151         in the DEFAULT section, which might be inconsistent, but
 152         seems a little clearer.
 153
 154         For "-flag param" situations, try to use a .B/.I combination
 155         instead of a single .BI, since it allows more flexibility in
 156         case of punctuation, and we get an automatic space between
 157         flag and param for free, without having to manual force it.
 158
 159 Subsections
 160
 161         Use ".SS" to denote a subsection
 162
 163 Tables
 164
 165         The folder manpage has an example of a table.
 166
 167         .PP
 168         .RS 5
 169         .nf
 170         .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
 171         FOLDER  \0\0\0\0\0\0# MESSAGES  RANGE   CUR     (OTHERS)
 172         ff      has \0no messages.
 173         inbox+  has \016 messages       (\03\-\022);    cur=\05.
 174         mh      has \076 messages       (15\-\076);     cur=70.
 175         .fi
 176         .RE
 177         .PP
 178
 179 Other italicized text
 180
 181         Italicize file names, profile entries, and folder names:
 182
 183                 If a file named
 184                 .RI \*(lq components \*(rq
 185                 exists in the user's nmh directory,
 186
 187                 If the user's profile contains a
 188                 .RI \*(lq "Msg\-Protect: nnn" \*(rq
 189                 entry, it
 190
 191                 The \*(lq+\*(rq after
 192                 .I inbox
 193                 indicates that it is the current folder.
 194
 195         Enclose the file names and profile entries in lq/rq
 196         quotes, too.
 197
 198 Pointer manpages
 199
 200         Certain manpages are shared between one or more programs
 201         (such as folder/folders). The secondary program should
 202         have a man page that only contains:
 203
 204                 .so man1/folder.1
 205
 206         Also, add this manpage to the appropriate section in Makefile.in
 207
 208
 209 CONTEXT
 210     Don't include a CONTEXT section when contexts are not
 211     applicable.
 212
 213
 214 AUTHOR and HISTORY sections
 215
 216     These have no place in a manpage.  If you want everlasting glory,
 217     try the release notes.
 218
 219 BUGS
 220
 221     The BUGS section goes last.