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