| blob | 80bdc8162a25a76f3fea736a6a88349f7695efde |
1 .\" $Id: mandoc.1,v 1.45 2009/10/26 15:44:51 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 November 11, 2009
18 .Dt MANDOC 1
19 .Os
20 .
21 .
22 .Sh NAME
23 .Nm mandoc
24 .Nd format and display UNIX manuals
25 .
26 .
27 .Sh SYNOPSIS
28 .Nm mandoc
29 .Op Fl f Ns Ar option...
30 .Op Fl m Ns Ar format
31 .Op Fl O Ns Ar option...
32 .Op Fl T Ns Ar output
33 .Op Fl V
34 .Op Fl W Ns Ar err...
35 .Op Ar infile...
36 .
37 .
38 .Sh DESCRIPTION
39 The
40 .Nm
41 utility formats
42 .Ux
43 manual pages for display. The arguments are as follows:
44 .
45 .Bl -tag -width Ds
46 .It Fl f Ns Ar option...
47 Comma-separated compiler options. See
48 .Sx Compiler Options
49 for details.
50 .
51 .It Fl m Ns Ar format
52 Input format. See
53 .Sx Input Formats
54 for available formats. Defaults to
55 .Fl m Ns Ar andoc .
56 .
57 .It Fl O Ns Ar option...
58 Comma-separated output options. See
59 .Sx Output Options
60 for details.
61 .
62 .It Fl T Ns Ar output
63 Output format. See
64 .Sx Output Formats
65 for available formats. Defaults to
66 .Fl T Ns Ar ascii .
67 .
68 .It Fl V
69 Print version and exit.
70 .
71 .It Fl W Ns Ar err...
72 Comma-separated warning options. Use
73 .Fl W Ns Ar all
74 to print warnings,
75 .Fl W Ns Ar error
76 for warnings to be considered errors and cause utility
77 termination. Multiple
78 .Fl W
79 arguments may be comma-separated, such as
80 .Fl W Ns Ar error,all .
81 .
82 .It Ar infile...
83 Read input from zero or more
84 .Ar infile .
85 If unspecified, reads from stdin. If multiple files are specified,
86 .Nm
87 will halt with the first failed parse.
88 .El
89 .
90 .Pp
91 By default,
92 .Nm
93 reads
94 .Xr mdoc 7
95 or
96 .Xr man 7
97 text from stdin, implying
98 .Fl m Ns Ar andoc ,
99 and prints 78-column backspace-encoded output to stdout as if
100 .Fl T Ns Ar ascii
101 were provided.
102 .
103 .Pp
104 .Ex -std mandoc
105 .
106 .
107 .Ss Punctuation and Spacing
108 If punctuation is set apart from words, such as in the phrase
109 .Dq to be \&, or not to be ,
110 it's processed by
111 .Nm
112 according to the following rules: opening punctuation
113 .Po
114 .Sq \&( ,
115 .Sq \&[ ,
116 and
117 .Sq \&{
118 .Pc
119 is not followed by a space; closing punctuation
120 .Po
121 .Sq \&. ,
122 .Sq \&, ,
123 .Sq \&; ,
124 .Sq \&: ,
125 .Sq \&? ,
126 .Sq \&! ,
127 .Sq \&) ,
128 .Sq \&]
129 and
130 .Sq \&}
131 .Pc
132 is not preceded by whitespace.
133 .
134 .Pp
135 If the input is
136 .Xr mdoc 7 ,
137 these rules are also applied to macro arguments when appropriate.
138 .
139 .Pp
140 White-space, in non-literal (normal) mode, is stripped from input and
141 replaced on output by a single space. Thus, if you wish to preserve multiple
142 spaces, they must be space-escaped or used in a literal display mode, e.g.,
143 .Sq \&Bd \-literal
144 in
145 .Xr mdoc 7 .
146 .
147 .
148 .Ss Input Formats
149 The
150 .Nm
151 utility accepts
152 .Xr mdoc 7
153 and
154 .Xr man 7
155 input with
156 .Fl m Ns Ar doc
157 and
158 .Fl m Ns Ar an ,
159 respectively. The
160 .Xr mdoc 7
161 format is
162 .Em strongly
163 recommended;
164 .Xr man 7
165 should only be used for legacy manuals.
166 .
167 .Pp
168 A third option,
169 .Fl m Ns Ar andoc ,
170 which is also the default, determines encoding on-the-fly: if the first
171 non-comment macro is
172 .Sq \&Dd
173 or
174 .Sq \&Dt ,
175 the
176 .Xr mdoc 7
177 parser is used; otherwise, the
178 .Xr man 7
179 parser is used.
180 .
181 .Pp
182 If multiple
183 files are specified with
184 .Fl m Ns Ar andoc ,
185 each has its file-type determined this way. If multiple files are
186 specified and
187 .Fl m Ns Ar doc
188 or
189 .Fl m Ns Ar an
190 is specified, then this format is used exclusively.
191 .
192 .
193 .Ss Output Formats
194 The
195 .Nm
196 utility accepts the following
197 .Fl T
198 arguments:
199 .
200 .Bl -tag -width Ds
201 .It Fl T Ns Ar ascii
202 Produce 7-bit ASCII output, backspace-encoded for bold and underline
203 styles. This is the default.
204 .
205 .It Fl T Ns Ar html
206 Produce strict HTML-4.01 output, with a sane default style.
207 .
208 .It Fl T Ns Ar tree
209 Produce an indented parse tree.
210 .
211 .It Fl T Ns Ar lint
212 Parse only: produce no output.
213 .El
214 .
215 .Pp
216 If multiple input files are specified, these will be processed by the
217 corresponding filter in-order.
218 .
219 .
220 .Ss Compiler Options
221 Default compiler behaviour may be overridden with the
222 .Fl f
223 flag.
224 .
225 .Bl -tag -width Ds
226 .It Fl f Ns Ar ign-scope
227 When rewinding the scope of a block macro, forces the compiler to ignore
228 scope violations. This can seriously mangle the resulting tree.
229 .Pq mdoc only
230 .
231 .It Fl f Ns Ar ign-escape
232 Ignore invalid escape sequences.
233 This is the default, but the option can be used to override an earlier
234 .Fl f Ns Ar strict .
235 .
236 .It Fl f Ns Ar no-ign-escape
237 Don't ignore invalid escape sequences.
238 .
239 .It Fl f Ns Ar no-ign-macro
240 Do not ignore unknown macros at the start of input lines.
241 .
242 .It Fl f Ns Ar no-ign-chars
243 Do not ignore disallowed characters.
244 .
245 .It Fl f Ns Ar strict
246 Implies
247 .Fl f Ns Ar no-ign-escape ,
248 .Fl f Ns Ar no-ign-macro
249 and
250 .Fl f Ns Ar no-ign-chars .
251 .
252 .It Fl f Ns Ar ign-errors
253 Don't halt when encountering parse errors. Useful with
254 .Fl T Ns Ar lint
255 over a large set of manuals passed on the command line.
256 .El
257 .
258 .Ss Output Options
259 For the time being, only
260 .Fl T Ns Ar html
261 is the only mode with output options:
262 .Bl -tag -width Ds
263 .It Fl O Ns Ar style=style.css
264 The file
265 .Ar style.css
266 is used for an external style-sheet. This must be a valid absolute or
267 relative URI.
268 .It Fl O Ns Ar includes=fmt
269 The string
270 .Ar fmt ,
271 for example,
272 .Ar ../src/%I.html ,
273 is used as a template for linked header files (usually via the
274 .Sq \&In
275 macro). Instances of
276 .Sq \&%I
277 are replaced with the include filename. The default is not to present a
278 hyperlink.
279 .It Fl O Ns Ar man=fmt
280 The string
281 .Ar fmt ,
282 for example,
283 .Ar ../html%S/%N.%S.html ,
284 is used as a template for linked manuals (usually via the
285 .Sq \&Xr
286 macro). Instances of
287 .Sq \&%N
288 and
289 .Sq %S
290 are replaced with the linked manual's name and section, respectively.
291 If no section is included, section 1 is assumed. The default is not to
292 present a hyperlink.
293 .El
294 .
295 .Sh EXAMPLES
296 To page manuals to the terminal:
297 .
298 .Pp
299 .D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
300 .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
301 .
302 .Pp
303 To produce HTML manuals with
304 .Ar style.css
305 as the style-sheet:
306 .Pp
307 .D1 % mandoc \-Thtml -ostyle=style.css mdoc.7 > mdoc.7.html
308 .Pp
309 To check over a large set of manuals:
310 .
311 .Pp
312 .Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
313 .
314 .
315 .Sh COMPATIBILITY
316 This section summarises
317 .Nm
318 compatibility with
319 .Xr groff 1 .
320 Each input and output format is separately noted.
321 .
322 .
323 .Ss ASCII output
324 .Bl -bullet -compact
325 .It
326 The
327 .Sq \e~
328 special character doesn't produce expected behaviour in
329 .Fl T Ns Ar ascii .
330 .
331 .It
332 The
333 .Sq \&Bd \-literal
334 and
335 .Sq \&Bd \-unfilled
336 macros of
337 .Xr mdoc 7
338 in
339 .Fl T Ns Ar ascii
340 are synonyms, as are \-filled and \-ragged.
341 .
342 .It
343 In
344 .Xr groff 1 ,
345 the
346 .Sq \&Pa
347 .Xr mdoc 7
348 macro does not underline when scoped under an
349 .Sq \&It
350 in the FILES section. This behaves correctly in
351 .Nm .
352 .
353 .It
354 A list or display following
355 .Sq \&Ss
356 .Xr mdoc 7
357 macro in
358 .Fl T Ns Ar ascii
359 does not assert a prior vertical break, just as it doesn't with
360 .Sq \&Sh .
361 .
362 .It
363 The
364 .Sq \&na
365 .Xr man 7
366 macro in
367 .Fl T Ns Ar ascii
368 has no effect.
369 .
370 .It
371 Words aren't hyphenated.
372 .
373 .It
374 In normal mode (not a literal block), blocks of spaces aren't preserved,
375 so double spaces following sentence closure are reduced to a single space;
376 .Xr groff 1
377 retains spaces.
378 .
379 .It
380 Sentences are unilaterally monospaced.
381 .El
382 .
383 .Ss HTML output
384 .Bl -bullet -compact
385 .It
386 The
387 .Xr mdoc 7
388 .Sq \&Bl \-hang
389 and
390 .Sq \&Bl \-tag
391 list types render similarly (no break following overreached left-hand
392 side) due to the expressive constraints of HTML.
393 .
394 .It
395 The
396 .Xr man 7
397 .Sq IP
398 and
399 .Sq TP
400 lists render similarly.
401 .El
402 .\" SECTION
403 .Sh SEE ALSO
404 .Xr mandoc_char 7 ,
405 .Xr mdoc 7 ,
406 .Xr man 7
407 .
408 .Sh AUTHORS
409 The
410 .Nm
411 utility was written by
412 .An Kristaps Dzonsons Aq kristaps@kth.se .
413 .
414 .Sh CAVEATS
415 In
416 .Fl T Ns Ar html ,
417 the maximum size of an element attribute is determined by
418 .Dv BUFSIZ ,
419 which is usually 1024 bytes. Be aware of this when setting long link
420 formats with
421 .Fl O Ns Ar man=fmt .