mdocterm.1

   1 .\" $Id: mdocterm.1,v 1.19 2009/03/13 07:46:10 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
   7 .\" above copyright notice and this permission notice appear in all
   8 .\" copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
  11 .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
  12 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
  13 .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
  14 .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  15 .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  16 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  17 .\" PERFORMANCE OF THIS SOFTWARE.
  18 .\"
  19 .Dd $Mdocdate: March 13 2009 $
  20 .Dt mdocterm 1
  21 .Os
  22 .\" SECTION
  23 .Sh NAME
  24 .Nm mdocmterm
  25 .Nd mdoc macro compiler
  26 .\" SECTION
  27 .Sh SYNOPSIS
  28 .Nm mdocmterm
  29 .Op Fl vV
  30 .Op Fl f Ns Ar option...
  31 .Op Fl W Ns Ar err...
  32 .Op Ar infile
  33 .\" SECTION
  34 .Sh DESCRIPTION
  35 The
  36 .Nm
  37 utility formats a BSD
  38 .Dq mdoc
  39 manual page for display on the terminal.  The arguments are as follows:
  40 .Bl -tag -width XXXXXXXXXXXX
  41 .\" ITEM
  42 .It Fl v
  43 Print verbose parsing output.
  44 .\" ITEM
  45 .It Fl v
  46 Print version and exit.
  47 .\" ITEM
  48 .It Fl f Ns Ar option...
  49 Override default compiler behaviour.  See
  50 .Sx Compiler Options
  51 for details.
  52 .\" ITEM
  53 .It Fl W Ns Ar err...
  54 Print warning messages.  May be set to
  55 .Fl W Ns Ar all
  56 for all warnings,
  57 .Ar compat
  58 for groff/troff-compatibility warnings, or
  59 .Ar syntax
  60 for syntax warnings.  If
  61 .Fl W Ns Ar error
  62 is specified, warnings are considered errors and cause utility
  63 termination.  Multiple
  64 .Fl W
  65 arguments may be comma-separated, such as
  66 .Fl W Ns Ar error,all .
  67 .\" ITEM
  68 .It Ar infile
  69 Read input from
  70 .Ar infile ,
  71 which may be
  72 .Dq \-
  73 for stdin.
  74 .El
  75 .\" PARAGRAPH
  76 .Pp
  77 The
  78 .Nm
  79 utility is a formatting front-end for
  80 .Xr mdoc 3 ,
  81 which parses the
  82 .Dq mdoc
  83 input, documented at
  84 .Xr mdoc 7
  85 and
  86 .Xr mdoc.samples 7 ,
  87 into an abstract syntax tree.
  88 .Pp
  89 By default,
  90 .Nm
  91 reads from stdin and prints ANSI
  92 .Qq raw
  93 terminal-encoded output to stdout, at this time to a fixed column with
  94 of 78 characters.
  95 .\" PARAGRAPH
  96 .Pp
  97 .Ex -std mdocmterm
  98 .\" SUB-SECTION
  99 .Ss Compiler Options
 100 Default compiler behaviour may be overriden with the
 101 .Fl f
 102 flag.  The available options are as follows:
 103 .Bl -tag -width XXXXXXXXXXXX -offset XXXX
 104 .It Fl f Ns Ar ign-scope
 105 When rewinding the scope of a block macro, forces the compiler to ignore
 106 scope violations.  This can seriously mangle the resulting tree.
 107 .It Fl f Ns Ar ign-escape
 108 Ignore invalid escape sequences.
 109 .It Fl f Ns Ar ign-macro
 110 Ignore unknown macros at the start of input lines.
 111 .El
 112 .\" PARAGRAPH
 113 .Pp
 114 As with the
 115 .Fl W
 116 flag, multiple
 117 .Fl f
 118 options may be grouped and delimited with a comma.  Using
 119 .Fl f Ns Ar ign-scope,ign-escape ,
 120 for example, will try to ignore scope and character-escape errors.
 121 .\" SUB-SECTION
 122 .Ss Input Encoding
 123 The
 124 .Nm
 125 utility expects its input to be 7-bit ASCII as defined in
 126 .Xr ascii 7 .
 127 The only non-graphing characters accepted are spaces,
 128 .Sq \  ,
 129 and tabs,
 130 .Sq \et .
 131 Tabs are only accepted in literal block-displays and as column
 132 delimiters.
 133 .Pp
 134 Only Unix-style newlines (\en) are accepted; if the newline is escaped,
 135 the line is concatenated with the next.
 136 .\" SUB-SECTION
 137 .Ss Character Escapes
 138 This section documents the character-escapes accepted by
 139 .Xr mdocterm 1 .
 140 Note that the \\x, \\(xx and \\[n] forms are described here; the \\*(xx,
 141 \\*[n] and \\*x forms described in
 142 .Xr mdoc.samples 7
 143 are deprecated, but still rendered.  All one- and two-character
 144 sequences may be used in the n-character sequence \\[n].
 145 .Pp
 146 Note that the
 147 .Em Output
 148 column will render differently whether executed with
 149 .Xr mdocterm 1
 150 or another output filter.
 151 .\" PARAGRAPH
 152 .Pp
 153 Grammatic:
 154 .Pp
 155 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 156 .It Em Output
 157 .Em Input (Name)
 158 .It \(em
 159 \\(em (em-dash)
 160 .It \(en
 161 \\(en (en-dash)
 162 .It \-
 163 \\- (hyphen)
 164 .It \\
 165 \\\\ (back-slash)
 166 .El
 167 .\" PARAGRAPH
 168 .Pp
 169 Enclosures:
 170 .Pp
 171 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 172 .It Em Output
 173 .Em Input (Name)
 174 .It \(rC
 175 \\(rC (right brace)
 176 .It \(lC
 177 \\(lC (left brace)
 178 .It \(ra
 179 \\(ra (right angle)
 180 .It \(la
 181 \\(la (left angle)
 182 .It \(rB
 183 \\(rB (right bracket)
 184 .It \(lB
 185 \\(lB (left bracket)
 186 .It \q
 187 \\q (double-quote)
 188 .It \(lq
 189 \\(lq (left double-quote)
 190 .It \(rq
 191 \\(rq (right double-quote)
 192 .It \(oq
 193 \\(oq, \\` (left single-quote)
 194 .It \(aq
 195 \\(aq, \\' (right single-quote, apostrophe)
 196 .El
 197 .\" PARAGRAPH
 198 .Pp
 199 Indicatives:
 200 .Pp
 201 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 202 .It Em Output
 203 .Em Input (Name)
 204 .It \(<-
 205 \\(<- (left arrow)
 206 .It \(->
 207 \\(-> (right arrow)
 208 .It \(ua
 209 \\(ua (up arrow)
 210 .It \(da
 211 \\(da (down arrow)
 212 .El
 213 .\" PARAGRAPH
 214 .Pp
 215 Mathematical:
 216 .Pp
 217 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 218 .It Em Output
 219 .Em Input (Name)
 220 .It \(<=
 221 \\(<= (less-than-equal)
 222 .It \(>=
 223 \\(>= (greater-than-equal)
 224 .It \(==
 225 \\(== (equal)
 226 .It \(!=
 227 \\(!= (not equal)
 228 .It \(if
 229 \\(if (infinity)
 230 .It \(na
 231 \\(na (NaN)*
 232 .It \(+-
 233 \\(+- (plus-minus)
 234 .It \(**
 235 \\(** (asterisk)
 236 .El
 237 .\" PARAGRAPH
 238 .Pp
 239 Diacritics:
 240 .Pp
 241 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 242 .It Em Output
 243 .Em Input (Name)
 244 .It \(ga
 245 \\(ga (accent grave)
 246 .It \(aa
 247 \\(aa (accent accute)
 248 .El
 249 .\" PARAGRAPH
 250 .Pp
 251 Special symbols:
 252 .Pp
 253 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 254 .It Em Output
 255 .Em Input (Name)
 256 .It \(bu
 257 \\(bu (bullet)
 258 .It \(ba
 259 \\(ba (bar)
 260 .It \(co
 261 \\(co (copyright)
 262 .El
 263 .Pp
 264 *This is a deviation from the standard, as NaN is usually rendered as
 265 \\*(Na, which is a deprecated form.  We introduce \\(na, which follows
 266 the more general syntax.
 267 .\" SECTION
 268 .Sh EXAMPLES
 269 To display this manual page:
 270 .\" PARAGRAPH
 271 .Pp
 272 .D1 % mdocmterm \-Wall,error mdocmterm.1
 273 .\" PARAGRAPH
 274 .Pp
 275 To pipe a manual page to the pager:
 276 .Pp
 277 .D1 % mdocterm mdocterm.1 2>&1 | less \-R
 278 .\" SECTION
 279 .Sh SEE ALSO
 280 .Xr mdoctree 1 ,
 281 .Xr mdoclint 1 ,
 282 .Xr mdoc.samples 7 ,
 283 .Xr mdoc 7 ,
 284 .Xr mdoc 3
 285 .\"
 286 .Sh AUTHORS
 287 The
 288 .Nm
 289 utility was written by
 290 .An Kristaps Dzonsons Aq kristaps@kth.se .
 291 .\" SECTION
 292 .Sh CAVEATS
 293 See
 294 .Xr mdoc 3
 295 for a list of bugs, caveats, and incomplete macros regarding the
 296 document parse.
 297 .Pp
 298 The
 299 .Nm
 300 utility doesn't yet know how to display the following:
 301 .Pp
 302 .Bl -bullet -compact
 303 .It
 304 The \-hang
 305 .Sq \&Bl
 306 list is not yet supported.
 307 .It
 308 The \-literal and \-unfilled
 309 .Sq \&Bd
 310 displays only accept text contents.
 311 .It
 312 The
 313 .Sq \&Xo/Xc
 314 pair isn't supported (and never will be).
 315 .It
 316 The
 317 .Sq \&Sm
 318 macro has no effect, yet.
 319 .El