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