mdocterm.1

   1 .\" $Id: mdocterm.1,v 1.15 2009/03/08 18:02:36 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 8 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 .El
 110 .\" PARAGRAPH
 111 .Pp
 112 As with the
 113 .Fl W
 114 flag, multiple
 115 .Fl f
 116 options may be grouped and delimited with a comma.  Using
 117 .Fl f Ns Ar ign-scope,ign-escape ,
 118 for example, will try to ignore scope and character-escape errors.
 119 .\" SUB-SECTION
 120 .Ss Character Escapes
 121 This section documents the character-escapes accepted by
 122 .Xr mdocterm 1 .
 123 Note that the \\x, \\(xx and \\[n] forms are described here; the \\*(xx,
 124 \\*[n] and \\*x forms described in
 125 .Xr mdoc.samples 7
 126 are deprecated, but still rendered.  All one- and two-character
 127 sequences may be used in the n-character sequence \\[n].
 128 .Pp
 129 Note that the
 130 .Em Output
 131 column will render differently whether executed with
 132 .Xr mdocterm 1
 133 or another output filter.
 134 .\" PARAGRAPH
 135 .Pp
 136 Grammatic:
 137 .Pp
 138 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 139 .It Em Output
 140 .Em Input (Name)
 141 .It \(em
 142 \\(em (em-dash)
 143 .It \(en
 144 \\(en (en-dash)
 145 .It \-
 146 \\- (hyphen)
 147 .It \\
 148 \\\\ (back-slash)
 149 .El
 150 .\" PARAGRAPH
 151 .Pp
 152 Enclosures:
 153 .Pp
 154 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 155 .It Em Output
 156 .Em Input (Name)
 157 .It \(ra
 158 \\(ra (right angle)
 159 .It \(la
 160 \\(la (left angle)
 161 .It \(rB
 162 \\(rB (right bracket)
 163 .It \(lB
 164 \\(lB (left bracket)
 165 .It \(lq
 166 \\(lq (left double-quote)
 167 .It \(rq
 168 \\(rq (right double-quote)
 169 .It \(oq
 170 \\(oq, \\` (left single-quote)
 171 .It \(aq
 172 \\(aq, \\' (right single-quote, apostrophe)
 173 .El
 174 .\" PARAGRAPH
 175 .Pp
 176 Indicatives:
 177 .Pp
 178 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 179 .It Em Output
 180 .Em Input (Name)
 181 .It \(<-
 182 \\(<- (left arrow)
 183 .It \(->
 184 \\(-> (right arrow)
 185 .It \(ua
 186 \\(ua (up arrow)
 187 .It \(da
 188 \\(da (down arrow)
 189 .El
 190 .\" PARAGRAPH
 191 .Pp
 192 Mathematical:
 193 .Pp
 194 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 195 .It Em Output
 196 .Em Input (Name)
 197 .It \(<=
 198 \\(<= (less-than-equal)
 199 .It \(>=
 200 \\(>= (greater-than-equal)
 201 .It \(==
 202 \\(== (equal)
 203 .It \(!=
 204 \\(!= (not equal)
 205 .It \(if
 206 \\(if (infinity)
 207 .It \(na
 208 \\(na (NaN)*
 209 .It \(+-
 210 \\(+- (plus-minus)
 211 .It \(**
 212 \\(** (asterisk)
 213 .El
 214 .\" PARAGRAPH
 215 .Pp
 216 Diacritics:
 217 .Pp
 218 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 219 .It Em Output
 220 .Em Input (Name)
 221 .It \(ga
 222 \\(ga (accent grave)
 223 .It \(aa
 224 \\(aa (accent accute)
 225 .El
 226 .\" PARAGRAPH
 227 .Pp
 228 Special symbols:
 229 .Pp
 230 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 231 .It Em Output
 232 .Em Input (Name)
 233 .It \(bu
 234 \\(bu (bullet)
 235 .It \(ba
 236 \\(ba (bar)
 237 .It \(co
 238 \\(co (copyright)
 239 .El
 240 .Pp
 241 *This is a deviation from the standard, as NaN is usually rendered as
 242 \\*(Na, which is a deprecated form.  We introduce \\(na, which follows
 243 the more general syntax.
 244 .\" SECTION
 245 .Sh EXAMPLES
 246 To display this manual page:
 247 .\" PARAGRAPH
 248 .Pp
 249 .D1 % mdocmterm \-Wall,error mdocmterm.1
 250 .\" PARAGRAPH
 251 .Pp
 252 To pipe a manual page to the pager:
 253 .Pp
 254 .D1 % mdocterm mdocterm.1 2>&1 | less \-R
 255 .\" SECTION
 256 .Sh SEE ALSO
 257 .Xr mdoctree 1 ,
 258 .Xr mdoclint 1 ,
 259 .Xr mdoc.samples 7 ,
 260 .Xr mdoc 7 ,
 261 .Xr mdoc 3
 262 .\"
 263 .Sh AUTHORS
 264 The
 265 .Nm
 266 utility was written by
 267 .An Kristaps Dzonsons Aq kristaps@kth.se .
 268 .\" SECTION
 269 .Sh CAVEATS
 270 See
 271 .Xr mdoc 3
 272 for a list of bugs, caveats, and incomplete macros regarding the
 273 document parse.
 274 .Pp
 275 The
 276 .Nm
 277 utility doesn't yet know how to display the following:
 278 .Pp
 279 .Bl -bullet -compact
 280 .It
 281 The \-hang and \-column
 282 .Sq \&Bl
 283 lists are not yet supported.
 284 .It
 285 The \-literal and \-unfilled
 286 .Sq \&Bd
 287 displays only accept text contents.
 288 .It
 289 The
 290 .Sq \&Xo/Xc
 291 pair isn't supported (and never will be).
 292 .It
 293 The
 294 .Sq \&Sm
 295 macro has no effect, yet.
 296 .El