Annotation of mandoc/mandoc.1, Revision 1.14
1.14 ! kristaps 1: .\" $Id: mandoc.1,v 1.13 2009/04/05 16:34:22 kristaps Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the
7: .\" above copyright notice and this permission notice appear in all
8: .\" copies.
9: .\"
10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
11: .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
12: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
13: .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
14: .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
15: .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
16: .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17: .\" PERFORMANCE OF THIS SOFTWARE.
18: .\"
19: .Dd $Mdocdate$
1.14 ! kristaps 20: .Dt MANDOC 1
1.1 kristaps 21: .Os
22: .\" SECTION
23: .Sh NAME
24: .Nm mandoc
1.8 kristaps 25: .Nd format and display UNIX manuals
1.1 kristaps 26: .\" SECTION
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...
35: .\" SECTION
36: .Sh DESCRIPTION
37: The
38: .Nm
1.8 kristaps 39: utility formats
40: .Ux
41: manual pages for display. The arguments are as follows:
1.1 kristaps 42: .Bl -tag -width XXXXXXXXXXXX
43: .\" ITEM
44: .It Fl f Ns Ar option...
45: Override default compiler behaviour. See
46: .Sx Compiler Options
47: for details.
48: .\" ITEM
1.8 kristaps 49: .It Fl m
50: Input format. See
51: .Sx Input Formats
52: for available formats. Defaults to
1.12 kristaps 53: .Fl m Ns Ar andoc .
1.8 kristaps 54: .\" ITEM
1.1 kristaps 55: .It Fl T
56: Output format. See
57: .Sx Output Formats
58: for available formats. Defaults to
59: .Fl T Ns Ar ascii .
60: .\" ITEM
61: .It Fl V
62: Print version and exit.
63: .\" ITEM
64: .It Fl W Ns Ar err...
65: Print warning messages. May be set to
66: .Fl W Ns Ar all
67: for all warnings,
68: .Ar compat
69: for groff/troff-compatibility warnings, or
70: .Ar syntax
71: for syntax warnings. If
72: .Fl W Ns Ar error
73: is specified, warnings are considered errors and cause utility
74: termination. Multiple
75: .Fl W
76: arguments may be comma-separated, such as
77: .Fl W Ns Ar error,all .
78: .\" ITEM
79: .It Ar infile...
80: Read input from zero or more
81: .Ar infile .
1.2 kristaps 82: If unspecified, reads from stdin. If multiple files are specified,
83: .Nm
84: will halt with the first failed parse.
1.1 kristaps 85: .El
86: .\" PARAGRAPH
87: .Pp
88: By default,
89: .Nm
1.8 kristaps 90: reads
91: .Xr mdoc 7
1.12 kristaps 92: or
93: .Xr man 7
1.8 kristaps 94: text from stdin, implying
1.12 kristaps 95: .Fl m Ns Ar andoc ,
1.8 kristaps 96: and prints 78-column backspace-encoded output to stdout as if
1.1 kristaps 97: .Fl T Ns Ar ascii
98: were provided.
99: .\" PARAGRAPH
100: .Pp
101: .Ex -std mandoc
102: .\" SUB-SECTION
1.13 kristaps 103: .Ss Punctuation
104: If punctuation is set apart from words, such as in the phrase
105: .Dq to be \&, or not to be ,
106: it's processed by
107: .Nm
108: according to the following rules. Opening punctuation
1.4 kristaps 109: .Po
110: .Sq \&( ,
111: .Sq \&[ ,
112: and
113: .Sq \&{
1.13 kristaps 114: .Pc
115: is not followed by a space. Closing punctuation
1.4 kristaps 116: .Po
117: .Sq \&. ,
118: .Sq \&, ,
119: .Sq \&; ,
120: .Sq \&: ,
121: .Sq \&? ,
122: .Sq \&! ,
123: .Sq \&) ,
124: .Sq \&]
125: and
126: .Sq \&}
1.13 kristaps 127: .Pc
128: is not preceeded by whitespace.
1.4 kristaps 129: .Pp
1.13 kristaps 130: If the input is
131: .Xr mdoc 7 ,
132: these rules are also applied to macro arguments when appropriate.
1.4 kristaps 133: .\" SUB-SECTION
1.8 kristaps 134: .Ss Input Formats
135: The
136: .Nm
137: utility accepts
138: .Xr mdoc 7
139: and
140: .Xr man 7
141: input with
1.10 kristaps 142: .Fl m Ns Ar doc
1.8 kristaps 143: and
1.10 kristaps 144: .Fl m Ns Ar an ,
1.8 kristaps 145: respectively. The
146: .Xr mdoc 7
147: format is
148: .Em strongly
149: recommended;
150: .Xr man 7
151: should only be used for legacy manuals.
1.11 kristaps 152: .Pp
1.12 kristaps 153: A third option,
154: .Fl m Ns Ar andoc ,
1.13 kristaps 155: which is also the default, determines encoding on-the-fly: if the first
156: non-comment macro is
157: .Sq \&.Dd
158: or
159: .Sq \&.Dt ,
160: the
161: .Xr mdoc 7
162: parser is used; otherwise, the
163: .Xr man 7
164: parser is used.
165: .Pp
166: If multiple
167: files are specified with
168: .Fl m Ns Ar andoc ,
169: each has its file-type determined this way. If multiple files are
170: specified and
1.12 kristaps 171: .Fl m Ns Ar doc
172: or
173: .Fl m Ns Ar an
174: is specified, then this format is used exclusively.
1.13 kristaps 175: .\" .Pp
176: .\" The following escape sequences are recognised, although the per-format
177: .\" compiler may not allow certain sequences.
178: .\" .Bl -tag -width Ds -offset XXXX
179: .\" .It \efX
180: .\" sets the font mode to X (B, I, R or P, where P resets the font)
181: .\" .It \eX, \e(XX, \e[XN]
182: .\" queries the special-character table for a corresponding symbol
183: .\" .It \e*X, \e*(XX, \e*[XN]
184: .\" deprecated special-character format
185: .\" .El
1.8 kristaps 186: .\" SUB-SECTION
1.1 kristaps 187: .Ss Output Formats
188: The
189: .Nm
190: utility accepts the following
191: .Fl T
192: arguments:
1.13 kristaps 193: .Bl -tag -width XXXXXXXXXXXX
194: .It Fl T Ns Ar ascii
1.1 kristaps 195: Produce 7-bit ASCII output, backspace-encoded for bold and underline
196: styles. This is the default.
1.13 kristaps 197: .It Fl T Ns Ar tree
1.1 kristaps 198: Produce an indented parse tree.
1.13 kristaps 199: .It Fl T Ns Ar lint
1.1 kristaps 200: Parse only: produce no output.
201: .El
1.13 kristaps 202: .Pp
203: If multiple input files are specified, these will be processed by the
204: corresponding filter in-order.
1.1 kristaps 205: .\" SUB-SECTION
206: .Ss Compiler Options
207: Default compiler behaviour may be overriden with the
208: .Fl f
209: flag.
1.13 kristaps 210: .Bl -tag -width XXXXXXXXXXXXXX
1.1 kristaps 211: .It Fl f Ns Ar ign-scope
212: When rewinding the scope of a block macro, forces the compiler to ignore
213: scope violations. This can seriously mangle the resulting tree.
1.8 kristaps 214: .Pq mdoc only
1.1 kristaps 215: .It Fl f Ns Ar ign-escape
216: Ignore invalid escape sequences.
217: .It Fl f Ns Ar ign-macro
1.12 kristaps 218: Ignore unknown macros at the start of input lines (default for
219: .Xr man 7
220: parsing).
221: .It Fl f Ns Ar no-ign-macro
222: Do not ignore unknown macros at the start of input lines (default for
223: .Xr mdoc 7
224: parsing).
1.1 kristaps 225: .El
226: .\" PARAGRAPH
227: .Pp
228: As with the
229: .Fl W
230: flag, multiple
231: .Fl f
232: options may be grouped and delimited with a comma. Using
233: .Fl f Ns Ar ign-scope,ign-escape ,
234: for example, will try to ignore scope and character-escape errors.
235: .\" SECTION
236: .Sh EXAMPLES
1.13 kristaps 237: To page manuals to the terminal:
1.1 kristaps 238: .\" PARAGRAPH
239: .Pp
240: .D1 % mandoc \-Wall,error mandoc.1 2>&1 | less
1.13 kristaps 241: .Pp
242: .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
1.1 kristaps 243: .\" SECTION
244: .Sh SEE ALSO
1.13 kristaps 245: .Xr mandoc_char 7 ,
1.9 kristaps 246: .Xr mdoc 7 ,
247: .Xr man 7
1.1 kristaps 248: .\"
249: .Sh AUTHORS
250: The
251: .Nm
252: utility was written by
253: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
254: .\" SECTION
255: .Sh CAVEATS
256: The
257: .Nm
1.5 kristaps 258: utility in
259: .Fl T Ns Ar ascii
260: mode doesn't yet know how to display the following:
1.1 kristaps 261: .Pp
262: .Bl -bullet -compact
263: .It
264: The \-hang
1.10 kristaps 265: .Sq \&.Bl
1.1 kristaps 266: list is not yet supported.
1.7 kristaps 267: .El
268: .Pp
269: Other macros still aren't supported by virtue of nobody complaining
270: about their absence. Please report any omissions: this is a work in
271: progress.
272: .Pp
273: The following list documents differences between traditional
274: .Xr nroff 1
275: output and
276: .Nm :
277: .Pp
278: .Bl -bullet -compact
279: .It
280: A list of display following
1.10 kristaps 281: .Sq \&.Ss
1.7 kristaps 282: does not assert a prior vertical break, just as it doesn't with
1.10 kristaps 283: .Sq \&.Sh .
1.7 kristaps 284: .It
285: Special characters don't follow the current font style.
1.5 kristaps 286: .\" LIST-ITEM
1.1 kristaps 287: .It
288: The \-literal and \-unfilled
1.10 kristaps 289: .Sq \&.Bd
1.3 kristaps 290: displays types are synonyms, as are \-filled and \-ragged.
1.1 kristaps 291: .El
CVSweb