Annotation of mandoc/mandoc.1, Revision 1.6
1.6 ! kristaps 1: .\" $Id: mandoc.1,v 1.5 2009/03/21 21:09:00 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
25: .Nd format and display BSD manuals
26: .\" SECTION
27: .Sh SYNOPSIS
28: .Nm mandoc
29: .Op Fl V
30: .Op Fl f Ns Ar option...
31: .Op Fl W Ns Ar err...
32: .Op Fl T Ns Ar output
33: .Op Ar infile...
34: .\" SECTION
35: .Sh DESCRIPTION
36: The
37: .Nm
38: utility formats a BSD
39: .Dq mdoc
40: manual page for display. The arguments are as follows:
41: .Bl -tag -width XXXXXXXXXXXX
42: .\" ITEM
43: .It Fl f Ns Ar option...
44: Override default compiler behaviour. See
45: .Sx Compiler Options
46: for details.
47: .\" ITEM
48: .It Fl T
49: Output format. See
50: .Sx Output Formats
51: for available formats. Defaults to
52: .Fl T Ns Ar ascii .
53: .\" ITEM
54: .It Fl V
55: Print version and exit.
56: .\" ITEM
57: .It Fl W Ns Ar err...
58: Print warning messages. May be set to
59: .Fl W Ns Ar all
60: for all warnings,
61: .Ar compat
62: for groff/troff-compatibility warnings, or
63: .Ar syntax
64: for syntax warnings. If
65: .Fl W Ns Ar error
66: is specified, warnings are considered errors and cause utility
67: termination. Multiple
68: .Fl W
69: arguments may be comma-separated, such as
70: .Fl W Ns Ar error,all .
71: .\" ITEM
72: .It Ar infile...
73: Read input from zero or more
74: .Ar infile .
1.2 kristaps 75: If unspecified, reads from stdin. If multiple files are specified,
76: .Nm
77: will halt with the first failed parse.
1.1 kristaps 78: .El
79: .\" PARAGRAPH
80: .Pp
81: By default,
82: .Nm
83: reads from stdin and prints 78-column backspace-encoded output to stdout
84: as if
85: .Fl T Ns Ar ascii
86: were provided.
87: .\" PARAGRAPH
88: .Pp
89: .Ex -std mandoc
90: .\" SUB-SECTION
1.4 kristaps 91: .Ss Reserved Words
92: The reserved words described in
93: .Xr mdoc 7
94: are handled according to the following rules:
95: .Bl -enum -offset XXX
96: .It
97: Opening delimiters
98: .Po
99: .Sq \&( ,
100: .Sq \&[ ,
101: and
102: .Sq \&{
103: .Pc are not followed by whitespace.
104: .It
105: Closing delimiters
106: .Po
107: .Sq \&. ,
108: .Sq \&, ,
109: .Sq \&; ,
110: .Sq \&: ,
111: .Sq \&? ,
112: .Sq \&! ,
113: .Sq \&) ,
114: .Sq \&]
115: and
116: .Sq \&}
117: .Pc are not preceeded by whitespace.
118: .El
119: .\" PARAGRAPH
120: .Pp
121: Note that reserved words may occur in streams of text, so the following:
122: .Bd -literal -offset XXXX
123: this self is not that of the waking , empirically real man
124: .Ed
125: .\" PARAGRAPH
126: .Pp
127: \&...correctly adjusts the comma spacing to
128: .Qq this self is not that of the waking , empirically real man .
129: .\" SUB-SECTION
1.1 kristaps 130: .Ss Output Formats
131: The
132: .Nm
133: utility accepts the following
134: .Fl T
135: arguments:
136: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
137: .It Ar ascii
138: Produce 7-bit ASCII output, backspace-encoded for bold and underline
139: styles. This is the default.
140: .It Ar tree
141: Produce an indented parse tree.
142: .It Ar lint
143: Parse only: produce no output.
144: .El
145: .\" SUB-SECTION
146: .Ss Compiler Options
147: Default compiler behaviour may be overriden with the
148: .Fl f
149: flag.
150: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
151: .It Fl f Ns Ar ign-scope
152: When rewinding the scope of a block macro, forces the compiler to ignore
153: scope violations. This can seriously mangle the resulting tree.
154: .It Fl f Ns Ar ign-escape
155: Ignore invalid escape sequences.
156: .It Fl f Ns Ar ign-macro
157: Ignore unknown macros at the start of input lines.
158: .El
159: .\" PARAGRAPH
160: .Pp
161: As with the
162: .Fl W
163: flag, multiple
164: .Fl f
165: options may be grouped and delimited with a comma. Using
166: .Fl f Ns Ar ign-scope,ign-escape ,
167: for example, will try to ignore scope and character-escape errors.
168: .\" SECTION
169: .Sh EXAMPLES
170: To page this manual page on the terminal:
171: .\" PARAGRAPH
172: .Pp
173: .D1 % mandoc \-Wall,error mandoc.1 2>&1 | less
174: .\" SECTION
175: .Sh SEE ALSO
176: .Xr mdoc 7
177: .\"
178: .Sh AUTHORS
179: The
180: .Nm
181: utility was written by
182: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
183: .\" SECTION
184: .Sh CAVEATS
185: The
186: .Nm
1.5 kristaps 187: utility in
188: .Fl T Ns Ar ascii
189: mode doesn't yet know how to display the following:
1.1 kristaps 190: .Pp
191: .Bl -bullet -compact
192: .It
193: The \-hang
194: .Sq \&Bl
195: list is not yet supported.
1.5 kristaps 196: .\" LIST-ITEM
1.1 kristaps 197: .It
198: The \-literal and \-unfilled
199: .Sq \&Bd
1.3 kristaps 200: displays types are synonyms, as are \-filled and \-ragged.
1.5 kristaps 201: .\" LIST-ITEM
1.1 kristaps 202: .It
203: The
1.5 kristaps 204: .Sq \&Bd
205: macro doesn't process \-compact .
1.1 kristaps 206: .El
207: .Pp
208: Other macros still aren't supported by virtue of nobody complaining
209: about their absence. Please report any omissions: this is a work in
210: progress.
CVSweb