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