mdocterm.1

   1 .\" $Id: mdocterm.1,v 1.26 2009/03/19 11:49:00 kristaps Exp $
   2 .\"
   3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
   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 19 2009 $
  20 .Dt mdocterm 1
  21 .Os
  22 .\" SECTION
  23 .Sh NAME
  24 .Nm mdocterm
  25 .Nd mdoc macro compiler
  26 .\" SECTION
  27 .Sh SYNOPSIS
  28 .Nm mdocterm
  29 .Op Fl V
  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 version and exit.
  44 .\" ITEM
  45 .It Fl f Ns Ar option...
  46 Override default compiler behaviour.  See
  47 .Sx Compiler Options
  48 for details.
  49 .\" ITEM
  50 .It Fl W Ns Ar err...
  51 Print warning messages.  May be set to
  52 .Fl W Ns Ar all
  53 for all warnings,
  54 .Ar compat
  55 for groff/troff-compatibility warnings, or
  56 .Ar syntax
  57 for syntax warnings.  If
  58 .Fl W Ns Ar error
  59 is specified, warnings are considered errors and cause utility
  60 termination.  Multiple
  61 .Fl W
  62 arguments may be comma-separated, such as
  63 .Fl W Ns Ar error,all .
  64 .\" ITEM
  65 .It Ar infile...
  66 Read input from zero or more
  67 .Ar infile .
  68 If unspecified, reads from stdin.
  69 .El
  70 .\" PARAGRAPH
  71 .Pp
  72 The
  73 .Nm
  74 utility is a formatting front-end for
  75 .Xr mdoc 3 ,
  76 which parses the
  77 .Dq mdoc
  78 input, documented at
  79 .Xr mdoc 7
  80 and
  81 .Xr mdoc.samples 7 ,
  82 into an abstract syntax tree.
  83 .\" PARAGRAPH
  84 .Pp
  85 By default,
  86 .Nm
  87 reads from stdin and prints nroff
  88 .Qq backspace
  89 terminal-encoded output to stdout, at this time to a fixed column with
  90 of 78 characters.
  91 .\" PARAGRAPH
  92 .Pp
  93 .Ex -std mdocterm
  94 .\" SUB-SECTION
  95 .Ss Compiler Options
  96 Default compiler behaviour may be overriden with the
  97 .Fl f
  98 flag.  The available options are as follows:
  99 .Bl -tag -width XXXXXXXXXXXX -offset XXXX
 100 .It Fl f Ns Ar ign-scope
 101 When rewinding the scope of a block macro, forces the compiler to ignore
 102 scope violations.  This can seriously mangle the resulting tree.
 103 .It Fl f Ns Ar ign-escape
 104 Ignore invalid escape sequences.
 105 .It Fl f Ns Ar ign-macro
 106 Ignore unknown macros at the start of input lines.
 107 .El
 108 .\" PARAGRAPH
 109 .Pp
 110 As with the
 111 .Fl W
 112 flag, multiple
 113 .Fl f
 114 options may be grouped and delimited with a comma.  Using
 115 .Fl f Ns Ar ign-scope,ign-escape ,
 116 for example, will try to ignore scope and character-escape errors.
 117 .\" SUB-SECTION
 118 .Ss Character Escapes
 119 The
 120 .Nm
 121 utility correctly renders all
 122 .Sx Special Characters
 123 in
 124 .Xr mdoc 7
 125 in 7-bit ASCII.
 126 .Pp
 127 In the general sense,
 128 .Nm
 129 will make a
 130 .Pq best-effort
 131 to render complex characters; however, if a manual is using considerable
 132 special characters, some meaning may be lost in translation.
 133 .\" SECTION
 134 .Sh EXAMPLES
 135 To display this manual page:
 136 .\" PARAGRAPH
 137 .Pp
 138 .D1 % mdocterm \-Wall,error mdocterm.1
 139 .\" PARAGRAPH
 140 .Pp
 141 To pipe a manual page to the pager:
 142 .Pp
 143 .D1 % mdocterm mdocterm.1 | less
 144 .\" SECTION
 145 .Sh SEE ALSO
 146 .Xr mdoc 7 ,
 147 .Xr mdoc 3
 148 .\"
 149 .Sh AUTHORS
 150 The
 151 .Nm
 152 utility was written by
 153 .An Kristaps Dzonsons Aq kristaps@openbsd.org .
 154 .\" SECTION
 155 .Sh CAVEATS
 156 See
 157 .Xr mdoc 3
 158 for a list of bugs, caveats, and incomplete macros regarding the
 159 document parse.
 160 .Pp
 161 The
 162 .Nm
 163 utility doesn't yet know how to display the following:
 164 .Pp
 165 .Bl -bullet -compact
 166 .It
 167 The \-hang
 168 .Sq \&Bl
 169 list is not yet supported.
 170 .It
 171 The \-literal and \-unfilled
 172 .Sq \&Bd
 173 displays only accept text contents.
 174 .It
 175 The
 176 .Sq \&Xo/Xc
 177 pair isn't supported (and never will be).
 178 .It
 179 The
 180 .Sq \&Sm
 181 macro has no effect, yet.
 182 .El