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