Annotation of mandoc/mandoc.1, Revision 1.12
1.12 ! kristaps 1: .\" $Id: mandoc.1,v 1.11 2009/03/26 16:44: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$
20: .Dt mandoc 1
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.8 kristaps 103: .Ss Reserved Words (mdoc only)
1.4 kristaps 104: The reserved words described in
105: .Xr mdoc 7
106: are handled according to the following rules:
107: .Bl -enum -offset XXX
108: .It
109: Opening delimiters
110: .Po
111: .Sq \&( ,
112: .Sq \&[ ,
113: and
114: .Sq \&{
115: .Pc are not followed by whitespace.
116: .It
117: Closing delimiters
118: .Po
119: .Sq \&. ,
120: .Sq \&, ,
121: .Sq \&; ,
122: .Sq \&: ,
123: .Sq \&? ,
124: .Sq \&! ,
125: .Sq \&) ,
126: .Sq \&]
127: and
128: .Sq \&}
129: .Pc are not preceeded by whitespace.
130: .El
131: .\" PARAGRAPH
132: .Pp
1.7 kristaps 133: Note that reserved words only register as such as if they appear as
134: standalone tokens, either in parsed lines or streams of text. Thus, the
135: following fragment:
1.4 kristaps 136: .Bd -literal -offset XXXX
137: this self is not that of the waking , empirically real man
138: .Ed
139: .\" PARAGRAPH
140: .Pp
141: \&...correctly adjusts the comma spacing to
1.7 kristaps 142: .Dq this self is not that of the waking , empirically real man .
143: However, if the comma were part of
144: .Dq ,empirically ,
145: it would not.
1.4 kristaps 146: .\" SUB-SECTION
1.8 kristaps 147: .Ss Input Formats
148: The
149: .Nm
150: utility accepts
151: .Xr mdoc 7
152: and
153: .Xr man 7
154: input with
1.10 kristaps 155: .Fl m Ns Ar doc
1.8 kristaps 156: and
1.10 kristaps 157: .Fl m Ns Ar an ,
1.8 kristaps 158: respectively. The
159: .Xr mdoc 7
160: format is
161: .Em strongly
162: recommended;
163: .Xr man 7
164: should only be used for legacy manuals.
1.11 kristaps 165: .Pp
1.12 ! kristaps 166: A third option,
! 167: .Fl m Ns Ar andoc ,
! 168: which is also the default, determines encoding on-the-fly. If multiple
! 169: files are passed in, each has its file-type determined this way. If
! 170: multiple files are passed and
! 171: .Fl m Ns Ar doc
! 172: or
! 173: .Fl m Ns Ar an
! 174: is specified, then this format is used exclusively.
! 175: .Pp
1.11 kristaps 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:
193: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
194: .It Ar ascii
195: Produce 7-bit ASCII output, backspace-encoded for bold and underline
196: styles. This is the default.
197: .It Ar tree
198: Produce an indented parse tree.
199: .It Ar lint
200: Parse only: produce no output.
201: .El
202: .\" SUB-SECTION
203: .Ss Compiler Options
204: Default compiler behaviour may be overriden with the
205: .Fl f
206: flag.
1.12 ! kristaps 207: .Bl -tag -width XXXXXXXXXXXXXX -offset XXXX
1.1 kristaps 208: .It Fl f Ns Ar ign-scope
209: When rewinding the scope of a block macro, forces the compiler to ignore
210: scope violations. This can seriously mangle the resulting tree.
1.8 kristaps 211: .Pq mdoc only
1.1 kristaps 212: .It Fl f Ns Ar ign-escape
213: Ignore invalid escape sequences.
214: .It Fl f Ns Ar ign-macro
1.12 ! kristaps 215: Ignore unknown macros at the start of input lines (default for
! 216: .Xr man 7
! 217: parsing).
! 218: .It Fl f Ns Ar no-ign-macro
! 219: Do not ignore unknown macros at the start of input lines (default for
! 220: .Xr mdoc 7
! 221: parsing).
1.1 kristaps 222: .El
223: .\" PARAGRAPH
224: .Pp
225: As with the
226: .Fl W
227: flag, multiple
228: .Fl f
229: options may be grouped and delimited with a comma. Using
230: .Fl f Ns Ar ign-scope,ign-escape ,
231: for example, will try to ignore scope and character-escape errors.
232: .\" SECTION
233: .Sh EXAMPLES
234: To page this manual page on the terminal:
235: .\" PARAGRAPH
236: .Pp
237: .D1 % mandoc \-Wall,error mandoc.1 2>&1 | less
238: .\" SECTION
239: .Sh SEE ALSO
1.9 kristaps 240: .Xr mdoc 7 ,
241: .Xr man 7
1.1 kristaps 242: .\"
243: .Sh AUTHORS
244: The
245: .Nm
246: utility was written by
247: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
248: .\" SECTION
249: .Sh CAVEATS
250: The
251: .Nm
1.5 kristaps 252: utility in
253: .Fl T Ns Ar ascii
254: mode doesn't yet know how to display the following:
1.1 kristaps 255: .Pp
256: .Bl -bullet -compact
257: .It
258: The \-hang
1.10 kristaps 259: .Sq \&.Bl
1.1 kristaps 260: list is not yet supported.
1.7 kristaps 261: .El
262: .Pp
263: Other macros still aren't supported by virtue of nobody complaining
264: about their absence. Please report any omissions: this is a work in
265: progress.
266: .Pp
267: The following list documents differences between traditional
268: .Xr nroff 1
269: output and
270: .Nm :
271: .Pp
272: .Bl -bullet -compact
273: .It
274: A list of display following
1.10 kristaps 275: .Sq \&.Ss
1.7 kristaps 276: does not assert a prior vertical break, just as it doesn't with
1.10 kristaps 277: .Sq \&.Sh .
1.7 kristaps 278: .It
279: Special characters don't follow the current font style.
1.5 kristaps 280: .\" LIST-ITEM
1.1 kristaps 281: .It
282: The \-literal and \-unfilled
1.10 kristaps 283: .Sq \&.Bd
1.3 kristaps 284: displays types are synonyms, as are \-filled and \-ragged.
1.1 kristaps 285: .El
CVSweb