roff.7

   1 .\"     $Id: roff.7,v 1.12 2010/07/04 22:04:04 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
   4 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd $Mdocdate: July 4 2010 $
  19 .Dt ROFF 7
  20 .Os
  21 .Sh NAME
  22 .Nm roff
  23 .Nd roff language reference
  24 .Sh DESCRIPTION
  25 The
  26 .Nm roff
  27 language is a general-purpose text-formatting language.  The purpose of
  28 this document is to consistently describe those language constructs
  29 accepted by the
  30 .Xr mandoc 1
  31 utility.  It is a work in progress.
  32 .Pp
  33 An
  34 .Nm
  35 document follows simple rules:  lines beginning with the control
  36 characters
  37 .Sq \.
  38 or
  39 .Sq \(aq
  40 are parsed for macros.  Other lines are interpreted within the scope of
  41 prior macros:
  42 .Bd -literal -offset indent
  43 \&.xx Macro lines change control state.
  44 Other lines are interpreted within the current state.
  45 .Ed
  46 .Sh LANGUAGE SYNTAX
  47 .Nm
  48 documents may contain only graphable 7-bit ASCII characters, the space
  49 character, and, in certain circumstances, the tab character.  All
  50 manuals must have
  51 .Ux
  52 line terminators.
  53 .Sh MACRO SYNTAX
  54 Macros are arbitrary in length and begin with a control character ,
  55 .Sq \.
  56 or
  57 .Sq \(aq ,
  58 at the beginning of the line.
  59 An arbitrary amount of whitespace may sit between the control character
  60 and the macro name.
  61 Thus, the following are equivalent:
  62 .Bd -literal -offset indent
  63 \&.if
  64 \&.\ \ \ \&if
  65 .Ed
  66 .Sh REFERENCE
  67 This section is a canonical reference of all macros, arranged
  68 alphabetically.
  69 .Ss \&am
  70 The syntax of this macro is the same as that of
  71 .Sx \&ig ,
  72 except that a leading argument must be specified.
  73 It is ignored, as are its children.
  74 .Ss \&ami
  75 The syntax of this macro is the same as that of
  76 .Sx \&ig ,
  77 except that a leading argument must be specified.
  78 It is ignored, as are its children.
  79 .Ss \&am1
  80 The syntax of this macro is the same as that of
  81 .Sx \&ig ,
  82 except that a leading argument must be specified.
  83 It is ignored, as are its children.
  84 .Ss \&de
  85 The syntax of this macro is the same as that of
  86 .Sx \&ig ,
  87 except that a leading argument must be specified.
  88 It is ignored, as are its children.
  89 .Ss \&dei
  90 The syntax of this macro is the same as that of
  91 .Sx \&ig ,
  92 except that a leading argument must be specified.
  93 It is ignored, as are its children.
  94 .Ss \&ds
  95 Define a string.
  96 This macro is intended to have two arguments,
  97 the name of the string to define and its content.
  98 Currently, it is ignored including its arguments,
  99 and the number of arguments is not checked.
 100 .Ss \&de1
 101 The syntax of this macro is the same as that of
 102 .Sx \&ig ,
 103 except that a leading argument must be specified.
 104 It is ignored, as are its children.
 105 .Ss \&el
 106 The
 107 .Qq else
 108 half of an if/else conditional.
 109 Pops a result off the stack of conditional evaluations pushed by
 110 .Sx \&ie
 111 and uses it as its conditional.
 112 If no stack entries are present (e.g., due to no prior
 113 .Sx \&ie
 114 calls)
 115 then false is assumed.
 116 The syntax of this macro is similar to
 117 .Sx \&if
 118 except that the conditional is missing.
 119 .Ss \&ie
 120 The
 121 .Qq if
 122 half of an if/else conditional.
 123 The result of the conditional is pushed into a stack used by subsequent
 124 invocations of
 125 .Sx \&el ,
 126 which may be separated by any intervening input (or not exist at all).
 127 Its syntax is equivalent to
 128 .Sx \&if .
 129 .Ss \&if
 130 Begins a conditional.
 131 Right now, the conditional evaluates to true
 132 if and only if it starts with the letter
 133 .Sy n ,
 134 indicating processing in
 135 .Xr nroff 1
 136 style as opposed to
 137 .Xr troff 1
 138 style.
 139 If a conditional is false, its children are not processed, but are
 140 syntactically interpreted to preserve the integrity of the input
 141 document.
 142 Thus,
 143 .Pp
 144 .D1 \&.if t \e .ig
 145 .Pp
 146 will discard the
 147 .Sq \&.ig ,
 148 which may lead to interesting results, but
 149 .Pp
 150 .D1 \&.if t \e .if t \e{\e
 151 .Pp
 152 will continue to syntactically interpret to the block close of the final
 153 conditional.
 154 Sub-conditionals, in this case, obviously inherit the truth value of
 155 the parent.
 156 This macro has the following syntax:
 157 .Pp
 158 .Bd -literal -offset indent -compact
 159 \&.if COND \e{\e
 160 BODY...
 161 \&.\e}
 162 .Ed
 163 .Bd -literal -offset indent -compact
 164 \&.if COND \e{ BODY
 165 BODY... \e}
 166 .Ed
 167 .Bd -literal -offset indent -compact
 168 \&.if COND \e{ BODY
 169 BODY...
 170 \&.\e}
 171 .Ed
 172 .Bd -literal -offset indent -compact
 173 \&.if COND \e
 174 BODY
 175 .Ed
 176 .Pp
 177 COND is a conditional statement.
 178 roff allows for complicated conditionals; mandoc is much simpler.
 179 At this time, mandoc supports only
 180 .Sq n ,
 181 evaluating to true;
 182 and
 183 .Sq t ,
 184 .Sq e ,
 185 and
 186 .Sq o ,
 187 evaluating to false.
 188 All other invocations are read up to the next end of line or space and
 189 evaluate as false.
 190 .Pp
 191 If the BODY section is begun by an escaped brace
 192 .Sq \e{ ,
 193 scope continues until a closing-brace macro
 194 .Sq \.\e} .
 195 If the BODY is not enclosed in braces, scope continues until the next
 196 macro or word.
 197 If the COND is followed by a BODY on the same line, whether after a
 198 brace or not, then macros
 199 .Em must
 200 begin with a control character.
 201 It is generally more intuitive, in this case, to write
 202 .Bd -literal -offset indent
 203 \&.if COND \e{\e
 204 \&.foo
 205 bar
 206 \&.\e}
 207 .Ed
 208 .Pp
 209 than having the macro follow as
 210 .Pp
 211 .D1 \&.if COND \e{ .foo
 212 .Pp
 213 The scope of a conditional is always parsed, but only executed if the
 214 conditional evaluates to true.
 215 .Pp
 216 Note that text subsequent a
 217 .Sq \&.\e}
 218 macro is discarded.
 219 Furthermore, if an explicit closing sequence
 220 .Sq \e}
 221 is specified in a free-form line, the entire line is accepted within the
 222 scope of the prior macro, not only the text preceding the close, with the
 223 .Sq \e}
 224 collapsing into a zero-width space.
 225 .Ss \&ig
 226 Ignore input.
 227 Accepts the following syntax:
 228 .Pp
 229 .Bd -literal -offset indent -compact
 230 \&.ig
 231 BODY...
 232 \&..
 233 .Ed
 234 .Bd -literal -offset indent -compact
 235 \&.ig END
 236 BODY...
 237 \&.END
 238 .Ed
 239 .Pp
 240 In the first case, input is ignored until a
 241 .Sq \&..
 242 macro is encountered on its own line.
 243 In the second case, input is ignored until a
 244 .Sq \&.END
 245 is encountered.
 246 Text subsequent the
 247 .Sq \&.END
 248 or
 249 .Sq \&..
 250 is discarded.
 251 .Pp
 252 Do not use the escape
 253 .Sq \e
 254 anywhere in the definition of END.
 255 It causes very strange behaviour.
 256 Furthermore, if you redefine a
 257 .Nm
 258 macro, such as
 259 .Pp
 260 .D1 \&.ig if
 261 .Pp
 262 the subsequent invocation of
 263 .Sx \&if
 264 will first signify the end of comment, then be invoked as a macro.
 265 This behaviour really shouldn't be counted upon.
 266 .Ss \&rm
 267 Remove a request, macro or string.
 268 This macro is intended to have one argument,
 269 the name of the request, macro or string to be undefined.
 270 Currently, it is ignored including its arguments,
 271 and the number of arguments is not checked.
 272 .Ss \&nr
 273 Define a register.
 274 A register is an arbitrary string value that defines some sort of state,
 275 which influences parsing and/or formatting.
 276 Its syntax is as follows:
 277 .Pp
 278 .D1 Pf \. Sx \&nr Cm name value
 279 .Pp
 280 The
 281 .Cm value
 282 may, at the moment, only be an integer.
 283 The
 284 .Cm name
 285 is defined up to the next whitespace.
 286 The following register
 287 .Cm name
 288 requests are recognised:
 289 .Bl -tag -width Ds
 290 .It Cm nS
 291 If set to a positive integer value, certain
 292 .Xr mdoc 7
 293 macros will behave as if they were defined in the
 294 .Em SYNOPSIS
 295 section.
 296 Otherwise, this behaviour is unset (even if called within the
 297 .Em SYNOPSIS
 298 section itself).
 299 Note that invoking a new
 300 .Xr mdoc 7
 301 section will unset this value.
 302 .El
 303 .Ss \&tr
 304 Output character translation.
 305 This macro is intended to have one argument,
 306 consisting of an even number of characters.
 307 Currently, it is ignored including its arguments,
 308 and the number of arguments is not checked.
 309 .Sh COMPATIBILITY
 310 This section documents compatibility between mandoc and other other
 311 troff implementations, at this time limited to GNU troff
 312 .Pq Qq groff .
 313 The term
 314 .Qq historic groff
 315 refers to groff versions before the
 316 .Pa doc.tmac
 317 file re-write
 318 .Pq somewhere between 1.15 and 1.19 .
 319 .Pp
 320 .Bl -dash -compact
 321 .It
 322 The
 323 .Cm nS
 324 request to
 325 .Sx \&nr
 326 is only compatible with OpenBSD's groff.
 327 .It
 328 Historic groff did not accept white-space buffering the custom END tag
 329 for the
 330 .Sx \&ig
 331 macro.
 332 .It
 333 The
 334 .Sx \&if
 335 and family would print funny white-spaces with historic groff when
 336 depending on next-line syntax.
 337 .El
 338 .Sh AUTHORS
 339 The
 340 .Nm
 341 reference was written by
 342 .An Kristaps Dzonsons Aq kristaps@bsd.lv .