Annotation of mandoc/mandoc.1, Revision 1.23
1.23 ! kristaps 1: .\" $Id: mandoc.1,v 1.22 2009/06/22 12:04:05 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.8 kristaps 37: utility formats
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...
43: Override default compiler behaviour. See
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...
63: Print warning messages. May be set to
64: .Fl W Ns Ar all
65: for all warnings,
66: .Ar compat
67: for groff/troff-compatibility warnings, or
68: .Ar syntax
69: for syntax warnings. If
70: .Fl W Ns Ar error
71: is specified, warnings are considered errors and cause utility
72: termination. Multiple
73: .Fl W
74: arguments may be comma-separated, such as
75: .Fl W Ns Ar error,all .
76: .\" ITEM
77: .It Ar infile...
78: Read input from zero or more
79: .Ar infile .
1.2 kristaps 80: If unspecified, reads from stdin. If multiple files are specified,
81: .Nm
82: will halt with the first failed parse.
1.1 kristaps 83: .El
84: .\" PARAGRAPH
85: .Pp
86: By default,
87: .Nm
1.8 kristaps 88: reads
89: .Xr mdoc 7
1.12 kristaps 90: or
91: .Xr man 7
1.8 kristaps 92: text from stdin, implying
1.12 kristaps 93: .Fl m Ns Ar andoc ,
1.8 kristaps 94: and prints 78-column backspace-encoded output to stdout as if
1.1 kristaps 95: .Fl T Ns Ar ascii
96: were provided.
97: .\" PARAGRAPH
98: .Pp
99: .Ex -std mandoc
100: .\" SUB-SECTION
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
108: .Sq \&( ,
109: .Sq \&[ ,
110: and
111: .Sq \&{
1.13 kristaps 112: .Pc
1.22 kristaps 113: is not followed by a space; closing punctuation
1.4 kristaps 114: .Po
115: .Sq \&. ,
116: .Sq \&, ,
117: .Sq \&; ,
118: .Sq \&: ,
119: .Sq \&? ,
120: .Sq \&! ,
121: .Sq \&) ,
122: .Sq \&]
123: and
124: .Sq \&}
1.13 kristaps 125: .Pc
1.15 kristaps 126: is not preceded by whitespace.
1.4 kristaps 127: .Pp
1.13 kristaps 128: If the input is
129: .Xr mdoc 7 ,
130: these rules are also applied to macro arguments when appropriate.
1.22 kristaps 131: .Pp
132: White-space, in non-literal (normal) mode, is stripped from input and
133: replaced on output by a single space. Thus, if you wish to preserve
134: multiple spaces, they must be space-escaped
1.23 ! kristaps 135: .Sq \e\
1.22 kristaps 136: or used in a literal display mode, e.g.,
137: .Sq \&.Bd \-literal
138: in
139: .Xr mdoc 7 .
1.4 kristaps 140: .\" SUB-SECTION
1.8 kristaps 141: .Ss Input Formats
142: The
143: .Nm
144: utility accepts
145: .Xr mdoc 7
146: and
147: .Xr man 7
148: input with
1.10 kristaps 149: .Fl m Ns Ar doc
1.8 kristaps 150: and
1.10 kristaps 151: .Fl m Ns Ar an ,
1.8 kristaps 152: respectively. The
153: .Xr mdoc 7
154: format is
155: .Em strongly
156: recommended;
157: .Xr man 7
158: should only be used for legacy manuals.
1.11 kristaps 159: .Pp
1.12 kristaps 160: A third option,
161: .Fl m Ns Ar andoc ,
1.13 kristaps 162: which is also the default, determines encoding on-the-fly: if the first
163: non-comment macro is
164: .Sq \&.Dd
165: or
166: .Sq \&.Dt ,
167: the
168: .Xr mdoc 7
169: parser is used; otherwise, the
170: .Xr man 7
171: parser is used.
172: .Pp
173: If multiple
174: files are specified with
175: .Fl m Ns Ar andoc ,
176: each has its file-type determined this way. If multiple files are
177: specified and
1.12 kristaps 178: .Fl m Ns Ar doc
179: or
180: .Fl m Ns Ar an
181: is specified, then this format is used exclusively.
1.13 kristaps 182: .\" .Pp
183: .\" The following escape sequences are recognised, although the per-format
184: .\" compiler may not allow certain sequences.
185: .\" .Bl -tag -width Ds -offset XXXX
186: .\" .It \efX
187: .\" sets the font mode to X (B, I, R or P, where P resets the font)
188: .\" .It \eX, \e(XX, \e[XN]
189: .\" queries the special-character table for a corresponding symbol
190: .\" .It \e*X, \e*(XX, \e*[XN]
191: .\" deprecated special-character format
192: .\" .El
1.8 kristaps 193: .\" SUB-SECTION
1.1 kristaps 194: .Ss Output Formats
195: The
196: .Nm
197: utility accepts the following
198: .Fl T
199: arguments:
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.13 kristaps 204: .It Fl T Ns Ar tree
1.1 kristaps 205: Produce an indented parse tree.
1.13 kristaps 206: .It Fl T Ns Ar lint
1.1 kristaps 207: Parse only: produce no output.
208: .El
1.13 kristaps 209: .Pp
210: If multiple input files are specified, these will be processed by the
211: corresponding filter in-order.
1.1 kristaps 212: .\" SUB-SECTION
213: .Ss Compiler Options
214: Default compiler behaviour may be overriden with the
215: .Fl f
216: flag.
1.19 kristaps 217: .Bl -tag -width Ds
1.1 kristaps 218: .It Fl f Ns Ar ign-scope
219: When rewinding the scope of a block macro, forces the compiler to ignore
220: scope violations. This can seriously mangle the resulting tree.
1.8 kristaps 221: .Pq mdoc only
1.21 kristaps 222: .It Fl f Ns Ar no-ign-escape
223: Don't ignore invalid escape sequences.
1.12 kristaps 224: .It Fl f Ns Ar no-ign-macro
1.21 kristaps 225: Do not ignore unknown macros at the start of input lines.
226: .It Fl f Ns Ar no-ign-chars
227: Do not ignore disallowed characters.
228: .It Fl f Ns Ar strict
229: Implies
230: .Fl f Ns Ar no-ign-escape ,
231: .Fl f Ns Ar no-ign-macro
232: and
233: .Fl f Ns Ar no-ign-chars .
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.1 kristaps 252: .\" SECTION
1.20 kristaps 253: .Sh COMPATIBILITY
254: This section summarises
255: .Nm
256: compatibility with
257: .Xr groff 1 .
258: .Pp
259: .Bl -bullet -compact
260: .It
261: A list or display following
262: .Sq \&.Ss
263: does not assert a prior vertical break, just as it doesn't with
264: .Sq \&.Sh .
265: .It
266: The \-literal and \-unfilled
267: .Sq \&.Bd
268: displays types are synonyms, as are \-filled and \-ragged.
269: .It
270: Words aren't hyphenated.
1.22 kristaps 271: .It
272: In normal mode (not a literal block), blocks of spaces aren't preserved,
1.23 ! kristaps 273: so double spaces following sentence closure are reduced to a single space
! 274: .Pq Dq French spacing .
1.20 kristaps 275: .El
276: .\" SECTION
1.1 kristaps 277: .Sh SEE ALSO
1.13 kristaps 278: .Xr mandoc_char 7 ,
1.9 kristaps 279: .Xr mdoc 7 ,
280: .Xr man 7
1.20 kristaps 281: .\" SECTION
1.1 kristaps 282: .Sh AUTHORS
283: The
284: .Nm
285: utility was written by
1.18 kristaps 286: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.1 kristaps 287: .\" SECTION
288: .Sh CAVEATS
289: The
290: .Nm
1.20 kristaps 291: utility doesn't yet know how to display \-hang lists.
1.7 kristaps 292: .Pp
293: Other macros still aren't supported by virtue of nobody complaining
1.20 kristaps 294: about their absence.
CVSweb