Added nchild decrement in libman (not used, but better in than forgotten).
[mandoc.git] / mandoc.1
1 .\" $Id: mandoc.1,v 1.21 2009/06/18 08:13:34 kristaps Exp $
2 .\"
3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
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 above
7 .\" copyright notice and this permission notice appear in all copies.
8 .\"
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.
16 .\"
17 .Dd $Mdocdate: June 18 2009 $
18 .Dt MANDOC 1
19 .Os
20 .\" SECTION
21 .Sh NAME
22 .Nm mandoc
23 .Nd format and display UNIX manuals
24 .\" SECTION
25 .Sh SYNOPSIS
26 .Nm mandoc
27 .Op Fl V
28 .Op Fl f Ns Ar option...
29 .Op Fl m Ns Ar format
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
37 utility formats
38 .Ux
39 manual pages for display. The arguments are as follows:
40 .Bl -tag -width Ds
41 .\" ITEM
42 .It Fl f Ns Ar option...
43 Override default compiler behaviour. See
44 .Sx Compiler Options
45 for details.
46 .\" ITEM
47 .It Fl m Ns Ar format
48 Input format. See
49 .Sx Input Formats
50 for available formats. Defaults to
51 .Fl m Ns Ar andoc .
52 .\" ITEM
53 .It Fl T Ns Ar output
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 .
80 If unspecified, reads from stdin. If multiple files are specified,
81 .Nm
82 will halt with the first failed parse.
83 .El
84 .\" PARAGRAPH
85 .Pp
86 By default,
87 .Nm
88 reads
89 .Xr mdoc 7
90 or
91 .Xr man 7
92 text from stdin, implying
93 .Fl m Ns Ar andoc ,
94 and prints 78-column backspace-encoded output to stdout as if
95 .Fl T Ns Ar ascii
96 were provided.
97 .\" PARAGRAPH
98 .Pp
99 .Ex -std mandoc
100 .\" SUB-SECTION
101 .Ss Punctuation
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
106 according to the following rules. Opening punctuation
107 .Po
108 .Sq \&( ,
109 .Sq \&[ ,
110 and
111 .Sq \&{
112 .Pc
113 is not followed by a space. Closing punctuation
114 .Po
115 .Sq \&. ,
116 .Sq \&, ,
117 .Sq \&; ,
118 .Sq \&: ,
119 .Sq \&? ,
120 .Sq \&! ,
121 .Sq \&) ,
122 .Sq \&]
123 and
124 .Sq \&}
125 .Pc
126 is not preceded by whitespace.
127 .Pp
128 If the input is
129 .Xr mdoc 7 ,
130 these rules are also applied to macro arguments when appropriate.
131 .\" SUB-SECTION
132 .Ss Input Formats
133 The
134 .Nm
135 utility accepts
136 .Xr mdoc 7
137 and
138 .Xr man 7
139 input with
140 .Fl m Ns Ar doc
141 and
142 .Fl m Ns Ar an ,
143 respectively. The
144 .Xr mdoc 7
145 format is
146 .Em strongly
147 recommended;
148 .Xr man 7
149 should only be used for legacy manuals.
150 .Pp
151 A third option,
152 .Fl m Ns Ar andoc ,
153 which is also the default, determines encoding on-the-fly: if the first
154 non-comment macro is
155 .Sq \&.Dd
156 or
157 .Sq \&.Dt ,
158 the
159 .Xr mdoc 7
160 parser is used; otherwise, the
161 .Xr man 7
162 parser is used.
163 .Pp
164 If multiple
165 files are specified with
166 .Fl m Ns Ar andoc ,
167 each has its file-type determined this way. If multiple files are
168 specified and
169 .Fl m Ns Ar doc
170 or
171 .Fl m Ns Ar an
172 is specified, then this format is used exclusively.
173 .\" .Pp
174 .\" The following escape sequences are recognised, although the per-format
175 .\" compiler may not allow certain sequences.
176 .\" .Bl -tag -width Ds -offset XXXX
177 .\" .It \efX
178 .\" sets the font mode to X (B, I, R or P, where P resets the font)
179 .\" .It \eX, \e(XX, \e[XN]
180 .\" queries the special-character table for a corresponding symbol
181 .\" .It \e*X, \e*(XX, \e*[XN]
182 .\" deprecated special-character format
183 .\" .El
184 .\" SUB-SECTION
185 .Ss Output Formats
186 The
187 .Nm
188 utility accepts the following
189 .Fl T
190 arguments:
191 .Bl -tag -width Ds
192 .It Fl T Ns Ar ascii
193 Produce 7-bit ASCII output, backspace-encoded for bold and underline
194 styles. This is the default.
195 .It Fl T Ns Ar tree
196 Produce an indented parse tree.
197 .It Fl T Ns Ar lint
198 Parse only: produce no output.
199 .El
200 .Pp
201 If multiple input files are specified, these will be processed by the
202 corresponding filter in-order.
203 .\" SUB-SECTION
204 .Ss Compiler Options
205 Default compiler behaviour may be overriden with the
206 .Fl f
207 flag.
208 .Bl -tag -width Ds
209 .It Fl f Ns Ar ign-scope
210 When rewinding the scope of a block macro, forces the compiler to ignore
211 scope violations. This can seriously mangle the resulting tree.
212 .Pq mdoc only
213 .It Fl f Ns Ar no-ign-escape
214 Don't ignore invalid escape sequences.
215 .It Fl f Ns Ar no-ign-macro
216 Do not ignore unknown macros at the start of input lines.
217 .It Fl f Ns Ar no-ign-chars
218 Do not ignore disallowed characters.
219 .It Fl f Ns Ar strict
220 Implies
221 .Fl f Ns Ar no-ign-escape ,
222 .Fl f Ns Ar no-ign-macro
223 and
224 .Fl f Ns Ar no-ign-chars .
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,no-ign-escape ,
234 for example, will try to ignore scope and not ignore character-escape
235 errors.
236 .\" SECTION
237 .Sh EXAMPLES
238 To page manuals to the terminal:
239 .\" PARAGRAPH
240 .Pp
241 .D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
242 .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
243 .\" SECTION
244 .Sh COMPATIBILITY
245 This section summarises
246 .Nm
247 compatibility with
248 .Xr groff 1 .
249 .Pp
250 .Bl -bullet -compact
251 .It
252 A list or display following
253 .Sq \&.Ss
254 does not assert a prior vertical break, just as it doesn't with
255 .Sq \&.Sh .
256 .\" LIST-ITEM
257 .It
258 The \-literal and \-unfilled
259 .Sq \&.Bd
260 displays types are synonyms, as are \-filled and \-ragged.
261 .\" LIST-ITEM
262 .It
263 Words aren't hyphenated.
264 .El
265 .\" SECTION
266 .Sh SEE ALSO
267 .Xr mandoc_char 7 ,
268 .Xr mdoc 7 ,
269 .Xr man 7
270 .\" SECTION
271 .Sh AUTHORS
272 The
273 .Nm
274 utility was written by
275 .An Kristaps Dzonsons Aq kristaps@kth.se .
276 .\" SECTION
277 .Sh CAVEATS
278 The
279 .Nm
280 utility doesn't yet know how to display \-hang lists.
281 .Pp
282 Other macros still aren't supported by virtue of nobody complaining
283 about their absence.