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

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