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 .\"
   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 "mts_conf" for
  73         etc/mts.conf. 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 \*(lq components \*(rq
 160                 exists in the user's nmh directory,
 161
 162                 If the user's profile contains a
 163                 .RI \*(lq "Msg\-Protect: nnn" \*(rq
 164                 entry, it
 165
 166                 The \*(lq+\*(rq 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