mdocterm.1

   1 .\" $Id: mdocterm.1,v 1.14 2009/03/06 14:13:47 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 6 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 v
  30 .Op Fl W Ns Ar err...
  31 .Op Ar infile
  32 .\" SECTION
  33 .Sh DESCRIPTION
  34 The
  35 .Nm
  36 utility formats a BSD
  37 .Dq mdoc
  38 manual page for display on the terminal.  The arguments are as follows:
  39 .Bl -tag -width "\-Werr... "
  40 .\" ITEM
  41 .It Fl v
  42 Print verbose parsing output.
  43 .\" ITEM
  44 .It Fl W Ns Ar err...
  45 Print warning messages.  May be set to
  46 .Fl W Ns Ar all
  47 for all warnings,
  48 .Ar compat
  49 for groff/troff-compatibility warnings, or
  50 .Ar syntax
  51 for syntax warnings.  If
  52 .Fl W Ns Ar error
  53 is specified, warnings are considered errors and cause utility
  54 termination.  Multiple
  55 .Fl W
  56 arguments may be comma-separated, such as
  57 .Fl W Ns Ar error,all .
  58 .\" ITEM
  59 .It Ar infile
  60 Read input from
  61 .Ar infile ,
  62 which may be
  63 .Dq \-
  64 for stdin.
  65 .El
  66 .\" PARAGRAPH
  67 .Pp
  68 The
  69 .Nm
  70 utility is a formatting front-end for
  71 .Xr mdoc 3 ,
  72 which parses the
  73 .Dq mdoc
  74 input, documented at
  75 .Xr mdoc 7
  76 and
  77 .Xr mdoc.samples 7 ,
  78 into an abstract syntax tree.
  79 .\" PARAGRAPH
  80 .Pp
  81 By default,
  82 .Nm
  83 reads from stdin and prints terminal-encoded output to stdout.
  84 .\" PARAGRAPH
  85 .Pp
  86 .Ex -std mdocmterm
  87 .\" PARAGRAPH
  88 .Pp
  89 .Nm
  90 is
  91 .Ud
  92 .\" SUB-SECTION
  93 .Ss Character Escapes
  94 This section documents the character-escapes accepted by
  95 .Xr mdocterm 1 .
  96 Note that the \\x, \\(xx and \\[n] forms are described here; the \\*(xx,
  97 \\*[n] and \\*x forms described in
  98 .Xr mdoc.samples 7
  99 are deprecated, but still rendered.  All one- and two-character
 100 sequences may be used in the n-character sequence \\[n].
 101 .Pp
 102 Note that the
 103 .Em Output
 104 column will render differently whether executed with
 105 .Xr mdocterm 1
 106 or another output filter.
 107 .\" PARAGRAPH
 108 .Pp
 109 Grammatic:
 110 .Pp
 111 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 112 .It Em Output
 113 .Em Input (Name)
 114 .It \(em
 115 \\(em (em-dash)
 116 .It \(en
 117 \\(en (en-dash)
 118 .It \-
 119 \\- (hyphen)
 120 .It \\
 121 \\\\ (back-slash)
 122 .El
 123 .\" PARAGRAPH
 124 .Pp
 125 Enclosures:
 126 .Pp
 127 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 128 .It Em Output
 129 .Em Input (Name)
 130 .It \(ra
 131 \\(ra (right angle)
 132 .It \(la
 133 \\(la (left angle)
 134 .It \(rB
 135 \\(rB (right bracket)
 136 .It \(lB
 137 \\(lB (left bracket)
 138 .It \(lq
 139 \\(lq (left double-quote)
 140 .It \(rq
 141 \\(rq (right double-quote)
 142 .It \(oq
 143 \\(oq, \\` (left single-quote)
 144 .It \(aq
 145 \\(aq, \\' (right single-quote, apostrophe)
 146 .El
 147 .\" PARAGRAPH
 148 .Pp
 149 Indicatives:
 150 .Pp
 151 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 152 .It Em Output
 153 .Em Input (Name)
 154 .It \(<-
 155 \\(<- (left arrow)
 156 .It \(->
 157 \\(-> (right arrow)
 158 .It \(ua
 159 \\(ua (up arrow)
 160 .It \(da
 161 \\(da (down arrow)
 162 .El
 163 .\" PARAGRAPH
 164 .Pp
 165 Mathematical:
 166 .Pp
 167 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 168 .It Em Output
 169 .Em Input (Name)
 170 .It \(<=
 171 \\(<= (less-than-equal)
 172 .It \(>=
 173 \\(>= (greater-than-equal)
 174 .It \(==
 175 \\(== (equal)
 176 .It \(!=
 177 \\(!= (not equal)
 178 .It \(if
 179 \\(if (infinity)
 180 .It \(na
 181 \\(na (NaN)*
 182 .It \(+-
 183 \\(+- (plus-minus)
 184 .It \(**
 185 \\(** (asterisk)
 186 .El
 187 .\" PARAGRAPH
 188 .Pp
 189 Diacritics:
 190 .Pp
 191 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 192 .It Em Output
 193 .Em Input (Name)
 194 .It \(ga
 195 \\(ga (accent grave)
 196 .It \(aa
 197 \\(aa (accent accute)
 198 .El
 199 .\" PARAGRAPH
 200 .Pp
 201 Special symbols:
 202 .Pp
 203 .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
 204 .It Em Output
 205 .Em Input (Name)
 206 .It \(bu
 207 \\(bu (bullet)
 208 .It \(ba
 209 \\(ba (bar)
 210 .It \(co
 211 \\(co (copyright)
 212 .El
 213 .Pp
 214 *This is a deviation from the standard, as NaN is usually rendered as
 215 \\*(Na, which is a deprecated form.  We introduce \\(na, which follows
 216 the more general syntax.
 217 .\" SECTION
 218 .Sh EXAMPLES
 219 To display this manual page:
 220 .\" PARAGRAPH
 221 .Pp
 222 .D1 % mdocmterm \-Wall,error mdocmterm.1
 223 .\" PARAGRAPH
 224 .Pp
 225 To pipe a manual page to the pager:
 226 .Pp
 227 .D1 % mdocterm mdocterm.1 | less \-R
 228 .\" SECTION
 229 .Sh SEE ALSO
 230 .Xr mdoctree 1 ,
 231 .Xr mdoclint 1 ,
 232 .Xr mdoc.samples 7 ,
 233 .Xr mdoc 7 ,
 234 .Xr mdoc 3
 235 .\"
 236 .Sh AUTHORS
 237 The
 238 .Nm
 239 utility was written by
 240 .An Kristaps Dzonsons Aq kristaps@kth.se .
 241 .\" SECTION
 242 .Sh CAVEATS
 243 See
 244 .Xr mdoc 3
 245 for a list of bugs, caveats, and incomplete macros regarding the
 246 document parse.
 247 .Pp
 248 The
 249 .Nm
 250 utility doesn't yet know how to display the following:
 251 .Pp
 252 .Bl -bullet -compact
 253 .It
 254 The \-hang and \-column
 255 .Sq \&Bl
 256 lists are not yet supported.
 257 .It
 258 The \-literal and \-unfilled
 259 .Sq \&Bd
 260 displays only accept text contents.
 261 .It
 262 The
 263 .Sq \&Xo/Xc
 264 pair isn't supported (and never will be).
 265 .It
 266 The
 267 .Sq \&Sm
 268 macro has no effect, yet.
 269 .El