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