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