mandoc.1

   1 .\"     $Id: mandoc.1,v 1.45 2009/10/26 15:44:51 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 above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: October 26 2009 $
  18 .Dt MANDOC 1
  19 .Os
  20 .
  21 .
  22 .Sh NAME
  23 .Nm mandoc
  24 .Nd format and display UNIX manuals
  25 .
  26 .
  27 .Sh SYNOPSIS
  28 .Nm mandoc
  29 .Op Fl f Ns Ar option...
  30 .Op Fl m Ns Ar format
  31 .Op Fl O Ns Ar option...
  32 .Op Fl T Ns Ar output
  33 .Op Fl V
  34 .Op Fl W Ns Ar err...
  35 .Op Ar infile...
  36 .
  37 .
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 utility formats
  42 .Ux
  43 manual pages for display.  The arguments are as follows:
  44 .
  45 .Bl -tag -width Ds
  46 .It Fl f Ns Ar option...
  47 Comma-separated compiler options.  See
  48 .Sx Compiler Options
  49 for details.
  50 .
  51 .It Fl m Ns Ar format
  52 Input format.  See
  53 .Sx Input Formats
  54 for available formats.  Defaults to
  55 .Fl m Ns Ar andoc .
  56 .
  57 .It Fl O Ns Ar option...
  58 Comma-separated output options.  See
  59 .Sx Output Options
  60 for details.
  61 .
  62 .It Fl T Ns Ar output
  63 Output format.  See
  64 .Sx Output Formats
  65 for available formats.  Defaults to
  66 .Fl T Ns Ar ascii .
  67 .
  68 .It Fl V
  69 Print version and exit.
  70 .
  71 .It Fl W Ns Ar err...
  72 Comma-separated warning options.  Use
  73 .Fl W Ns Ar all
  74 to print warnings,
  75 .Fl W Ns Ar error
  76 for warnings to be considered errors and cause utility
  77 termination.  Multiple
  78 .Fl W
  79 arguments may be comma-separated, such as
  80 .Fl W Ns Ar error,all .
  81 .
  82 .It Ar infile...
  83 Read input from zero or more
  84 .Ar infile .
  85 If unspecified, reads from stdin.  If multiple files are specified,
  86 .Nm
  87 will halt with the first failed parse.
  88 .El
  89 .
  90 .Pp
  91 By default,
  92 .Nm
  93 reads
  94 .Xr mdoc 7
  95 or
  96 .Xr man 7
  97 text from stdin, implying
  98 .Fl m Ns Ar andoc ,
  99 and prints 78-column backspace-encoded output to stdout as if
 100 .Fl T Ns Ar ascii
 101 were provided.
 102 .
 103 .Pp
 104 .Ex -std mandoc
 105 .
 106 .
 107 .Ss Punctuation and Spacing
 108 If punctuation is set apart from words, such as in the phrase
 109 .Dq to be \&, or not to be ,
 110 it's processed by
 111 .Nm
 112 according to the following rules:  opening punctuation
 113 .Po
 114 .Sq \&( ,
 115 .Sq \&[ ,
 116 and
 117 .Sq \&{
 118 .Pc
 119 is not followed by a space; closing punctuation
 120 .Po
 121 .Sq \&. ,
 122 .Sq \&, ,
 123 .Sq \&; ,
 124 .Sq \&: ,
 125 .Sq \&? ,
 126 .Sq \&! ,
 127 .Sq \&) ,
 128 .Sq \&]
 129 and
 130 .Sq \&}
 131 .Pc
 132 is not preceded by whitespace.
 133 .
 134 .Pp
 135 If the input is
 136 .Xr mdoc 7 ,
 137 these rules are also applied to macro arguments when appropriate.
 138 .
 139 .Pp
 140 White-space, in non-literal (normal) mode, is stripped from input and
 141 replaced on output by a single space.  Thus, if you wish to preserve multiple
 142 spaces, they must be space-escaped or used in a literal display mode, e.g.,
 143 .Sq \&Bd \-literal
 144 in
 145 .Xr mdoc 7 .
 146 .
 147 .
 148 .Ss Input Formats
 149 The
 150 .Nm
 151 utility accepts
 152 .Xr mdoc 7
 153 and
 154 .Xr man 7
 155 input with
 156 .Fl m Ns Ar doc
 157 and
 158 .Fl m Ns Ar an ,
 159 respectively.  The
 160 .Xr mdoc 7
 161 format is
 162 .Em strongly
 163 recommended;
 164 .Xr man 7
 165 should only be used for legacy manuals.
 166 .
 167 .Pp
 168 A third option,
 169 .Fl m Ns Ar andoc ,
 170 which is also the default, determines encoding on-the-fly: if the first
 171 non-comment macro is
 172 .Sq \&Dd
 173 or
 174 .Sq \&Dt ,
 175 the
 176 .Xr mdoc 7
 177 parser is used; otherwise, the
 178 .Xr man 7
 179 parser is used.
 180 .
 181 .Pp
 182 If multiple
 183 files are specified with
 184 .Fl m Ns Ar andoc ,
 185 each has its file-type determined this way.  If multiple files are
 186 specified and
 187 .Fl m Ns Ar doc
 188 or
 189 .Fl m Ns Ar an
 190 is specified, then this format is used exclusively.
 191 .
 192 .
 193 .Ss Output Formats
 194 The
 195 .Nm
 196 utility accepts the following
 197 .Fl T
 198 arguments:
 199 .
 200 .Bl -tag -width Ds
 201 .It Fl T Ns Ar ascii
 202 Produce 7-bit ASCII output, backspace-encoded for bold and underline
 203 styles.  This is the default.
 204 .
 205 .It Fl T Ns Ar html
 206 Produce strict HTML-4.01 output, with a sane default style.
 207 .
 208 .It Fl T Ns Ar tree
 209 Produce an indented parse tree.
 210 .
 211 .It Fl T Ns Ar lint
 212 Parse only: produce no output.
 213 .El
 214 .
 215 .Pp
 216 If multiple input files are specified, these will be processed by the
 217 corresponding filter in-order.
 218 .
 219 .
 220 .Ss Compiler Options
 221 Default compiler behaviour may be overridden with the
 222 .Fl f
 223 flag.
 224 .
 225 .Bl -tag -width Ds
 226 .It Fl f Ns Ar ign-scope
 227 When rewinding the scope of a block macro, forces the compiler to ignore
 228 scope violations.  This can seriously mangle the resulting tree.
 229 .Pq mdoc only
 230 .
 231 .It Fl f Ns Ar ign-escape
 232 Ignore invalid escape sequences.
 233 This is the default, but the option can be used to override an earlier
 234 .Fl f Ns Ar strict .
 235 .
 236 .It Fl f Ns Ar no-ign-escape
 237 Don't ignore invalid escape sequences.
 238 .
 239 .It Fl f Ns Ar no-ign-macro
 240 Do not ignore unknown macros at the start of input lines.
 241 .
 242 .It Fl f Ns Ar no-ign-chars
 243 Do not ignore disallowed characters.
 244 .
 245 .It Fl f Ns Ar strict
 246 Implies
 247 .Fl f Ns Ar no-ign-escape ,
 248 .Fl f Ns Ar no-ign-macro
 249 and
 250 .Fl f Ns Ar no-ign-chars .
 251 .
 252 .It Fl f Ns Ar ign-errors
 253 Don't halt when encountering parse errors.  Useful with
 254 .Fl T Ns Ar lint
 255 over a large set of manuals passed on the command line.
 256 .El
 257 .
 258 .Ss Output Options
 259 For the time being, only
 260 .Fl T Ns Ar html
 261 is the only mode with output options:
 262 .Bl -tag -width Ds
 263 .It Fl O Ns Ar style=style.css
 264 The file
 265 .Ar style.css
 266 is used for an external style-sheet.  This must be a valid absolute or
 267 relative URI.
 268 .It Fl O Ns Ar includes=fmt
 269 The string
 270 .Ar fmt ,
 271 for example,
 272 .Ar ../src/%I.html ,
 273 is used as a template for linked header files (usually via the
 274 .Sq \&In
 275 macro).  Instances of
 276 .Sq \&%I
 277 are replaced with the include filename.  The default is not to present a
 278 hyperlink.
 279 .It Fl O Ns Ar man=fmt
 280 The string
 281 .Ar fmt ,
 282 for example,
 283 .Ar ../html%S/%N.%S.html ,
 284 is used as a template for linked manuals (usually via the
 285 .Sq \&Xr
 286 macro).  Instances of
 287 .Sq \&%N
 288 and
 289 .Sq %S
 290 are replaced with the linked manual's name and section, respectively.
 291 If no section is included, section 1 is assumed.  The default is not to
 292 present a hyperlink.
 293 .El
 294 .
 295 .Sh EXAMPLES
 296 To page manuals to the terminal:
 297 .
 298 .Pp
 299 .D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
 300 .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
 301 .
 302 .Pp
 303 To produce HTML manuals with
 304 .Ar style.css
 305 as the style-sheet:
 306 .Pp
 307 .D1 % mandoc \-Thtml -ostyle=style.css mdoc.7 > mdoc.7.html
 308 .Pp
 309 To check over a large set of manuals:
 310 .
 311 .Pp
 312 .Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
 313 .
 314 .
 315 .Sh COMPATIBILITY
 316 This section summarises
 317 .Nm
 318 compatibility with
 319 .Xr groff 1 .
 320 Each input and output format is separately noted.
 321 .
 322 .
 323 .Ss ASCII output
 324 .Bl -bullet -compact
 325 .It
 326 The
 327 .Sq \e~
 328 special character doesn't produce expected behaviour in
 329 .Fl T Ns Ar ascii .
 330 .
 331 .It
 332 The
 333 .Sq \&Bd \-literal
 334 and
 335 .Sq \&Bd \-unfilled
 336 macros of
 337 .Xr mdoc 7
 338 in
 339 .Fl T Ns Ar ascii
 340 are synonyms, as are \-filled and \-ragged.
 341 .
 342 .It
 343 In
 344 .Xr groff 1 ,
 345 the
 346 .Sq \&Pa
 347 .Xr mdoc 7
 348 macro does not underline when scoped under an
 349 .Sq \&It
 350 in the FILES section.  This behaves correctly in
 351 .Nm .
 352 .
 353 .It
 354 A list or display following
 355 .Sq \&Ss
 356 .Xr mdoc 7
 357 macro in
 358 .Fl T Ns Ar ascii
 359 does not assert a prior vertical break, just as it doesn't with
 360 .Sq \&Sh .
 361 .
 362 .It
 363 The
 364 .Sq \&na
 365 .Xr man 7
 366 macro in
 367 .Fl T Ns Ar ascii
 368 has no effect.
 369 .
 370 .It
 371 Words aren't hyphenated.
 372 .
 373 .It
 374 In normal mode (not a literal block), blocks of spaces aren't preserved,
 375 so double spaces following sentence closure are reduced to a single space;
 376 .Xr groff 1
 377 retains spaces.
 378 .
 379 .It
 380 Sentences are unilaterally monospaced.
 381 .El
 382 .
 383 .Ss HTML output
 384 .Bl -bullet -compact
 385 .It
 386 The
 387 .Xr mdoc 7
 388 .Sq \&Bl \-hang
 389 and
 390 .Sq \&Bl \-tag
 391 list types render similarly (no break following overreached left-hand
 392 side) due to the expressive constraints of HTML.
 393 .
 394 .It
 395 The
 396 .Xr man 7
 397 .Sq IP
 398 and
 399 .Sq TP
 400 lists render similarly.
 401 .El
 402 .\" SECTION
 403 .Sh SEE ALSO
 404 .Xr mandoc_char 7 ,
 405 .Xr mdoc 7 ,
 406 .Xr man 7
 407 .
 408 .Sh AUTHORS
 409 The
 410 .Nm
 411 utility was written by
 412 .An Kristaps Dzonsons Aq kristaps@kth.se .
 413 .
 414 .Sh CAVEATS
 415 In
 416 .Fl T Ns Ar html ,
 417 the maximum size of an element attribute is determined by
 418 .Dv BUFSIZ ,
 419 which is usually 1024 bytes.  Be aware of this when setting long link
 420 formats with
 421 .Fl O Ns Ar man=fmt .