man.7

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