roff.7

   1 .\"     $Id: roff.7,v 1.4 2010/05/17 02:01:05 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: May 17 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 \&de1
  94 The syntax of this macro is the same as that of
  95 .Sx \&ig ,
  96 except that a leading argument must be specified.
  97 It is ignored, as are its children.
  98 .Ss \&if
  99 Begins a conditional that always evaluates to false.
 100 If a conditional is false, its children are not processed, but are
 101 syntactically interpreted to preserve the integrity of the input
 102 document.
 103 Thus,
 104 .Pp
 105 .D1 \&.if t \e .ig
 106 .Pp
 107 will discard the
 108 .Sq \&.ig ,
 109 which may lead to interesting results, but
 110 .Pp
 111 .D1 \&.if t \e .if t \e{\e
 112 .Pp
 113 will continue to syntactically interpret to the block close of the final
 114 conditional.
 115 Sub-conditionals, in this case, obviously inherit the truth value of
 116 the parent.
 117 This macro has the following syntax:
 118 .Pp
 119 .Bd -literal -offset indent -compact
 120 \&.if COND \e{\e
 121 BODY...
 122 \&.\e}
 123 .Ed
 124 .Bd -literal -offset indent -compact
 125 \&.if COND \e{ BODY
 126 BODY... \e}
 127 .Ed
 128 .Bd -literal -offset indent -compact
 129 \&.if COND \e{ BODY
 130 BODY...
 131 \&.\e}
 132 .Ed
 133 .Bd -literal -offset indent -compact
 134 \&.if COND \e
 135 BODY
 136 .Ed
 137 .Pp
 138 COND is a conditional (for the time being, this always evaluates to
 139 false).
 140 .Pp
 141 If the BODY section is begun by an escaped brace
 142 .Sq \e{ ,
 143 scope continues until a closing-brace macro
 144 .Sq \.\e} .
 145 If the BODY is not enclosed in braces, scope continues until the next
 146 macro or word.
 147 If the COND is followed by a BODY on the same line, whether after a
 148 brace or not, then macros
 149 .Em must
 150 begin with a control character.
 151 It is generally more intuitive, in this case, to write
 152 .Bd -literal -offset indent
 153 \&.if COND \e{\e
 154 \&.foo
 155 bar
 156 \&.\e}
 157 .Ed
 158 .Pp
 159 than having the macro follow as
 160 .Pp
 161 .D1 \&.if COND \e{ .foo
 162 .Pp
 163 The scope of a conditional is always parsed, but only executed if the
 164 conditional evaluates to true.
 165 .Pp
 166 Note that text subsequent a
 167 .Sq \&.\e}
 168 macro is discarded.
 169 Furthermore, if an explicit closing sequence
 170 .Sq \e}
 171 is specified in a free-form line, the entire line is accepted within the
 172 scope of the prior macro, not only the text preceding the close.
 173 .Ss \&ig
 174 Ignore input.
 175 Accepts the following syntax:
 176 .Pp
 177 .Bd -literal -offset indent -compact
 178 \&.ig
 179 BODY...
 180 \&..
 181 .Ed
 182 .Bd -literal -offset indent -compact
 183 \&.ig END
 184 BODY...
 185 \&.END
 186 .Ed
 187 .Pp
 188 In the first case, input is ignored until a
 189 .Sq \&..
 190 macro is encountered on its own line.
 191 In the second case, input is ignored until a
 192 .Sq \&.END
 193 is encountered.
 194 Text subsequent the
 195 .Sq \&.END
 196 or
 197 .Sq \&..
 198 is discarded.
 199 .Pp
 200 Do not use the escape
 201 .Sq \e
 202 anywhere in the definition of END.
 203 It causes very strange behaviour.
 204 Furthermore, if you redefine a
 205 .Nm
 206 macro, such as
 207 .Pp
 208 .D1 \&.ig if
 209 .Pp
 210 the subsequent invocation of
 211 .Sx \&if
 212 will first signify the end of comment, then be invoked as a macro.
 213 This behaviour really shouldn't be counted upon.
 214 .Sh COMPATIBILITY
 215 This section documents compatibility between mandoc and other other
 216 troff implementations, at this time limited to GNU troff
 217 .Pq Qq groff .
 218 The term
 219 .Qq historic groff
 220 refers to groff versions before the
 221 .Pa doc.tmac
 222 file re-write
 223 .Pq somewhere between 1.15 and 1.19 .
 224 .Pp
 225 .Bl -dash -compact
 226 .It
 227 Historic groff did not accept white-space buffering the custom END tag
 228 for the
 229 .Sx \&ig
 230 macro.
 231 .It
 232 The
 233 .Sx \&if
 234 and family would print funny white-spaces with historic groff when
 235 depending on next-line syntax.
 236 .El
 237 .Sh AUTHORS
 238 The
 239 .Nm
 240 reference was written by
 241 .An Kristaps Dzonsons Aq kristaps@bsd.lv .