Annotation of mandoc/mandoc.1, Revision 1.32
1.32 ! kristaps 1: .\" $Id: mandoc.1,v 1.31 2009/08/20 11:51:07 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 V
30: .Op Fl f Ns Ar option...
1.8 kristaps 31: .Op Fl m Ns Ar format
1.1 kristaps 32: .Op Fl W Ns Ar err...
33: .Op Fl T Ns Ar output
34: .Op Ar infile...
1.32 ! kristaps 35: .
! 36: .
1.1 kristaps 37: .Sh DESCRIPTION
38: The
39: .Nm
1.26 kristaps 40: utility formats
1.8 kristaps 41: .Ux
42: manual pages for display. The arguments are as follows:
1.32 ! kristaps 43: .
1.19 kristaps 44: .Bl -tag -width Ds
1.1 kristaps 45: .It Fl f Ns Ar option...
1.26 kristaps 46: Override default compiler behaviour. See
1.1 kristaps 47: .Sx Compiler Options
48: for details.
1.32 ! kristaps 49: .
1.19 kristaps 50: .It Fl m Ns Ar format
1.8 kristaps 51: Input format. See
52: .Sx Input Formats
53: for available formats. Defaults to
1.12 kristaps 54: .Fl m Ns Ar andoc .
1.32 ! kristaps 55: .
1.19 kristaps 56: .It Fl T Ns Ar output
1.1 kristaps 57: Output format. See
58: .Sx Output Formats
59: for available formats. Defaults to
60: .Fl T Ns Ar ascii .
1.32 ! kristaps 61: .
1.1 kristaps 62: .It Fl V
63: Print version and exit.
1.32 ! kristaps 64: .
1.1 kristaps 65: .It Fl W Ns Ar err...
1.24 kristaps 66: Configure warning messages. Use
1.1 kristaps 67: .Fl W Ns Ar all
1.24 kristaps 68: to print warnings,
1.26 kristaps 69: .Fl W Ns Ar error
1.24 kristaps 70: for warnings to be considered errors and cause utility
1.26 kristaps 71: termination. Multiple
1.1 kristaps 72: .Fl W
73: arguments may be comma-separated, such as
74: .Fl W Ns Ar error,all .
1.32 ! kristaps 75: .
1.1 kristaps 76: .It Ar infile...
77: Read input from zero or more
78: .Ar infile .
1.2 kristaps 79: If unspecified, reads from stdin. If multiple files are specified,
80: .Nm
81: will halt with the first failed parse.
1.1 kristaps 82: .El
1.32 ! kristaps 83: .
1.1 kristaps 84: .Pp
1.26 kristaps 85: By default,
86: .Nm
87: reads
1.8 kristaps 88: .Xr mdoc 7
1.12 kristaps 89: or
90: .Xr man 7
1.8 kristaps 91: text from stdin, implying
1.12 kristaps 92: .Fl m Ns Ar andoc ,
1.8 kristaps 93: and prints 78-column backspace-encoded output to stdout as if
1.1 kristaps 94: .Fl T Ns Ar ascii
95: were provided.
1.32 ! kristaps 96: .
1.1 kristaps 97: .Pp
98: .Ex -std mandoc
1.32 ! kristaps 99: .
! 100: .
1.22 kristaps 101: .Ss Punctuation and Spacing
1.13 kristaps 102: If punctuation is set apart from words, such as in the phrase
103: .Dq to be \&, or not to be ,
104: it's processed by
105: .Nm
1.22 kristaps 106: according to the following rules: opening punctuation
1.4 kristaps 107: .Po
1.26 kristaps 108: .Sq \&( ,
109: .Sq \&[ ,
1.4 kristaps 110: and
111: .Sq \&{
1.26 kristaps 112: .Pc
1.22 kristaps 113: is not followed by a space; closing punctuation
1.4 kristaps 114: .Po
1.26 kristaps 115: .Sq \&. ,
116: .Sq \&, ,
117: .Sq \&; ,
118: .Sq \&: ,
119: .Sq \&? ,
120: .Sq \&! ,
121: .Sq \&) ,
122: .Sq \&]
1.4 kristaps 123: and
124: .Sq \&}
1.26 kristaps 125: .Pc
1.15 kristaps 126: is not preceded by whitespace.
1.32 ! kristaps 127: .
1.4 kristaps 128: .Pp
1.13 kristaps 129: If the input is
130: .Xr mdoc 7 ,
131: these rules are also applied to macro arguments when appropriate.
1.32 ! kristaps 132: .
1.22 kristaps 133: .Pp
134: White-space, in non-literal (normal) mode, is stripped from input and
135: replaced on output by a single space. Thus, if you wish to preserve
136: multiple spaces, they must be space-escaped
1.26 kristaps 137: .Sq \e\
138: or used in a literal display mode, e.g.,
1.27 kristaps 139: .Sq \&Bd \-literal
1.26 kristaps 140: in
1.22 kristaps 141: .Xr mdoc 7 .
1.32 ! kristaps 142: .
! 143: .
1.8 kristaps 144: .Ss Input Formats
145: The
146: .Nm
147: utility accepts
148: .Xr mdoc 7
149: and
150: .Xr man 7
151: input with
1.10 kristaps 152: .Fl m Ns Ar doc
1.8 kristaps 153: and
1.10 kristaps 154: .Fl m Ns Ar an ,
1.8 kristaps 155: respectively. The
156: .Xr mdoc 7
157: format is
158: .Em strongly
1.26 kristaps 159: recommended;
1.8 kristaps 160: .Xr man 7
161: should only be used for legacy manuals.
1.32 ! kristaps 162: .
1.11 kristaps 163: .Pp
1.12 kristaps 164: A third option,
165: .Fl m Ns Ar andoc ,
1.13 kristaps 166: which is also the default, determines encoding on-the-fly: if the first
1.26 kristaps 167: non-comment macro is
1.27 kristaps 168: .Sq \&Dd
1.13 kristaps 169: or
1.27 kristaps 170: .Sq \&Dt ,
1.26 kristaps 171: the
1.13 kristaps 172: .Xr mdoc 7
173: parser is used; otherwise, the
174: .Xr man 7
175: parser is used.
1.32 ! kristaps 176: .
1.13 kristaps 177: .Pp
178: If multiple
1.26 kristaps 179: files are specified with
180: .Fl m Ns Ar andoc ,
1.13 kristaps 181: each has its file-type determined this way. If multiple files are
182: specified and
1.12 kristaps 183: .Fl m Ns Ar doc
184: or
185: .Fl m Ns Ar an
186: is specified, then this format is used exclusively.
1.32 ! kristaps 187: .
! 188: .
1.1 kristaps 189: .Ss Output Formats
190: The
191: .Nm
192: utility accepts the following
193: .Fl T
194: arguments:
1.32 ! kristaps 195: .
1.19 kristaps 196: .Bl -tag -width Ds
1.13 kristaps 197: .It Fl T Ns Ar ascii
1.1 kristaps 198: Produce 7-bit ASCII output, backspace-encoded for bold and underline
199: styles. This is the default.
1.32 ! kristaps 200: .
1.13 kristaps 201: .It Fl T Ns Ar tree
1.1 kristaps 202: Produce an indented parse tree.
1.32 ! kristaps 203: .
1.13 kristaps 204: .It Fl T Ns Ar lint
1.1 kristaps 205: Parse only: produce no output.
206: .El
1.32 ! kristaps 207: .
1.13 kristaps 208: .Pp
209: If multiple input files are specified, these will be processed by the
210: corresponding filter in-order.
1.32 ! kristaps 211: .
! 212: .
1.1 kristaps 213: .Ss Compiler Options
214: Default compiler behaviour may be overriden with the
215: .Fl f
216: flag.
1.32 ! kristaps 217: .
1.19 kristaps 218: .Bl -tag -width Ds
1.1 kristaps 219: .It Fl f Ns Ar ign-scope
220: When rewinding the scope of a block macro, forces the compiler to ignore
221: scope violations. This can seriously mangle the resulting tree.
1.8 kristaps 222: .Pq mdoc only
1.32 ! kristaps 223: .
1.21 kristaps 224: .It Fl f Ns Ar no-ign-escape
225: Don't ignore invalid escape sequences.
1.32 ! kristaps 226: .
1.12 kristaps 227: .It Fl f Ns Ar no-ign-macro
1.21 kristaps 228: Do not ignore unknown macros at the start of input lines.
1.32 ! kristaps 229: .
1.21 kristaps 230: .It Fl f Ns Ar no-ign-chars
231: Do not ignore disallowed characters.
1.32 ! kristaps 232: .
1.21 kristaps 233: .It Fl f Ns Ar strict
1.26 kristaps 234: Implies
1.21 kristaps 235: .Fl f Ns Ar no-ign-escape ,
1.26 kristaps 236: .Fl f Ns Ar no-ign-macro
1.21 kristaps 237: and
1.26 kristaps 238: .Fl f Ns Ar no-ign-chars .
1.32 ! kristaps 239: .
1.28 kristaps 240: .It Fl f Ns Ar ign-errors
241: Don't halt when encountering parse errors. Useful with
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.1 kristaps 246: .Pp
247: As with the
248: .Fl W
249: flag, multiple
250: .Fl f
251: options may be grouped and delimited with a comma. Using
1.21 kristaps 252: .Fl f Ns Ar ign-scope,no-ign-escape ,
253: for example, will try to ignore scope and not ignore character-escape
254: errors.
1.32 ! kristaps 255: .
! 256: .
1.1 kristaps 257: .Sh EXAMPLES
1.13 kristaps 258: To page manuals to the terminal:
1.32 ! kristaps 259: .
1.1 kristaps 260: .Pp
1.21 kristaps 261: .D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
1.13 kristaps 262: .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
1.32 ! kristaps 263: .
1.28 kristaps 264: .Pp
265: To check over a large set of manuals:
1.32 ! kristaps 266: .
1.28 kristaps 267: .Pp
268: .Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
1.32 ! kristaps 269: .
! 270: .
1.20 kristaps 271: .Sh COMPATIBILITY
1.26 kristaps 272: This section summarises
1.20 kristaps 273: .Nm
1.26 kristaps 274: compatibility with
1.20 kristaps 275: .Xr groff 1 .
1.32 ! kristaps 276: Each input and output format is separately noted.
! 277: .
! 278: .
! 279: .Ss ASCII output
1.20 kristaps 280: .Bl -bullet -compact
1.29 kristaps 281: .It
282: The
283: .Sq \e~
1.32 ! kristaps 284: special character doesn't produce expected behaviour in
! 285: .Fl T Ns Ar ascii .
! 286: .
! 287: .It
! 288: The
! 289: .Sq \&Bd \-literal
! 290: and
! 291: .Sq \&Bd \-unfilled
! 292: macros of
! 293: .Xr mdoc 7
! 294: in
! 295: .Fl T Ns Ar ascii
! 296: are synonyms, as are \-filled and \-ragged.
! 297: .
1.26 kristaps 298: .It
1.27 kristaps 299: In
300: .Xr groff 1 ,
301: the
302: .Sq \&Pa
1.32 ! kristaps 303: .Xr mdoc 7
! 304: macro does not underline when scoped under an
1.30 kristaps 305: .Sq \&It
306: in the FILES section. This behaves correctly in
1.27 kristaps 307: .Nm .
1.32 ! kristaps 308: .
1.27 kristaps 309: .It
1.20 kristaps 310: A list or display following
1.27 kristaps 311: .Sq \&Ss
1.32 ! kristaps 312: .Xr mdoc 7
! 313: macro in
! 314: .Fl T Ns Ar ascii
1.20 kristaps 315: does not assert a prior vertical break, just as it doesn't with
1.27 kristaps 316: .Sq \&Sh .
1.32 ! kristaps 317: .
1.20 kristaps 318: .It
1.32 ! kristaps 319: The
! 320: .Sq \&na
! 321: and
! 322: .Sq \&Dt
! 323: .Xr man 7
! 324: macros in
! 325: .Fl T Ns Ar ascii
! 326: have no effect.
! 327: .
1.20 kristaps 328: .It
329: Words aren't hyphenated.
1.32 ! kristaps 330: .
1.22 kristaps 331: .It
332: In normal mode (not a literal block), blocks of spaces aren't preserved,
1.32 ! kristaps 333: so double spaces following sentence closure are reduced to a single space;
! 334: .Xr groff 1
! 335: retains spaces.
! 336: .
! 337: .It
! 338: Sentences are unilaterally monospaced.
1.20 kristaps 339: .El
340: .\" SECTION
1.1 kristaps 341: .Sh SEE ALSO
1.13 kristaps 342: .Xr mandoc_char 7 ,
1.9 kristaps 343: .Xr mdoc 7 ,
344: .Xr man 7
1.20 kristaps 345: .\" SECTION
1.1 kristaps 346: .Sh AUTHORS
347: The
348: .Nm
1.26 kristaps 349: utility was written by
1.18 kristaps 350: .An Kristaps Dzonsons Aq kristaps@kth.se .
CVSweb