1 .\" $Id: mandoc.1,v 1.35 2009/09/05 10:30:51 kristaps Exp $
3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
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.
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.
17 .Dd $Mdocdate: September 5 2009 $
24 .Nd format and display UNIX manuals
30 .Op Fl f Ns Ar option...
42 manual pages for display. The arguments are as follows:
45 .It Fl f Ns Ar option...
46 Override default compiler behaviour. See
53 for available formats. Defaults to
59 for available formats. Defaults to
63 Print version and exit.
66 Configure warning messages. Use
70 for warnings to be considered errors and cause utility
73 arguments may be comma-separated, such as
74 .Fl W Ns Ar error,all .
77 Read input from zero or more
79 If unspecified, reads from stdin. If multiple files are specified,
81 will halt with the first failed parse.
91 text from stdin, implying
93 and prints 78-column backspace-encoded output to stdout as if
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 ,
106 according to the following rules: opening punctuation
113 is not followed by a space; closing punctuation
126 is not preceded by whitespace.
131 these rules are also applied to macro arguments when appropriate.
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.,
159 should only be used for legacy manuals.
164 which is also the default, determines encoding on-the-fly: if the first
171 parser is used; otherwise, the
177 files are specified with
179 each has its file-type determined this way. If multiple files are
184 is specified, then this format is used exclusively.
190 utility accepts the following
196 Produce 7-bit ASCII output, backspace-encoded for bold and underline
197 styles. This is the default.
200 Produce an indented parse tree.
203 Parse only: produce no output.
207 If multiple input files are specified, these will be processed by the
208 corresponding filter in-order.
212 Default compiler behaviour may be overridden with the
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.
222 .It Fl f Ns Ar no-ign-escape
223 Don't ignore invalid escape sequences.
225 .It Fl f Ns Ar no-ign-macro
226 Do not ignore unknown macros at the start of input lines.
228 .It Fl f Ns Ar no-ign-chars
229 Do not ignore disallowed characters.
231 .It Fl f Ns Ar strict
233 .Fl f Ns Ar no-ign-escape ,
234 .Fl f Ns Ar no-ign-macro
236 .Fl f Ns Ar no-ign-chars .
238 .It Fl f Ns Ar ign-errors
239 Don't halt when encountering parse errors. Useful with
241 over a large set of manuals passed on the command line.
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
256 To page manuals to the terminal:
259 .D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
260 .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
263 To check over a large set of manuals:
266 .Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
270 This section summarises
274 Each input and output format is separately noted.
282 special character doesn't produce expected behaviour in
294 are synonyms, as are \-filled and \-ragged.
302 macro does not underline when scoped under an
304 in the FILES section. This behaves correctly in
308 A list or display following
313 does not assert a prior vertical break, just as it doesn't with
325 Words aren't hyphenated.
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;
334 Sentences are unilaterally monospaced.
345 utility was written by
346 .An Kristaps Dzonsons Aq kristaps@kth.se .