roff.7

   1 .\"     $Id: roff.7,v 1.2 2010/05/16 22:28:33 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 16 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 \&if
  69 Begins a conditional.
  70 Has the following syntax:
  71 .Pp
  72 .Bd -literal -offset indent -compact
  73 \&.if COND \e{\e
  74 BODY...
  75 \&.\e}
  76 .Ed
  77 .Bd -literal -offset indent -compact
  78 \&.if COND \e{ BODY
  79 BODY... \e}
  80 .Ed
  81 .Bd -literal -offset indent -compact
  82 \&.if COND \e{ BODY
  83 BODY...
  84 \&.\e}
  85 .Ed
  86 .Bd -literal -offset indent -compact
  87 \&.if COND \e
  88 BODY
  89 .Ed
  90 .Pp
  91 COND is a conditional (TODO: document).
  92 .Pp
  93 If the BODY section is begun by an escaped brace
  94 .Sq \e{ ,
  95 scope continues until a closing-brace macro
  96 .Sq \.\e} .
  97 If the BODY is not enclosed in braces, scope continues until the next
  98 macro or word.
  99 If the COND is followed by a BODY on the same line, whether after a
 100 brace or not, then macros
 101 .Em must
 102 begin with a control character.
 103 It is generally more intuitive, in this case, to write
 104 .Bd -literal -offset indent
 105 \&.if COND \e{\e
 106 \&.foo
 107 bar
 108 \&.\e}
 109 .Ed
 110 .Pp
 111 than having the macro follow as
 112 .Pp
 113 .D1 \&.if COND \e{ .foo
 114 .Pp
 115 The scope of a conditional is always parsed, but only executed if the
 116 conditional evaluates to true.
 117 .Pp
 118 Note that text subsequent a
 119 .Sq \&.\e}
 120 macro is discarded.
 121 Furthermore, if an explicit closing sequence
 122 .Sq \e}
 123 is specified in a free-form line, the entire line is accepted within the
 124 scope of the prior macro, not only the text preceding the close.
 125 .Ss \&ig
 126 Ignore input.
 127 Accepts the following syntax:
 128 .Pp
 129 .Bd -literal -offset indent -compact
 130 \&.ig
 131 BODY...
 132 \&..
 133 .Ed
 134 .Bd -literal -offset indent -compact
 135 \&.ig END
 136 BODY...
 137 \&.END
 138 .Ed
 139 .Pp
 140 In the first case, input is ignored until a
 141 .Sq \&..
 142 macro is encountered on its own line.
 143 In the second case, input is ignored until a
 144 .Sq \&.END
 145 is encountered.
 146 Text subsequent the
 147 .Sq \&.END
 148 or
 149 .Sq \&..
 150 is discarded.
 151 .Pp
 152 Do not use the escape
 153 .Sq \e
 154 anywhere in the definition of END.
 155 It causes very strange behaviour.
 156 Furthermore, if you redefine a
 157 .Nm
 158 macro, such as
 159 .Pp
 160 .D1 \&.ig if
 161 .Pp
 162 the subsequent invocation of
 163 .Sx \&if
 164 will first signify the end of comment, then be invoked as a macro.
 165 This behaviour really shouldn't be counted upon.
 166 .Sh COMPATIBILITY
 167 This section documents compatibility between mandoc and other other
 168 troff implementations, at this time limited to GNU troff
 169 .Pq Qq groff .
 170 The term
 171 .Qq historic groff
 172 refers to groff versions before the
 173 .Pa doc.tmac
 174 file re-write
 175 .Pq somewhere between 1.15 and 1.19 .
 176 .Pp
 177 .Bl -dash -compact
 178 .It
 179 Historic groff did not accept white-space buffering the custom END tag
 180 for the
 181 .Sx \&ig
 182 macro.
 183 .El
 184 .Sh AUTHORS
 185 The
 186 .Nm
 187 reference was written by
 188 .An Kristaps Dzonsons Aq kristaps@bsd.lv .