]> git.cameronkatri.com Git - mandoc.git/blob - mandoc.1
00951beeab44ae58f13c55fb48a387c21b8de6aa
[mandoc.git] / mandoc.1
1 .\" $Id: mandoc.1,v 1.35 2009/09/05 10:30: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 $Mdocdate: September 5 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 V
30 .Op Fl f Ns Ar option...
31 .Op Fl m Ns Ar format
32 .Op Fl W Ns Ar err...
33 .Op Fl T Ns Ar output
34 .Op Ar infile...
35 .
36 .
37 .Sh DESCRIPTION
38 The
39 .Nm
40 utility formats
41 .Ux
42 manual pages for display. The arguments are as follows:
43 .
44 .Bl -tag -width Ds
45 .It Fl f Ns Ar option...
46 Override default compiler behaviour. See
47 .Sx Compiler Options
48 for details.
49 .
50 .It Fl m Ns Ar format
51 Input format. See
52 .Sx Input Formats
53 for available formats. Defaults to
54 .Fl m Ns Ar andoc .
55 .
56 .It Fl T Ns Ar output
57 Output format. See
58 .Sx Output Formats
59 for available formats. Defaults to
60 .Fl T Ns Ar ascii .
61 .
62 .It Fl V
63 Print version and exit.
64 .
65 .It Fl W Ns Ar err...
66 Configure warning messages. Use
67 .Fl W Ns Ar all
68 to print warnings,
69 .Fl W Ns Ar error
70 for warnings to be considered errors and cause utility
71 termination. Multiple
72 .Fl W
73 arguments may be comma-separated, such as
74 .Fl W Ns Ar error,all .
75 .
76 .It Ar infile...
77 Read input from zero or more
78 .Ar infile .
79 If unspecified, reads from stdin. If multiple files are specified,
80 .Nm
81 will halt with the first failed parse.
82 .El
83 .
84 .Pp
85 By default,
86 .Nm
87 reads
88 .Xr mdoc 7
89 or
90 .Xr man 7
91 text from stdin, implying
92 .Fl m Ns Ar andoc ,
93 and prints 78-column backspace-encoded output to stdout as if
94 .Fl T Ns Ar ascii
95 were provided.
96 .
97 .Pp
98 .Ex -std mandoc
99 .
100 .
101 .Ss Punctuation and Spacing
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 .
128 .Pp
129 If the input is
130 .Xr mdoc 7 ,
131 these rules are also applied to macro arguments when appropriate.
132 .
133 .Pp
134 White-space, in non-literal (normal) mode, is stripped from input and
135 replaced on output by a single space. Thus, if you wish to preserve multiple
136 spaces, they must be space-escaped or used in a literal display mode, e.g.,
137 .Sq \&Bd \-literal
138 in
139 .Xr mdoc 7 .
140 .
141 .
142 .Ss Input Formats
143 The
144 .Nm
145 utility accepts
146 .Xr mdoc 7
147 and
148 .Xr man 7
149 input with
150 .Fl m Ns Ar doc
151 and
152 .Fl m Ns Ar an ,
153 respectively. The
154 .Xr mdoc 7
155 format is
156 .Em strongly
157 recommended;
158 .Xr man 7
159 should only be used for legacy manuals.
160 .
161 .Pp
162 A third option,
163 .Fl m Ns Ar andoc ,
164 which is also the default, determines encoding on-the-fly: if the first
165 non-comment macro is
166 .Sq \&Dd
167 or
168 .Sq \&Dt ,
169 the
170 .Xr mdoc 7
171 parser is used; otherwise, the
172 .Xr man 7
173 parser is used.
174 .
175 .Pp
176 If multiple
177 files are specified with
178 .Fl m Ns Ar andoc ,
179 each has its file-type determined this way. If multiple files are
180 specified and
181 .Fl m Ns Ar doc
182 or
183 .Fl m Ns Ar an
184 is specified, then this format is used exclusively.
185 .
186 .
187 .Ss Output Formats
188 The
189 .Nm
190 utility accepts the following
191 .Fl T
192 arguments:
193 .
194 .Bl -tag -width Ds
195 .It Fl T Ns Ar ascii
196 Produce 7-bit ASCII output, backspace-encoded for bold and underline
197 styles. This is the default.
198 .
199 .It Fl T Ns Ar tree
200 Produce an indented parse tree.
201 .
202 .It Fl T Ns Ar lint
203 Parse only: produce no output.
204 .El
205 .
206 .Pp
207 If multiple input files are specified, these will be processed by the
208 corresponding filter in-order.
209 .
210 .
211 .Ss Compiler Options
212 Default compiler behaviour may be overridden with the
213 .Fl f
214 flag.
215 .
216 .Bl -tag -width Ds
217 .It Fl f Ns Ar ign-scope
218 When rewinding the scope of a block macro, forces the compiler to ignore
219 scope violations. This can seriously mangle the resulting tree.
220 .Pq mdoc only
221 .
222 .It Fl f Ns Ar no-ign-escape
223 Don't ignore invalid escape sequences.
224 .
225 .It Fl f Ns Ar no-ign-macro
226 Do not ignore unknown macros at the start of input lines.
227 .
228 .It Fl f Ns Ar no-ign-chars
229 Do not ignore disallowed characters.
230 .
231 .It Fl f Ns Ar strict
232 Implies
233 .Fl f Ns Ar no-ign-escape ,
234 .Fl f Ns Ar no-ign-macro
235 and
236 .Fl f Ns Ar no-ign-chars .
237 .
238 .It Fl f Ns Ar ign-errors
239 Don't halt when encountering parse errors. Useful with
240 .Fl T Ns Ar lint
241 over a large set of manuals passed on the command line.
242 .El
243 .
244 .Pp
245 As with the
246 .Fl W
247 flag, multiple
248 .Fl f
249 options may be grouped and delimited with a comma. Using
250 .Fl f Ns Ar ign-scope,no-ign-escape ,
251 for example, will try to ignore scope and not ignore character-escape
252 errors.
253 .
254 .
255 .Sh EXAMPLES
256 To page manuals to the terminal:
257 .
258 .Pp
259 .D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
260 .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
261 .
262 .Pp
263 To check over a large set of manuals:
264 .
265 .Pp
266 .Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
267 .
268 .
269 .Sh COMPATIBILITY
270 This section summarises
271 .Nm
272 compatibility with
273 .Xr groff 1 .
274 Each input and output format is separately noted.
275 .
276 .
277 .Ss ASCII output
278 .Bl -bullet -compact
279 .It
280 The
281 .Sq \e~
282 special character doesn't produce expected behaviour in
283 .Fl T Ns Ar ascii .
284 .
285 .It
286 The
287 .Sq \&Bd \-literal
288 and
289 .Sq \&Bd \-unfilled
290 macros of
291 .Xr mdoc 7
292 in
293 .Fl T Ns Ar ascii
294 are synonyms, as are \-filled and \-ragged.
295 .
296 .It
297 In
298 .Xr groff 1 ,
299 the
300 .Sq \&Pa
301 .Xr mdoc 7
302 macro does not underline when scoped under an
303 .Sq \&It
304 in the FILES section. This behaves correctly in
305 .Nm .
306 .
307 .It
308 A list or display following
309 .Sq \&Ss
310 .Xr mdoc 7
311 macro in
312 .Fl T Ns Ar ascii
313 does not assert a prior vertical break, just as it doesn't with
314 .Sq \&Sh .
315 .
316 .It
317 The
318 .Sq \&na
319 .Xr man 7
320 macro in
321 .Fl T Ns Ar ascii
322 has no effect.
323 .
324 .It
325 Words aren't hyphenated.
326 .
327 .It
328 In normal mode (not a literal block), blocks of spaces aren't preserved,
329 so double spaces following sentence closure are reduced to a single space;
330 .Xr groff 1
331 retains spaces.
332 .
333 .It
334 Sentences are unilaterally monospaced.
335 .El
336 .\" SECTION
337 .Sh SEE ALSO
338 .Xr mandoc_char 7 ,
339 .Xr mdoc 7 ,
340 .Xr man 7
341 .\" SECTION
342 .Sh AUTHORS
343 The
344 .Nm
345 utility was written by
346 .An Kristaps Dzonsons Aq kristaps@kth.se .