man.7

   1 .\" $Id: man.7,v 1.4 2009/03/26 16:23:22 kristaps Exp $
   2 .\"
   3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the
   7 .\" above copyright notice and this permission notice appear in all
   8 .\" copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
  11 .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
  12 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
  13 .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
  14 .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  15 .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  16 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  17 .\" PERFORMANCE OF THIS SOFTWARE.
  18 .\"
  19 .Dd $Mdocdate: March 26 2009 $
  20 .Dt man 7
  21 .Os
  22 .\" SECTION
  23 .Sh NAME
  24 .Nm man
  25 .Nd man language reference
  26 .\" SECTION
  27 .Sh DESCRIPTION
  28 The
  29 .Nm man
  30 language was historically used to format
  31 .Ux
  32 manuals.  In this reference document, we describe the syntax and
  33 structure of the
  34 .Nm
  35 language.
  36 .Pp
  37 .Em \&Do not ever
  38 use
  39 .Nm
  40 to write your manuals.  Use the
  41 .Xr mdoc 7
  42 language, instead.
  43 .\" PARAGRAPH
  44 .Pp
  45 An
  46 .Nm
  47 document follows simple rules:  lines beginning with the control
  48 character
  49 .Sq \&.
  50 are parsed for macros.  Other lines are interpreted within the scope of
  51 prior macros:
  52 .Bd -literal -offset indent
  53 \&.SH Macro lines change control state.
  54 Other lines are interpreted within the current state.
  55 .Ed
  56 .\" PARAGRAPH
  57 .Pp
  58 Macros are character sequences whose structural rules are described
  59 later in this document.
  60 .\" SECTION
  61 .Sh INPUT ENCODING
  62 .Nm
  63 documents may contain only graphable 7-bit ASCII characters and the
  64 space character
  65 .Sq \  .
  66 All manuals must have
  67 .Sq \en
  68 line termination.
  69 .Pp
  70 Blank lines are acceptable; where found, the output will also assert a
  71 vertical space.
  72 .Pp
  73 The
  74 .Sq \ec
  75 escape is common in historical
  76 .Nm
  77 documents; if encountered at the end of a word, it ensures that the
  78 subsequent word isn't off-set by whitespace.
  79 .\" SUB-SECTION
  80 .Ss Special Characters
  81 Special character sequences begin with the escape character
  82 .Sq \e
  83 followed by either an open-parenthesis
  84 .Sq \&(
  85 for two-character sequences; an open-bracket
  86 .Sq \&[
  87 for n-character sequences (terminated at a close-bracket
  88 .Sq \&] ) ;
  89 or a single one-character sequence.
  90 .Pp
  91 Characters may alternatively be escaped by a slash-asterisk,
  92 .Sq \e* ,
  93 with the same combinations as described above.  This form is deprecated.
  94 .Pp
  95 The
  96 .Xr mdoc 7
  97 contains a table of all available escapes.
  98 .\" SECTION
  99 .Sh STRUCTURE
 100 Macros are one to three three characters in length and begin with a
 101 control character ,
 102 .Sq \&. ,
 103 at the beginning of the line.  An arbitrary amount of whitespace may
 104 sit between the control character and the macro name.  Thus,
 105 .Sq \&.PP
 106 and
 107 .Sq \&.\ \ \ \&PP
 108 are equivalent.
 109 .Pp
 110 All
 111 .Nm
 112 macros follow the same structural rules:
 113 .Bd -literal -offset indent
 114 \&.YO \(lBbody...\(rB
 115 .Ed
 116 .Pp
 117 The
 118 .Dq body
 119 consists of zero or more arguments to the macro.
 120 .Pp
 121 .Nm
 122 has a primitive notion of multi-line scope for the following macros:
 123 .Sq \&.TM ,
 124 .Sq \&.SM ,
 125 .Sq \&.SB ,
 126 .Sq \&.BI ,
 127 .Sq \&.IB ,
 128 .Sq \&.BR ,
 129 .Sq \&.RB ,
 130 .Sq \&.R ,
 131 .Sq \&.B ,
 132 .Sq \&.I ,
 133 .Sq \&.IR
 134 and
 135 .Sq \&.RI .
 136 When these macros are invoked without arguments, the subsequent line is
 137 considered a continuation of the macro.  Thus:
 138 .Bd -literal -offset indent
 139 \&.RI foo
 140 .Ed
 141 .Pp
 142 and
 143 .Bd -literal -offset indent
 144 \&.RI
 145 foo
 146 .Ed
 147 .Pp
 148 are equivalent.  If two consecutive lines exhibit the latter behaviour,
 149 an error is raised.  Thus, the following is acceptable:
 150 .Bd -literal -offset indent
 151 \&.RI
 152 \&.I Hello, world.
 153 foo
 154 .Ed
 155 .Pp
 156 The following, however, is not:
 157 .Bd -literal -offset indent
 158 \&.RI
 159 \&.I
 160 Hello, world.
 161 .Ed
 162 .Pp
 163 The
 164 .Sq \&.TP
 165 macro has similar behaviour, but does not need an empty argument line in
 166 order to trigger scope.
 167 .\" PARAGRAPH
 168 .Sh MACROS
 169 This section contains a complete list of all
 170 .Nm
 171 macros, arranged alphabetically, with the number of arguments.
 172 .Pp
 173 .Bl -column "MacroX" "Arguments" -compact -offset indent
 174 .It Em Macro Ta Em Arguments
 175 .It \&.TH    Ta    >1, <6
 176 .It \&.SH    Ta    >0
 177 .It \&.SS    Ta    >0
 178 .It \&.TP    Ta    n
 179 .It \&.LP    Ta    0
 180 .It \&.PP    Ta    0
 181 .It \&.P     Ta    0
 182 .It \&.IP    Ta    <3
 183 .It \&.HP    Ta    <2
 184 .It \&.SM    Ta    n
 185 .It \&.SB    Ta    n
 186 .It \&.BI    Ta    n
 187 .It \&.IB    Ta    n
 188 .It \&.BR    Ta    n
 189 .It \&.RB    Ta    n
 190 .It \&.R     Ta    n
 191 .It \&.B     Ta    n
 192 .It \&.I     Ta    n
 193 .It \&.IR    Ta    n
 194 .It \&.RI    Ta    n
 195 .El
 196 .\" SECTION
 197 .Sh SEE ALSO
 198 .Xr mandoc 1
 199 .\" SECTION
 200 .Sh AUTHORS
 201 The
 202 .Nm
 203 utility was written by
 204 .An Kristaps Dzonsons Aq kristaps@openbsd.org .
 205 .\" SECTION
 206 .Sh CAVEATS
 207 Do not use this language.  Use
 208 .Xr mdoc 7 ,
 209 instead.