Annotation of mandoc/mandoc.1, Revision 1.57
1.57 ! kristaps 1: .\" $Id: mandoc.1,v 1.56 2010/03/29 10:10:35 kristaps Exp $
1.1 kristaps 2: .\"
1.17 kristaps 3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
1.1 kristaps 4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
1.16 kristaps 6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
1.1 kristaps 8: .\"
1.16 kristaps 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.
1.1 kristaps 16: .\"
1.57 ! kristaps 17: .Dd $Mdocdate: March 29 2010 $
1.14 kristaps 18: .Dt MANDOC 1
1.1 kristaps 19: .Os
1.32 kristaps 20: .
21: .
1.1 kristaps 22: .Sh NAME
23: .Nm mandoc
1.8 kristaps 24: .Nd format and display UNIX manuals
1.32 kristaps 25: .
26: .
1.1 kristaps 27: .Sh SYNOPSIS
28: .Nm mandoc
29: .Op Fl f Ns Ar option...
1.8 kristaps 30: .Op Fl m Ns Ar format
1.44 kristaps 31: .Op Fl O Ns Ar option...
1.37 kristaps 32: .Op Fl T Ns Ar output
33: .Op Fl V
1.1 kristaps 34: .Op Fl W Ns Ar err...
35: .Op Ar infile...
1.32 kristaps 36: .
37: .
1.1 kristaps 38: .Sh DESCRIPTION
39: The
40: .Nm
1.26 kristaps 41: utility formats
1.8 kristaps 42: .Ux
1.57 ! kristaps 43: manual pages for display.
! 44: The arguments are as follows:
1.32 kristaps 45: .
1.19 kristaps 46: .Bl -tag -width Ds
1.1 kristaps 47: .It Fl f Ns Ar option...
1.57 ! kristaps 48: Comma-separated compiler options.
! 49: See
1.1 kristaps 50: .Sx Compiler Options
51: for details.
1.32 kristaps 52: .
1.19 kristaps 53: .It Fl m Ns Ar format
1.57 ! kristaps 54: Input format.
! 55: See
1.8 kristaps 56: .Sx Input Formats
1.57 ! kristaps 57: for available formats.
! 58: Defaults to
1.12 kristaps 59: .Fl m Ns Ar andoc .
1.32 kristaps 60: .
1.44 kristaps 61: .It Fl O Ns Ar option...
1.57 ! kristaps 62: Comma-separated output options.
! 63: See
1.37 kristaps 64: .Sx Output Options
65: for details.
66: .
1.19 kristaps 67: .It Fl T Ns Ar output
1.57 ! kristaps 68: Output format.
! 69: See
1.1 kristaps 70: .Sx Output Formats
1.57 ! kristaps 71: for available formats.
! 72: Defaults to
1.1 kristaps 73: .Fl T Ns Ar ascii .
1.32 kristaps 74: .
1.1 kristaps 75: .It Fl V
76: Print version and exit.
1.32 kristaps 77: .
1.1 kristaps 78: .It Fl W Ns Ar err...
1.57 ! kristaps 79: Comma-separated warning options.
! 80: Use
1.1 kristaps 81: .Fl W Ns Ar all
1.24 kristaps 82: to print warnings,
1.26 kristaps 83: .Fl W Ns Ar error
1.24 kristaps 84: for warnings to be considered errors and cause utility
1.57 ! kristaps 85: termination.
! 86: Multiple
1.1 kristaps 87: .Fl W
88: arguments may be comma-separated, such as
89: .Fl W Ns Ar error,all .
1.32 kristaps 90: .
1.1 kristaps 91: .It Ar infile...
92: Read input from zero or more
93: .Ar infile .
1.57 ! kristaps 94: If unspecified, reads from stdin.
! 95: If multiple files are specified,
1.2 kristaps 96: .Nm
97: will halt with the first failed parse.
1.1 kristaps 98: .El
1.32 kristaps 99: .
1.1 kristaps 100: .Pp
1.26 kristaps 101: By default,
102: .Nm
103: reads
1.8 kristaps 104: .Xr mdoc 7
1.12 kristaps 105: or
106: .Xr man 7
1.8 kristaps 107: text from stdin, implying
1.12 kristaps 108: .Fl m Ns Ar andoc ,
1.48 kristaps 109: and produces
1.1 kristaps 110: .Fl T Ns Ar ascii
1.48 kristaps 111: output.
1.32 kristaps 112: .
1.1 kristaps 113: .Pp
114: .Ex -std mandoc
1.32 kristaps 115: .
116: .
1.8 kristaps 117: .Ss Input Formats
118: The
119: .Nm
120: utility accepts
121: .Xr mdoc 7
122: and
123: .Xr man 7
124: input with
1.10 kristaps 125: .Fl m Ns Ar doc
1.8 kristaps 126: and
1.10 kristaps 127: .Fl m Ns Ar an ,
1.57 ! kristaps 128: respectively.
! 129: The
1.8 kristaps 130: .Xr mdoc 7
131: format is
132: .Em strongly
1.26 kristaps 133: recommended;
1.8 kristaps 134: .Xr man 7
135: should only be used for legacy manuals.
1.32 kristaps 136: .
1.11 kristaps 137: .Pp
1.12 kristaps 138: A third option,
139: .Fl m Ns Ar andoc ,
1.13 kristaps 140: which is also the default, determines encoding on-the-fly: if the first
1.26 kristaps 141: non-comment macro is
1.27 kristaps 142: .Sq \&Dd
1.13 kristaps 143: or
1.27 kristaps 144: .Sq \&Dt ,
1.26 kristaps 145: the
1.13 kristaps 146: .Xr mdoc 7
147: parser is used; otherwise, the
148: .Xr man 7
149: parser is used.
1.32 kristaps 150: .
1.13 kristaps 151: .Pp
152: If multiple
1.26 kristaps 153: files are specified with
154: .Fl m Ns Ar andoc ,
1.57 ! kristaps 155: each has its file-type determined this way.
! 156: If multiple files are
1.13 kristaps 157: specified and
1.12 kristaps 158: .Fl m Ns Ar doc
159: or
160: .Fl m Ns Ar an
161: is specified, then this format is used exclusively.
1.32 kristaps 162: .
163: .
1.1 kristaps 164: .Ss Output Formats
165: The
166: .Nm
167: utility accepts the following
168: .Fl T
1.48 kristaps 169: arguments (see
170: .Sx OUTPUT ) :
1.32 kristaps 171: .
1.19 kristaps 172: .Bl -tag -width Ds
1.13 kristaps 173: .It Fl T Ns Ar ascii
1.1 kristaps 174: Produce 7-bit ASCII output, backspace-encoded for bold and underline
1.57 ! kristaps 175: styles.
! 176: This is the default.
! 177: See
1.48 kristaps 178: .Sx ASCII Output .
1.32 kristaps 179: .
1.37 kristaps 180: .It Fl T Ns Ar html
1.57 ! kristaps 181: Produce strict HTML-4.01 output, with a sane default style.
! 182: See
1.48 kristaps 183: .Sx HTML Output .
1.37 kristaps 184: .
1.50 kristaps 185: .It Fl T Ns Ar xhtml
1.57 ! kristaps 186: Produce strict XHTML-1.0 output, with a sane default style.
! 187: See
1.50 kristaps 188: .Sx XHTML Output .
189: .
1.13 kristaps 190: .It Fl T Ns Ar tree
1.1 kristaps 191: Produce an indented parse tree.
1.32 kristaps 192: .
1.13 kristaps 193: .It Fl T Ns Ar lint
1.1 kristaps 194: Parse only: produce no output.
1.52 kristaps 195: Implies
196: .Fl W Ns Ar all
197: and
198: .Fl f Ns Ar strict .
1.1 kristaps 199: .El
1.32 kristaps 200: .
1.13 kristaps 201: .Pp
202: If multiple input files are specified, these will be processed by the
203: corresponding filter in-order.
1.32 kristaps 204: .
205: .
1.1 kristaps 206: .Ss Compiler Options
1.35 kristaps 207: Default compiler behaviour may be overridden with the
1.1 kristaps 208: .Fl f
209: flag.
1.32 kristaps 210: .
1.19 kristaps 211: .Bl -tag -width Ds
1.1 kristaps 212: .It Fl f Ns Ar ign-scope
213: When rewinding the scope of a block macro, forces the compiler to ignore
1.57 ! kristaps 214: scope violations.
! 215: This can seriously mangle the resulting tree.
1.8 kristaps 216: .Pq mdoc only
1.32 kristaps 217: .
1.45 kristaps 218: .It Fl f Ns Ar ign-escape
219: Ignore invalid escape sequences.
220: This is the default, but the option can be used to override an earlier
221: .Fl f Ns Ar strict .
222: .
1.21 kristaps 223: .It Fl f Ns Ar no-ign-escape
224: Don't ignore invalid escape sequences.
1.32 kristaps 225: .
1.12 kristaps 226: .It Fl f Ns Ar no-ign-macro
1.21 kristaps 227: Do not ignore unknown macros at the start of input lines.
1.32 kristaps 228: .
1.21 kristaps 229: .It Fl f Ns Ar no-ign-chars
230: Do not ignore disallowed characters.
1.32 kristaps 231: .
1.21 kristaps 232: .It Fl f Ns Ar strict
1.26 kristaps 233: Implies
1.21 kristaps 234: .Fl f Ns Ar no-ign-escape ,
1.26 kristaps 235: .Fl f Ns Ar no-ign-macro
1.21 kristaps 236: and
1.26 kristaps 237: .Fl f Ns Ar no-ign-chars .
1.32 kristaps 238: .
1.28 kristaps 239: .It Fl f Ns Ar ign-errors
1.57 ! kristaps 240: When parsing multiple files, don't halt when one errors out.
! 241: Useful with
1.28 kristaps 242: .Fl T Ns Ar lint
243: over a large set of manuals passed on the command line.
1.1 kristaps 244: .El
1.32 kristaps 245: .
1.48 kristaps 246: .
1.37 kristaps 247: .Ss Output Options
248: For the time being, only
249: .Fl T Ns Ar html
1.52 kristaps 250: and
251: .Fl T Ns Ar xhtml
1.48 kristaps 252: accepts output options:
1.37 kristaps 253: .Bl -tag -width Ds
1.44 kristaps 254: .It Fl O Ns Ar style=style.css
1.37 kristaps 255: The file
256: .Ar style.css
1.57 ! kristaps 257: is used for an external style-sheet.
! 258: This must be a valid absolute or
1.37 kristaps 259: relative URI.
1.44 kristaps 260: .It Fl O Ns Ar includes=fmt
1.40 kristaps 261: The string
262: .Ar fmt ,
1.49 kristaps 263: for example,
1.40 kristaps 264: .Ar ../src/%I.html ,
265: is used as a template for linked header files (usually via the
266: .Sq \&In
1.57 ! kristaps 267: macro).
! 268: Instances of
1.43 kristaps 269: .Sq \&%I
1.57 ! kristaps 270: are replaced with the include filename.
! 271: The default is not to present a
1.40 kristaps 272: hyperlink.
1.44 kristaps 273: .It Fl O Ns Ar man=fmt
1.39 kristaps 274: The string
275: .Ar fmt ,
1.49 kristaps 276: for example,
1.39 kristaps 277: .Ar ../html%S/%N.%S.html ,
278: is used as a template for linked manuals (usually via the
1.37 kristaps 279: .Sq \&Xr
1.57 ! kristaps 280: macro).
! 281: Instances of
1.43 kristaps 282: .Sq \&%N
1.40 kristaps 283: and
284: .Sq %S
285: are replaced with the linked manual's name and section, respectively.
1.57 ! kristaps 286: If no section is included, section 1 is assumed.
! 287: The default is not to
1.40 kristaps 288: present a hyperlink.
1.37 kristaps 289: .El
1.32 kristaps 290: .
1.48 kristaps 291: .
292: .Sh OUTPUT
293: This section documents output details of
294: .Nm .
295: In general, output conforms to the traditional manual style of a header,
1.49 kristaps 296: a body composed of sections and sub-sections, and a footer.
1.48 kristaps 297: .Pp
298: The text style of output characters (non-macro characters, punctuation,
299: and white-space) is dictated by context.
300: .Pp
1.57 ! kristaps 301: White-space is generally stripped from input.
! 302: This can be changed with
1.48 kristaps 303: character escapes (specified in
304: .Xr mandoc_char 7 )
305: or literal modes (specified in
306: .Xr mdoc 7
307: and
308: .Xr man 7 ) .
309: .Pp
310: If non-macro punctuation is set apart from words, such as in the phrase
311: .Dq to be \&, or not to be ,
312: it's processed by
313: .Nm ,
314: regardless of output format, according to the following rules: opening
315: punctuation
316: .Po
317: .Sq \&( ,
318: .Sq \&[ ,
319: and
320: .Sq \&{
321: .Pc
322: is not followed by a space; closing punctuation
323: .Po
324: .Sq \&. ,
325: .Sq \&, ,
326: .Sq \&; ,
327: .Sq \&: ,
328: .Sq \&? ,
329: .Sq \&! ,
330: .Sq \&) ,
331: .Sq \&]
332: and
333: .Sq \&}
334: .Pc
335: is not preceded by white-space.
336: .
337: .Pp
338: If the input is
339: .Xr mdoc 7 ,
340: however, these rules are also applied to macro arguments when appropriate.
341: .
342: .
343: .Ss ASCII Output
1.49 kristaps 344: Output produced by
1.48 kristaps 345: .Fl T Ns Ar ascii ,
346: which is the default, is rendered in standard 7-bit ASCII documented in
347: .Xr ascii 7 .
348: .Pp
349: Font styles are applied by using back-spaced encoding such that an
350: underlined character
351: .Sq c
352: is rendered as
353: .Sq _ Ns \e[bs] Ns c ,
354: where
355: .Sq \e[bs]
1.57 ! kristaps 356: is the back-space character number 8.
! 357: Emboldened characters are rendered as
1.48 kristaps 358: .Sq c Ns \e[bs] Ns c .
359: .Pp
360: The special characters documented in
361: .Xr mandoc_char 7
362: are rendered best-effort in an ASCII equivalent.
363: .Pp
364: Output width is limited to 78 visible columns unless literal input lines
365: exceed this limit.
366: .
367: .
368: .Ss HTML Output
369: Output produced by
370: .Fl T Ns Ar html
1.50 kristaps 371: conforms to HTML-4.01 strict.
1.48 kristaps 372: .Pp
1.57 ! kristaps 373: Font styles and page structure are applied using CSS2.
! 374: By default, no font style is applied to any text,
! 375: although CSS2 is hard-coded to format
1.48 kristaps 376: the basic structure of output.
377: .Pp
378: The
379: .Pa example.style.css
380: file documents the range of styles applied to output and, if used, will
381: cause rendered documents to appear as they do in
382: .Fl T Ns Ar ascii .
383: .Pp
384: Special characters are rendered in decimal-encoded UTF-8.
385: .
386: .
1.50 kristaps 387: .Ss XHTML Output
388: Output produced by
389: .Fl T Ns Ar xhtml
390: conforms to XHTML-1.0 strict.
391: .Pp
392: See
393: .Sx HTML Output
394: for details; beyond generating XHTML tags instead of HTML tags, these
395: output modes are identical.
396: .
397: .
1.1 kristaps 398: .Sh EXAMPLES
1.13 kristaps 399: To page manuals to the terminal:
1.32 kristaps 400: .
1.1 kristaps 401: .Pp
1.57 ! kristaps 402: .D1 % mandoc \-Wall,error \-fstrict mandoc.1 2\*(Gt&1 | less
1.13 kristaps 403: .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
1.32 kristaps 404: .
1.28 kristaps 405: .Pp
1.41 kristaps 406: To produce HTML manuals with
407: .Ar style.css
408: as the style-sheet:
1.38 kristaps 409: .Pp
1.57 ! kristaps 410: .D1 % mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
1.38 kristaps 411: .Pp
1.28 kristaps 412: To check over a large set of manuals:
1.32 kristaps 413: .
1.28 kristaps 414: .Pp
415: .Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
1.32 kristaps 416: .
417: .
1.20 kristaps 418: .Sh COMPATIBILITY
1.26 kristaps 419: This section summarises
1.20 kristaps 420: .Nm
1.26 kristaps 421: compatibility with
1.20 kristaps 422: .Xr groff 1 .
1.32 kristaps 423: Each input and output format is separately noted.
424: .
425: .
1.48 kristaps 426: .Ss ASCII Compatibility
1.37 kristaps 427: .Bl -bullet -compact
1.29 kristaps 428: .It
1.49 kristaps 429: The
1.29 kristaps 430: .Sq \e~
1.49 kristaps 431: special character doesn't produce expected behaviour in
1.32 kristaps 432: .Fl T Ns Ar ascii .
433: .
434: .It
1.49 kristaps 435: The
1.33 kristaps 436: .Sq \&Bd \-literal
1.49 kristaps 437: and
1.32 kristaps 438: .Sq \&Bd \-unfilled
439: macros of
440: .Xr mdoc 7
441: in
442: .Fl T Ns Ar ascii
443: are synonyms, as are \-filled and \-ragged.
444: .
1.26 kristaps 445: .It
1.49 kristaps 446: In
1.27 kristaps 447: .Xr groff 1 ,
448: the
449: .Sq \&Pa
1.32 kristaps 450: .Xr mdoc 7
451: macro does not underline when scoped under an
1.30 kristaps 452: .Sq \&It
1.57 ! kristaps 453: in the FILES section.
! 454: This behaves correctly in
1.27 kristaps 455: .Nm .
1.32 kristaps 456: .
1.27 kristaps 457: .It
1.20 kristaps 458: A list or display following
1.27 kristaps 459: .Sq \&Ss
1.32 kristaps 460: .Xr mdoc 7
461: macro in
462: .Fl T Ns Ar ascii
1.20 kristaps 463: does not assert a prior vertical break, just as it doesn't with
1.27 kristaps 464: .Sq \&Sh .
1.32 kristaps 465: .
1.20 kristaps 466: .It
1.32 kristaps 467: The
468: .Sq \&na
469: .Xr man 7
1.34 kristaps 470: macro in
1.32 kristaps 471: .Fl T Ns Ar ascii
1.34 kristaps 472: has no effect.
1.32 kristaps 473: .
1.20 kristaps 474: .It
475: Words aren't hyphenated.
1.32 kristaps 476: .
1.22 kristaps 477: .It
478: In normal mode (not a literal block), blocks of spaces aren't preserved,
1.32 kristaps 479: so double spaces following sentence closure are reduced to a single space;
480: .Xr groff 1
481: retains spaces.
482: .
483: .It
484: Sentences are unilaterally monospaced.
1.20 kristaps 485: .El
1.42 kristaps 486: .
1.48 kristaps 487: .
1.50 kristaps 488: .Ss HTML/XHTML Compatibility
1.42 kristaps 489: .Bl -bullet -compact
490: .It
491: The
1.47 kristaps 492: .Sq \efP
493: escape will revert the font to the previous
494: .Sq \ef
495: escape, not to the last rendered decoration, which is now dictated by
1.57 ! kristaps 496: CSS instead of hard-coded.
! 497: It also will not span past the current scope,
! 498: for the same reason.
! 499: Note that in
1.47 kristaps 500: .Sx ASCII Output
501: mode, this will work fine.
502: .It
503: The
1.42 kristaps 504: .Xr mdoc 7
505: .Sq \&Bl \-hang
506: and
507: .Sq \&Bl \-tag
508: list types render similarly (no break following overreached left-hand
509: side) due to the expressive constraints of HTML.
510: .
511: .It
512: The
513: .Xr man 7
514: .Sq IP
515: and
516: .Sq TP
517: lists render similarly.
518: .El
1.48 kristaps 519: .
520: .
1.1 kristaps 521: .Sh SEE ALSO
1.57 ! kristaps 522: .Xr man 7 ,
1.13 kristaps 523: .Xr mandoc_char 7 ,
1.57 ! kristaps 524: .Xr mdoc 7
1.39 kristaps 525: .
1.1 kristaps 526: .Sh AUTHORS
527: The
528: .Nm
1.26 kristaps 529: utility was written by
1.18 kristaps 530: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.39 kristaps 531: .
1.48 kristaps 532: .
1.39 kristaps 533: .Sh CAVEATS
1.48 kristaps 534: The
535: .Fl T Ns Ar html
1.50 kristaps 536: and
537: .Fl T Ns Ar xhtml
1.48 kristaps 538: CSS2 styling used for
539: .Fl m Ns Ar doc
1.51 kristaps 540: input lists does not render properly in older browsers, such as Internet
541: Explorer 6 and earlier.
1.54 kristaps 542: .
1.48 kristaps 543: .Pp
1.39 kristaps 544: In
1.50 kristaps 545: .Fl T Ns Ar html
546: and
547: .Fl T Ns Ar xhtml ,
1.39 kristaps 548: the maximum size of an element attribute is determined by
549: .Dv BUFSIZ ,
1.57 ! kristaps 550: which is usually 1024 bytes.
! 551: Be aware of this when setting long link
1.48 kristaps 552: formats, e.g.,
553: .Fl O Ns Ar style=really/long/link .
1.54 kristaps 554: .
1.46 kristaps 555: .Pp
556: The
557: .Fl T Ns Ar html
1.50 kristaps 558: and
559: .Fl T Ns Ar xhtml
560: output modes don't render the
1.46 kristaps 561: .Sq \es
1.47 kristaps 562: font size escape documented in
1.46 kristaps 563: .Xr mdoc 7
564: and
565: .Xr man 7 .
1.54 kristaps 566: .
1.51 kristaps 567: .Pp
568: Nesting elements within next-line element scopes of
1.52 kristaps 569: .Fl m Ns Ar an ,
1.51 kristaps 570: such as
571: .Sq br
572: within an empty
573: .Sq B ,
574: will confuse
575: .Fl T Ns Ar html
576: and
577: .Fl T Ns Ar xhtml
1.52 kristaps 578: and cause them to forget the formatting of the prior next-line scope.
1.54 kristaps 579: .
1.53 kristaps 580: .Pp
581: The
582: .Sq i
583: macro in
584: .Fl m Ns Ar an
585: should italicise all subsequent text if a line argument is not provided.
586: This behaviour is not implemented.
1.54 kristaps 587: .
588: The
589: .Sq \(aq
1.55 kristaps 590: control character is an alias for the standard macro control character
591: and does not emit a line-break as stipulated in GNU troff.
CVSweb