usr.bin/mandoc/mandoc.1

   1 .\"     $Id: mandoc.1,v 1.18 2009/10/27 21:40:07 schwarze 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 October 29, 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 no-ign-escape
 232 Don't ignore invalid escape sequences.
 233 .
 234 .It Fl f Ns Ar no-ign-macro
 235 Do not ignore unknown macros at the start of input lines.
 236 .
 237 .It Fl f Ns Ar no-ign-chars
 238 Do not ignore disallowed characters.
 239 .
 240 .It Fl f Ns Ar strict
 241 Implies
 242 .Fl f Ns Ar no-ign-escape ,
 243 .Fl f Ns Ar no-ign-macro
 244 and
 245 .Fl f Ns Ar no-ign-chars .
 246 .
 247 .It Fl f Ns Ar ign-errors
 248 Don't halt when encountering parse errors.  Useful with
 249 .Fl T Ns Ar lint
 250 over a large set of manuals passed on the command line.
 251 .El
 252 .
 253 .Ss Output Options
 254 For the time being, only
 255 .Fl T Ns Ar html
 256 is the only mode with output options:
 257 .Bl -tag -width Ds
 258 .It Fl O Ns Ar style=style.css
 259 The file
 260 .Ar style.css
 261 is used for an external style-sheet.  This must be a valid absolute or
 262 relative URI.
 263 .It Fl O Ns Ar includes=fmt
 264 The string
 265 .Ar fmt ,
 266 for example,
 267 .Ar ../src/%I.html ,
 268 is used as a template for linked header files (usually via the
 269 .Sq \&In
 270 macro).  Instances of
 271 .Sq \&%I
 272 are replaced with the include filename.  The default is not to present a
 273 hyperlink.
 274 .It Fl O Ns Ar man=fmt
 275 The string
 276 .Ar fmt ,
 277 for example,
 278 .Ar ../html%S/%N.%S.html ,
 279 is used as a template for linked manuals (usually via the
 280 .Sq \&Xr
 281 macro).  Instances of
 282 .Sq \&%N
 283 and
 284 .Sq %S
 285 are replaced with the linked manual's name and section, respectively.
 286 If no section is included, section 1 is assumed.  The default is not to
 287 present a hyperlink.
 288 .El
 289 .
 290 .Sh EXAMPLES
 291 To page manuals to the terminal:
 292 .
 293 .Pp
 294 .D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
 295 .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
 296 .
 297 .Pp
 298 To produce HTML manuals with
 299 .Ar style.css
 300 as the style-sheet:
 301 .Pp
 302 .D1 % mandoc \-Thtml -ostyle=style.css mdoc.7 > mdoc.7.html
 303 .Pp
 304 To check over a large set of manuals:
 305 .
 306 .Pp
 307 .Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
 308 .
 309 .
 310 .Sh COMPATIBILITY
 311 This section summarises
 312 .Nm
 313 compatibility with
 314 .Xr groff 1 .
 315 Each input and output format is separately noted.
 316 .
 317 .
 318 .Ss ASCII output
 319 .Bl -bullet -compact
 320 .It
 321 The
 322 .Sq \e~
 323 special character doesn't produce expected behaviour in
 324 .Fl T Ns Ar ascii .
 325 .
 326 .It
 327 The
 328 .Sq \&Bd \-literal
 329 and
 330 .Sq \&Bd \-unfilled
 331 macros of
 332 .Xr mdoc 7
 333 in
 334 .Fl T Ns Ar ascii
 335 are synonyms, as are \-filled and \-ragged.
 336 .
 337 .It
 338 In
 339 .Xr groff 1 ,
 340 the
 341 .Sq \&Pa
 342 .Xr mdoc 7
 343 macro does not underline when scoped under an
 344 .Sq \&It
 345 in the FILES section.  This behaves correctly in
 346 .Nm .
 347 .
 348 .It
 349 A list or display following
 350 .Sq \&Ss
 351 .Xr mdoc 7
 352 macro in
 353 .Fl T Ns Ar ascii
 354 does not assert a prior vertical break, just as it doesn't with
 355 .Sq \&Sh .
 356 .
 357 .It
 358 The
 359 .Sq \&na
 360 .Xr man 7
 361 macro in
 362 .Fl T Ns Ar ascii
 363 has no effect.
 364 .
 365 .It
 366 Words aren't hyphenated.
 367 .
 368 .It
 369 In normal mode (not a literal block), blocks of spaces aren't preserved,
 370 so double spaces following sentence closure are reduced to a single space;
 371 .Xr groff 1
 372 retains spaces.
 373 .
 374 .It
 375 Sentences are unilaterally monospaced.
 376 .El
 377 .
 378 .Ss HTML output
 379 .Bl -bullet -compact
 380 .It
 381 The
 382 .Xr mdoc 7
 383 .Sq \&Bl \-hang
 384 and
 385 .Sq \&Bl \-tag
 386 list types render similarly (no break following overreached left-hand
 387 side) due to the expressive constraints of HTML.
 388 .
 389 .It
 390 The
 391 .Xr man 7
 392 .Sq IP
 393 and
 394 .Sq TP
 395 lists render similarly.
 396 .El
 397 .\" SECTION
 398 .Sh SEE ALSO
 399 .Xr mandoc_char 7 ,
 400 .Xr mdoc 7 ,
 401 .Xr man 7
 402 .
 403 .Sh AUTHORS
 404 The
 405 .Nm
 406 utility was written by
 407 .An Kristaps Dzonsons Aq kristaps@kth.se .
 408 .
 409 .Sh CAVEATS
 410 In
 411 .Fl T Ns Ar html ,
 412 the maximum size of an element attribute is determined by
 413 .Dv BUFSIZ ,
 414 which is usually 1024 bytes.  Be aware of this when setting long link
 415 formats with
 416 .Fl O Ns Ar man=fmt .