mdocterm.1

   1 .\" $Id: mdocterm.1,v 1.20 2009/03/14 12:35:02 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 14 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 O Ns Ar option...
  32 .Op Fl W Ns Ar err...
  33 .Op Ar infile
  34 .\" SECTION
  35 .Sh DESCRIPTION
  36 The
  37 .Nm
  38 utility formats a BSD
  39 .Dq mdoc
  40 manual page for display on the terminal.  The arguments are as follows:
  41 .Bl -tag -width XXXXXXXXXXXX
  42 .\" ITEM
  43 .It Fl v
  44 Print verbose parsing output.
  45 .\" ITEM
  46 .It Fl v
  47 Print version and exit.
  48 .\" ITEM
  49 .It Fl f Ns Ar option...
  50 Override default compiler behaviour.  See
  51 .Sx Compiler Options
  52 for details.
  53 .\" ITEM
  54 .It Fl O Ns Ar option...
  55 Terminal-encoding options.  May be set to
  56 .Fl O Ns Ar ansi
  57 for ANSI/VT100-encoded output (the default) or
  58 .Fl O Ns Ar nroff
  59 for nroff-encoded
  60 .Qq backspace
  61 output.
  62 .\" ITEM
  63 .It Fl W Ns Ar err...
  64 Print warning messages.  May be set to
  65 .Fl W Ns Ar all
  66 for all warnings,
  67 .Ar compat
  68 for groff/troff-compatibility warnings, or
  69 .Ar syntax
  70 for syntax warnings.  If
  71 .Fl W Ns Ar error
  72 is specified, warnings are considered errors and cause utility
  73 termination.  Multiple
  74 .Fl W
  75 arguments may be comma-separated, such as
  76 .Fl W Ns Ar error,all .
  77 .\" ITEM
  78 .It Ar infile
  79 Read input from
  80 .Ar infile ,
  81 which may be
  82 .Dq \-
  83 for stdin.
  84 .El
  85 .\" PARAGRAPH
  86 .Pp
  87 The
  88 .Nm
  89 utility is a formatting front-end for
  90 .Xr mdoc 3 ,
  91 which parses the
  92 .Dq mdoc
  93 input, documented at
  94 .Xr mdoc 7
  95 and
  96 .Xr mdoc.samples 7 ,
  97 into an abstract syntax tree.
  98 .Pp
  99 By default,
 100 .Nm
 101 reads from stdin and prints ANSI
 102 .Qq raw
 103 terminal-encoded output to stdout, at this time to a fixed column with
 104 of 78 characters.
 105 .\" PARAGRAPH
 106 .Pp
 107 .Ex -std mdocmterm
 108 .\" SUB-SECTION
 109 .Ss Compiler Options
 110 Default compiler behaviour may be overriden with the
 111 .Fl f
 112 flag.  The available options are as follows:
 113 .Bl -tag -width XXXXXXXXXXXX -offset XXXX
 114 .It Fl f Ns Ar ign-scope
 115 When rewinding the scope of a block macro, forces the compiler to ignore
 116 scope violations.  This can seriously mangle the resulting tree.
 117 .It Fl f Ns Ar ign-escape
 118 Ignore invalid escape sequences.
 119 .It Fl f Ns Ar ign-macro
 120 Ignore unknown macros at the start of input lines.
 121 .El
 122 .\" PARAGRAPH
 123 .Pp
 124 As with the
 125 .Fl W
 126 flag, multiple
 127 .Fl f
 128 options may be grouped and delimited with a comma.  Using
 129 .Fl f Ns Ar ign-scope,ign-escape ,
 130 for example, will try to ignore scope and character-escape errors.
 131 .\" SUB-SECTION
 132 .Ss Character Escapes
 133 The following table shows all
 134 .Xr mdoc 7
 135 character escapes rendered by
 136 .Nm .
 137 Note that the
 138 .Em Output
 139 column will render differently whether executed with
 140 .Xr mdocterm 1
 141 or another output filter.
 142 .\" PARAGRAPH
 143 .Pp
 144 Grammatic:
 145 .Pp
 146 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 147 .It Em Output
 148 .Em Input (Name)
 149 .It \(em
 150 \\(em (em-dash)
 151 .It \(en
 152 \\(en (en-dash)
 153 .It \-
 154 \\- (hyphen)
 155 .It \\
 156 \\\\ (back-slash)
 157 .El
 158 .\" PARAGRAPH
 159 .Pp
 160 Enclosures:
 161 .Pp
 162 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 163 .It Em Output
 164 .Em Input (Name)
 165 .It \(rC
 166 \\(rC (right brace)
 167 .It \(lC
 168 \\(lC (left brace)
 169 .It \(ra
 170 \\(ra (right angle)
 171 .It \(la
 172 \\(la (left angle)
 173 .It \(rB
 174 \\(rB (right bracket)
 175 .It \(lB
 176 \\(lB (left bracket)
 177 .It \q
 178 \\q (double-quote)
 179 .It \(lq
 180 \\(lq (left double-quote)
 181 .It \(rq
 182 \\(rq (right double-quote)
 183 .It \(oq
 184 \\(oq, \\` (left single-quote)
 185 .It \(aq
 186 \\(aq, \\' (right single-quote, apostrophe)
 187 .El
 188 .\" PARAGRAPH
 189 .Pp
 190 Indicatives:
 191 .Pp
 192 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 193 .It Em Output
 194 .Em Input (Name)
 195 .It \(<-
 196 \\(<- (left arrow)
 197 .It \(->
 198 \\(-> (right arrow)
 199 .It \(ua
 200 \\(ua (up arrow)
 201 .It \(da
 202 \\(da (down arrow)
 203 .El
 204 .\" PARAGRAPH
 205 .Pp
 206 Mathematical:
 207 .Pp
 208 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 209 .It Em Output
 210 .Em Input (Name)
 211 .It \(<=
 212 \\(<= (less-than-equal)
 213 .It \(>=
 214 \\(>= (greater-than-equal)
 215 .It \(==
 216 \\(== (equal)
 217 .It \(!=
 218 \\(!= (not equal)
 219 .It \(if
 220 \\(if (infinity)
 221 .It \(na
 222 \\(na (NaN)*
 223 .It \(+-
 224 \\(+- (plus-minus)
 225 .It \(**
 226 \\(** (asterisk)
 227 .El
 228 .\" PARAGRAPH
 229 .Pp
 230 Diacritics:
 231 .Pp
 232 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 233 .It Em Output
 234 .Em Input (Name)
 235 .It \(ga
 236 \\(ga (accent grave)
 237 .It \(aa
 238 \\(aa (accent accute)
 239 .El
 240 .\" PARAGRAPH
 241 .Pp
 242 Special symbols:
 243 .Pp
 244 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 245 .It Em Output
 246 .Em Input (Name)
 247 .It \(bu
 248 \\(bu (bullet)
 249 .It \(ba
 250 \\(ba (bar)
 251 .It \(co
 252 \\(co (copyright)
 253 .El
 254 .Pp
 255 *This is a deviation from the standard, as NaN is usually rendered as
 256 \\*(Na, which is a deprecated form.  We introduce \\(na, which follows
 257 the more general syntax.
 258 .\" SECTION
 259 .Sh EXAMPLES
 260 To display this manual page on ANSI-capable terminal:
 261 .\" PARAGRAPH
 262 .Pp
 263 .D1 % mdocmterm \-Wall,error mdocmterm.1
 264 .\" PARAGRAPH
 265 .Pp
 266 To pipe a manual page to the pager:
 267 .Pp
 268 .D1 % mdocterm -Onroff mdocterm.1 | less
 269 .\" SECTION
 270 .Sh SEE ALSO
 271 .Xr mdoctree 1 ,
 272 .Xr mdoclint 1 ,
 273 .Xr mdoc.samples 7 ,
 274 .Xr mdoc 7 ,
 275 .Xr mdoc 3
 276 .\"
 277 .Sh AUTHORS
 278 The
 279 .Nm
 280 utility was written by
 281 .An Kristaps Dzonsons Aq kristaps@kth.se .
 282 .\" SECTION
 283 .Sh CAVEATS
 284 See
 285 .Xr mdoc 3
 286 for a list of bugs, caveats, and incomplete macros regarding the
 287 document parse.
 288 .Pp
 289 The
 290 .Nm
 291 utility doesn't yet know how to display the following:
 292 .Pp
 293 .Bl -bullet -compact
 294 .It
 295 The \-hang
 296 .Sq \&Bl
 297 list is not yet supported.
 298 .It
 299 The \-literal and \-unfilled
 300 .Sq \&Bd
 301 displays only accept text contents.
 302 .It
 303 The
 304 .Sq \&Xo/Xc
 305 pair isn't supported (and never will be).
 306 .It
 307 The
 308 .Sq \&Sm
 309 macro has no effect, yet.
 310 .El