Annotation of mandoc/mandoc.1, Revision 1.46
1.46 ! kristaps 1: .\" $Id: mandoc.1,v 1.45 2009/10/26 15:44:51 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: .\"
17: .Dd $Mdocdate$
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.8 kristaps 99: and prints 78-column backspace-encoded output to stdout as if
1.1 kristaps 100: .Fl T Ns Ar ascii
101: were provided.
1.32 kristaps 102: .
1.1 kristaps 103: .Pp
104: .Ex -std mandoc
1.32 kristaps 105: .
106: .
1.22 kristaps 107: .Ss Punctuation and Spacing
1.13 kristaps 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
1.22 kristaps 112: according to the following rules: opening punctuation
1.4 kristaps 113: .Po
1.26 kristaps 114: .Sq \&( ,
115: .Sq \&[ ,
1.4 kristaps 116: and
117: .Sq \&{
1.26 kristaps 118: .Pc
1.22 kristaps 119: is not followed by a space; closing punctuation
1.4 kristaps 120: .Po
1.26 kristaps 121: .Sq \&. ,
122: .Sq \&, ,
123: .Sq \&; ,
124: .Sq \&: ,
125: .Sq \&? ,
126: .Sq \&! ,
127: .Sq \&) ,
128: .Sq \&]
1.4 kristaps 129: and
130: .Sq \&}
1.26 kristaps 131: .Pc
1.15 kristaps 132: is not preceded by whitespace.
1.32 kristaps 133: .
1.4 kristaps 134: .Pp
1.13 kristaps 135: If the input is
136: .Xr mdoc 7 ,
137: these rules are also applied to macro arguments when appropriate.
1.32 kristaps 138: .
1.22 kristaps 139: .Pp
140: White-space, in non-literal (normal) mode, is stripped from input and
1.33 kristaps 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.,
1.27 kristaps 143: .Sq \&Bd \-literal
1.26 kristaps 144: in
1.22 kristaps 145: .Xr mdoc 7 .
1.32 kristaps 146: .
147: .
1.8 kristaps 148: .Ss Input Formats
149: The
150: .Nm
151: utility accepts
152: .Xr mdoc 7
153: and
154: .Xr man 7
155: input with
1.10 kristaps 156: .Fl m Ns Ar doc
1.8 kristaps 157: and
1.10 kristaps 158: .Fl m Ns Ar an ,
1.8 kristaps 159: respectively. The
160: .Xr mdoc 7
161: format is
162: .Em strongly
1.26 kristaps 163: recommended;
1.8 kristaps 164: .Xr man 7
165: should only be used for legacy manuals.
1.32 kristaps 166: .
1.11 kristaps 167: .Pp
1.12 kristaps 168: A third option,
169: .Fl m Ns Ar andoc ,
1.13 kristaps 170: which is also the default, determines encoding on-the-fly: if the first
1.26 kristaps 171: non-comment macro is
1.27 kristaps 172: .Sq \&Dd
1.13 kristaps 173: or
1.27 kristaps 174: .Sq \&Dt ,
1.26 kristaps 175: the
1.13 kristaps 176: .Xr mdoc 7
177: parser is used; otherwise, the
178: .Xr man 7
179: parser is used.
1.32 kristaps 180: .
1.13 kristaps 181: .Pp
182: If multiple
1.26 kristaps 183: files are specified with
184: .Fl m Ns Ar andoc ,
1.13 kristaps 185: each has its file-type determined this way. If multiple files are
186: specified and
1.12 kristaps 187: .Fl m Ns Ar doc
188: or
189: .Fl m Ns Ar an
190: is specified, then this format is used exclusively.
1.32 kristaps 191: .
192: .
1.1 kristaps 193: .Ss Output Formats
194: The
195: .Nm
196: utility accepts the following
197: .Fl T
198: arguments:
1.32 kristaps 199: .
1.19 kristaps 200: .Bl -tag -width Ds
1.13 kristaps 201: .It Fl T Ns Ar ascii
1.1 kristaps 202: Produce 7-bit ASCII output, backspace-encoded for bold and underline
203: styles. This is the default.
1.32 kristaps 204: .
1.37 kristaps 205: .It Fl T Ns Ar html
206: Produce strict HTML-4.01 output, with a sane default style.
207: .
1.13 kristaps 208: .It Fl T Ns Ar tree
1.1 kristaps 209: Produce an indented parse tree.
1.32 kristaps 210: .
1.13 kristaps 211: .It Fl T Ns Ar lint
1.1 kristaps 212: Parse only: produce no output.
213: .El
1.32 kristaps 214: .
1.13 kristaps 215: .Pp
216: If multiple input files are specified, these will be processed by the
217: corresponding filter in-order.
1.32 kristaps 218: .
219: .
1.1 kristaps 220: .Ss Compiler Options
1.35 kristaps 221: Default compiler behaviour may be overridden with the
1.1 kristaps 222: .Fl f
223: flag.
1.32 kristaps 224: .
1.19 kristaps 225: .Bl -tag -width Ds
1.1 kristaps 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.
1.8 kristaps 229: .Pq mdoc only
1.32 kristaps 230: .
1.45 kristaps 231: .It Fl f Ns Ar ign-escape
232: Ignore invalid escape sequences.
233: This is the default, but the option can be used to override an earlier
234: .Fl f Ns Ar strict .
235: .
1.21 kristaps 236: .It Fl f Ns Ar no-ign-escape
237: Don't ignore invalid escape sequences.
1.32 kristaps 238: .
1.12 kristaps 239: .It Fl f Ns Ar no-ign-macro
1.21 kristaps 240: Do not ignore unknown macros at the start of input lines.
1.32 kristaps 241: .
1.21 kristaps 242: .It Fl f Ns Ar no-ign-chars
243: Do not ignore disallowed characters.
1.32 kristaps 244: .
1.21 kristaps 245: .It Fl f Ns Ar strict
1.26 kristaps 246: Implies
1.21 kristaps 247: .Fl f Ns Ar no-ign-escape ,
1.26 kristaps 248: .Fl f Ns Ar no-ign-macro
1.21 kristaps 249: and
1.26 kristaps 250: .Fl f Ns Ar no-ign-chars .
1.32 kristaps 251: .
1.28 kristaps 252: .It Fl f Ns Ar ign-errors
253: Don't halt when encountering parse errors. Useful with
254: .Fl T Ns Ar lint
255: over a large set of manuals passed on the command line.
1.1 kristaps 256: .El
1.32 kristaps 257: .
1.37 kristaps 258: .Ss Output Options
259: For the time being, only
260: .Fl T Ns Ar html
261: is the only mode with output options:
262: .Bl -tag -width Ds
1.44 kristaps 263: .It Fl O Ns Ar style=style.css
1.37 kristaps 264: The file
265: .Ar style.css
266: is used for an external style-sheet. This must be a valid absolute or
267: relative URI.
1.44 kristaps 268: .It Fl O Ns Ar includes=fmt
1.40 kristaps 269: The string
270: .Ar fmt ,
271: for example,
272: .Ar ../src/%I.html ,
273: is used as a template for linked header files (usually via the
274: .Sq \&In
275: macro). Instances of
1.43 kristaps 276: .Sq \&%I
1.40 kristaps 277: are replaced with the include filename. The default is not to present a
278: hyperlink.
1.44 kristaps 279: .It Fl O Ns Ar man=fmt
1.39 kristaps 280: The string
281: .Ar fmt ,
282: for example,
283: .Ar ../html%S/%N.%S.html ,
284: is used as a template for linked manuals (usually via the
1.37 kristaps 285: .Sq \&Xr
1.40 kristaps 286: macro). Instances of
1.43 kristaps 287: .Sq \&%N
1.40 kristaps 288: and
289: .Sq %S
290: are replaced with the linked manual's name and section, respectively.
291: If no section is included, section 1 is assumed. The default is not to
292: present a hyperlink.
1.37 kristaps 293: .El
1.32 kristaps 294: .
1.1 kristaps 295: .Sh EXAMPLES
1.13 kristaps 296: To page manuals to the terminal:
1.32 kristaps 297: .
1.1 kristaps 298: .Pp
1.21 kristaps 299: .D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
1.13 kristaps 300: .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
1.32 kristaps 301: .
1.28 kristaps 302: .Pp
1.41 kristaps 303: To produce HTML manuals with
304: .Ar style.css
305: as the style-sheet:
1.38 kristaps 306: .Pp
1.41 kristaps 307: .D1 % mandoc \-Thtml -ostyle=style.css mdoc.7 > mdoc.7.html
1.38 kristaps 308: .Pp
1.28 kristaps 309: To check over a large set of manuals:
1.32 kristaps 310: .
1.28 kristaps 311: .Pp
312: .Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
1.32 kristaps 313: .
314: .
1.20 kristaps 315: .Sh COMPATIBILITY
1.26 kristaps 316: This section summarises
1.20 kristaps 317: .Nm
1.26 kristaps 318: compatibility with
1.20 kristaps 319: .Xr groff 1 .
1.32 kristaps 320: Each input and output format is separately noted.
321: .
322: .
323: .Ss ASCII output
1.37 kristaps 324: .Bl -bullet -compact
1.29 kristaps 325: .It
326: The
327: .Sq \e~
1.32 kristaps 328: special character doesn't produce expected behaviour in
329: .Fl T Ns Ar ascii .
330: .
331: .It
332: The
1.33 kristaps 333: .Sq \&Bd \-literal
1.32 kristaps 334: and
335: .Sq \&Bd \-unfilled
336: macros of
337: .Xr mdoc 7
338: in
339: .Fl T Ns Ar ascii
340: are synonyms, as are \-filled and \-ragged.
341: .
1.26 kristaps 342: .It
1.27 kristaps 343: In
344: .Xr groff 1 ,
345: the
346: .Sq \&Pa
1.32 kristaps 347: .Xr mdoc 7
348: macro does not underline when scoped under an
1.30 kristaps 349: .Sq \&It
350: in the FILES section. This behaves correctly in
1.27 kristaps 351: .Nm .
1.32 kristaps 352: .
1.27 kristaps 353: .It
1.20 kristaps 354: A list or display following
1.27 kristaps 355: .Sq \&Ss
1.32 kristaps 356: .Xr mdoc 7
357: macro in
358: .Fl T Ns Ar ascii
1.20 kristaps 359: does not assert a prior vertical break, just as it doesn't with
1.27 kristaps 360: .Sq \&Sh .
1.32 kristaps 361: .
1.20 kristaps 362: .It
1.32 kristaps 363: The
364: .Sq \&na
365: .Xr man 7
1.34 kristaps 366: macro in
1.32 kristaps 367: .Fl T Ns Ar ascii
1.34 kristaps 368: has no effect.
1.32 kristaps 369: .
1.20 kristaps 370: .It
371: Words aren't hyphenated.
1.32 kristaps 372: .
1.22 kristaps 373: .It
374: In normal mode (not a literal block), blocks of spaces aren't preserved,
1.32 kristaps 375: so double spaces following sentence closure are reduced to a single space;
376: .Xr groff 1
377: retains spaces.
378: .
379: .It
380: Sentences are unilaterally monospaced.
1.20 kristaps 381: .El
1.42 kristaps 382: .
383: .Ss HTML output
384: .Bl -bullet -compact
385: .It
386: The
387: .Xr mdoc 7
388: .Sq \&Bl \-hang
389: and
390: .Sq \&Bl \-tag
391: list types render similarly (no break following overreached left-hand
392: side) due to the expressive constraints of HTML.
393: .
394: .It
395: The
396: .Xr man 7
397: .Sq IP
398: and
399: .Sq TP
400: lists render similarly.
401: .El
1.20 kristaps 402: .\" SECTION
1.1 kristaps 403: .Sh SEE ALSO
1.13 kristaps 404: .Xr mandoc_char 7 ,
1.9 kristaps 405: .Xr mdoc 7 ,
406: .Xr man 7
1.39 kristaps 407: .
1.1 kristaps 408: .Sh AUTHORS
409: The
410: .Nm
1.26 kristaps 411: utility was written by
1.18 kristaps 412: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.39 kristaps 413: .
414: .Sh CAVEATS
415: In
416: .Fl T Ns Ar html ,
417: the maximum size of an element attribute is determined by
418: .Dv BUFSIZ ,
419: which is usually 1024 bytes. Be aware of this when setting long link
420: formats with
1.44 kristaps 421: .Fl O Ns Ar man=fmt .
1.46 ! kristaps 422: .Pp
! 423: The
! 424: .Fl T Ns Ar html
! 425: utility doesn't support the
! 426: .Sq \ef
! 427: and
! 428: .Sq \es
! 429: text decorations documented in
! 430: .Xr mdoc 7
! 431: and
! 432: .Xr man 7 .
CVSweb