mandoc.1

   1 .\" $Id: mandoc.1,v 1.14 2009/04/12 19:19:57 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: April 12 2009 $
  20 .Dt MANDOC 1
  21 .Os
  22 .\" SECTION
  23 .Sh NAME
  24 .Nm mandoc
  25 .Nd format and display UNIX manuals
  26 .\" SECTION
  27 .Sh SYNOPSIS
  28 .Nm mandoc
  29 .Op Fl V
  30 .Op Fl f Ns Ar option...
  31 .Op Fl m Ns Ar format
  32 .Op Fl W Ns Ar err...
  33 .Op Fl T Ns Ar output
  34 .Op Ar infile...
  35 .\" SECTION
  36 .Sh DESCRIPTION
  37 The
  38 .Nm
  39 utility formats
  40 .Ux
  41 manual pages for display.  The arguments are as follows:
  42 .Bl -tag -width XXXXXXXXXXXX
  43 .\" ITEM
  44 .It Fl f Ns Ar option...
  45 Override default compiler behaviour.  See
  46 .Sx Compiler Options
  47 for details.
  48 .\" ITEM
  49 .It Fl m
  50 Input format.  See
  51 .Sx Input Formats
  52 for available formats.  Defaults to
  53 .Fl m Ns Ar andoc .
  54 .\" ITEM
  55 .It Fl T
  56 Output format.  See
  57 .Sx Output Formats
  58 for available formats.  Defaults to
  59 .Fl T Ns Ar ascii .
  60 .\" ITEM
  61 .It Fl V
  62 Print version and exit.
  63 .\" ITEM
  64 .It Fl W Ns Ar err...
  65 Print warning messages.  May be set to
  66 .Fl W Ns Ar all
  67 for all warnings,
  68 .Ar compat
  69 for groff/troff-compatibility warnings, or
  70 .Ar syntax
  71 for syntax warnings.  If
  72 .Fl W Ns Ar error
  73 is specified, warnings are considered errors and cause utility
  74 termination.  Multiple
  75 .Fl W
  76 arguments may be comma-separated, such as
  77 .Fl W Ns Ar error,all .
  78 .\" ITEM
  79 .It Ar infile...
  80 Read input from zero or more
  81 .Ar infile .
  82 If unspecified, reads from stdin.  If multiple files are specified,
  83 .Nm
  84 will halt with the first failed parse.
  85 .El
  86 .\" PARAGRAPH
  87 .Pp
  88 By default,
  89 .Nm
  90 reads
  91 .Xr mdoc 7
  92 or
  93 .Xr man 7
  94 text from stdin, implying
  95 .Fl m Ns Ar andoc ,
  96 and prints 78-column backspace-encoded output to stdout as if
  97 .Fl T Ns Ar ascii
  98 were provided.
  99 .\" PARAGRAPH
 100 .Pp
 101 .Ex -std mandoc
 102 .\" SUB-SECTION
 103 .Ss Punctuation
 104 If punctuation is set apart from words, such as in the phrase
 105 .Dq to be \&, or not to be ,
 106 it's processed by
 107 .Nm
 108 according to the following rules.  Opening punctuation
 109 .Po
 110 .Sq \&( ,
 111 .Sq \&[ ,
 112 and
 113 .Sq \&{
 114 .Pc
 115 is not followed by a space. Closing punctuation
 116 .Po
 117 .Sq \&. ,
 118 .Sq \&, ,
 119 .Sq \&; ,
 120 .Sq \&: ,
 121 .Sq \&? ,
 122 .Sq \&! ,
 123 .Sq \&) ,
 124 .Sq \&]
 125 and
 126 .Sq \&}
 127 .Pc
 128 is not preceeded by whitespace.
 129 .Pp
 130 If the input is
 131 .Xr mdoc 7 ,
 132 these rules are also applied to macro arguments when appropriate.
 133 .\" SUB-SECTION
 134 .Ss Input Formats
 135 The
 136 .Nm
 137 utility accepts
 138 .Xr mdoc 7
 139 and
 140 .Xr man 7
 141 input with
 142 .Fl m Ns Ar doc
 143 and
 144 .Fl m Ns Ar an ,
 145 respectively.  The
 146 .Xr mdoc 7
 147 format is
 148 .Em strongly
 149 recommended;
 150 .Xr man 7
 151 should only be used for legacy manuals.
 152 .Pp
 153 A third option,
 154 .Fl m Ns Ar andoc ,
 155 which is also the default, determines encoding on-the-fly: if the first
 156 non-comment macro is
 157 .Sq \&.Dd
 158 or
 159 .Sq \&.Dt ,
 160 the
 161 .Xr mdoc 7
 162 parser is used; otherwise, the
 163 .Xr man 7
 164 parser is used.
 165 .Pp
 166 If multiple
 167 files are specified with
 168 .Fl m Ns Ar andoc ,
 169 each has its file-type determined this way.  If multiple files are
 170 specified and
 171 .Fl m Ns Ar doc
 172 or
 173 .Fl m Ns Ar an
 174 is specified, then this format is used exclusively.
 175 .\" .Pp
 176 .\" The following escape sequences are recognised, although the per-format
 177 .\" compiler may not allow certain sequences.
 178 .\" .Bl -tag -width Ds -offset XXXX
 179 .\" .It \efX
 180 .\" sets the font mode to X (B, I, R or P, where P resets the font)
 181 .\" .It \eX, \e(XX, \e[XN]
 182 .\" queries the special-character table for a corresponding symbol
 183 .\" .It \e*X, \e*(XX, \e*[XN]
 184 .\" deprecated special-character format
 185 .\" .El
 186 .\" SUB-SECTION
 187 .Ss Output Formats
 188 The
 189 .Nm
 190 utility accepts the following
 191 .Fl T
 192 arguments:
 193 .Bl -tag -width XXXXXXXXXXXX
 194 .It Fl T Ns Ar ascii
 195 Produce 7-bit ASCII output, backspace-encoded for bold and underline
 196 styles.  This is the default.
 197 .It Fl T Ns Ar tree
 198 Produce an indented parse tree.
 199 .It Fl T Ns Ar lint
 200 Parse only: produce no output.
 201 .El
 202 .Pp
 203 If multiple input files are specified, these will be processed by the
 204 corresponding filter in-order.
 205 .\" SUB-SECTION
 206 .Ss Compiler Options
 207 Default compiler behaviour may be overriden with the
 208 .Fl f
 209 flag.
 210 .Bl -tag -width XXXXXXXXXXXXXX
 211 .It Fl f Ns Ar ign-scope
 212 When rewinding the scope of a block macro, forces the compiler to ignore
 213 scope violations.  This can seriously mangle the resulting tree.
 214 .Pq mdoc only
 215 .It Fl f Ns Ar ign-escape
 216 Ignore invalid escape sequences.
 217 .It Fl f Ns Ar ign-macro
 218 Ignore unknown macros at the start of input lines (default for
 219 .Xr man 7
 220 parsing).
 221 .It Fl f Ns Ar no-ign-macro
 222 Do not ignore unknown macros at the start of input lines (default for
 223 .Xr mdoc 7
 224 parsing).
 225 .El
 226 .\" PARAGRAPH
 227 .Pp
 228 As with the
 229 .Fl W
 230 flag, multiple
 231 .Fl f
 232 options may be grouped and delimited with a comma.  Using
 233 .Fl f Ns Ar ign-scope,ign-escape ,
 234 for example, will try to ignore scope and character-escape errors.
 235 .\" SECTION
 236 .Sh EXAMPLES
 237 To page manuals to the terminal:
 238 .\" PARAGRAPH
 239 .Pp
 240 .D1 % mandoc \-Wall,error mandoc.1 2>&1 | less
 241 .Pp
 242 .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
 243 .\" SECTION
 244 .Sh SEE ALSO
 245 .Xr mandoc_char 7 ,
 246 .Xr mdoc 7 ,
 247 .Xr man 7
 248 .\"
 249 .Sh AUTHORS
 250 The
 251 .Nm
 252 utility was written by
 253 .An Kristaps Dzonsons Aq kristaps@openbsd.org .
 254 .\" SECTION
 255 .Sh CAVEATS
 256 The
 257 .Nm
 258 utility in
 259 .Fl T Ns Ar ascii
 260 mode doesn't yet know how to display the following:
 261 .Pp
 262 .Bl -bullet -compact
 263 .It
 264 The \-hang
 265 .Sq \&.Bl
 266 list is not yet supported.
 267 .El
 268 .Pp
 269 Other macros still aren't supported by virtue of nobody complaining
 270 about their absence.  Please report any omissions: this is a work in
 271 progress.
 272 .Pp
 273 The following list documents differences between traditional
 274 .Xr nroff 1
 275 output and
 276 .Nm :
 277 .Pp
 278 .Bl -bullet -compact
 279 .It
 280 A list of display following
 281 .Sq \&.Ss
 282 does not assert a prior vertical break, just as it doesn't with
 283 .Sq \&.Sh .
 284 .It
 285 Special characters don't follow the current font style.
 286 .\" LIST-ITEM
 287 .It
 288 The \-literal and \-unfilled
 289 .Sq \&.Bd
 290 displays types are synonyms, as are \-filled and \-ragged.
 291 .El