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% "%nmhdate%" MH.6.8 [%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 In the FILES section, prefer the default .TP indent. The pathnames are
  57 variable and long, so any indentation value that works for you won't
  58 work for someone else.
  59
  60
  61 Source files
  62
  63         There should be no ".so" commands to source an external file,
  64         since these break on Linux, where the man program does not
  65         allow source files outside the man/ hierarchy. Instead, insert
  66         this fragment:
  67
  68                 .PP
  69                 .RS 5
  70                 .nf
  71                 %components%
  72                 .fi
  73                 .RE
  74                 .PP
  75
  76         Of course, replace "components" with a unique identifier that
  77         reflects the content being included, like "mts_conf" for
  78         etc/mts.conf. Then, add two lines to the man.sed target in
  79         Makefile.in like:
  80
  81                 echo '/%components%/r $(top_srcdir)/etc/components' >> $@
  82                 echo ' s,%components%,,g' >> $@
  83
  84         At compile time, the contents of the file will physically
  85         incorporated into the body of the man page. This is somewhat
  86         unfortunate, since later modifications won't be reflected in
  87         the manpage, but on the other hand, the manpage will show the
  88         default configuration and not local modifications.
  89
  90 Program names
  91
  92         All nmh program names should be bolded. If there is punctuation
  93         after the name, use a .BR construct to avoid the automatic
  94         space that's inserted with just a .B:
  95
  96                 .B comp
  97                 .BR comp ,
  98
  99         If this is a manpage reference (outside of the SEE ALSO
 100         section, which just uses regular text), use:
 101
 102                 .IR mh-draft (5)
 103
 104 SYNPOSIS section
 105
 106         Literal text (such as flags) should be in bold. Parameters
 107         should be italicized. Mutually exclusive options (like
 108         "-foo" and "-nofoo") should be grouped together and seperated
 109         by a "|":
 110
 111                 .RI [ +folder ]              <---- parameter
 112                 .RI [ msgs ]                 <---- parameter
 113                 .RB [ \-version ]            <---- flag
 114                 .RB [ \-editor               <---- flag with
 115                 .IR editor ]                       parameter
 116                 .RB [ \-use " | " \-nouse ]  <---- exclusive parameters
 117
 118         References to these flags or parameters in the body text of the
 119         manpage should reflect these conventions:
 120
 121                 You may not supply both a
 122                 .B \-form
 123                 .I formfile
 124                 and a
 125                 .I +folder
 126                 or
 127                 .I msg
 128                 argument.
 129
 130         In particular, don't enclose them in single quotes (except
 131         in the DEFAULT section, which might be inconsistent, but
 132         seems a little clearer.
 133
 134         For "-flag param" situations, try to use a .B/.I combination
 135         instead of a single .BI, since it allows more flexibility in
 136         case of punctuation, and we get an automatic space between
 137         flag and param for free, without having to manual force it.
 138
 139 Subsections
 140
 141         Use ".SS" to denote a subsection
 142
 143 Tables
 144
 145         The folder manpage has an example of a table.
 146
 147         .PP
 148         .RS 5
 149         .nf
 150         .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
 151         FOLDER  \0\0\0\0\0\0# MESSAGES  RANGE   CUR     (OTHERS)
 152         ff      has \0no messages.
 153         inbox+  has \016 messages       (\03\-\022);    cur=\05.
 154         mh      has \076 messages       (15\-\076);     cur=70.
 155         .fi
 156         .RE
 157         .PP
 158
 159 Other italicized text
 160
 161         Italicize file names, profile entries, and folder names:
 162
 163                 If a file named
 164                 .RI \*(lq components \*(rq
 165                 exists in the user's nmh directory,
 166
 167                 If the user's profile contains a
 168                 .RI \*(lq "Msg\-Protect: nnn" \*(rq
 169                 entry, it
 170
 171                 The \*(lq+\*(rq after
 172                 .I inbox
 173                 indicates that it is the current folder.
 174
 175         Enclose the file names and profile entries in lq/rq
 176         quotes, too.
 177
 178 Pointer manpages
 179
 180         Certain manpages are shared between one or more programs
 181         (such as folder/folders). The secondary program should
 182         have a man page that only contains:
 183
 184                 .so man1/folder.1
 185
 186         Also, add this manpage to the appropriate section in Makefile.in