roff.7

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