1 .\" $Id: mandoc.1,v 1.88 2011/05/20 15:51:18 kristaps Exp $
3 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
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: May 20 2011 $
22 .Nd format and display UNIX manuals
36 manual pages for display.
37 The arguments are as follows:
43 for available formats.
47 Comma-separated output options.
52 for available formats.
56 Print version and exit.
58 Specify the minimum message
60 to be reported on the standard error output and to affect the exit status.
83 to exit after parsing a file that causes warnings or errors of at least
85 No formatted output will be produced from that file.
90 are requested, they can be joined with a comma, for example
91 .Fl W Ns Cm error , Ns Cm stop .
93 Read input from zero or more files.
94 If unspecified, reads from stdin.
95 If multiple files are specified,
97 will halt with the first failed parse.
106 text from stdin, implying
129 should only be used for legacy manuals.
133 which is also the default, determines encoding on-the-fly: if the first
140 parser is used; otherwise, the
145 files are specified with
147 each has its file-type determined this way.
148 If multiple files are
153 is specified, then this format is used exclusively.
157 utility accepts the following
159 arguments, which correspond to output modes:
162 Encode output in the UTF-8 multi-byte format.
165 .It Fl T Ns Cm locale
166 Encode output using the current
171 Produce 7-bit ASCII output.
176 Produce strict CSS1/HTML-4.01 output.
180 Parse only: produce no output.
182 .Fl W Ns Cm warning .
188 Produce PostScript output.
190 .Sx PostScript Output .
192 Produce an indented parse tree.
194 Produce strict CSS1/XHTML-1.0 output.
199 If multiple input files are specified, these will be processed by the
200 corresponding filter in-order.
204 to force a UTF-8 locale.
207 for details and options.
209 Locale-depending output encoding is triggered with
211 This option is not available on all systems: systems without locale
212 support, or those whose internal representation is not natively UCS-4,
217 for font style specification and available command-line arguments.
221 which is the default, is rendered in standard 7-bit ASCII documented in
224 Font styles are applied by using back-spaced encoding such that an
228 .Sq _ Ns \e[bs] Ns c ,
231 is the back-space character number 8.
232 Emboldened characters are rendered as
233 .Sq c Ns \e[bs] Ns c .
235 The special characters documented in
237 are rendered best-effort in an ASCII equivalent.
238 If no equivalent is found,
242 Output width is limited to 78 visible columns unless literal input lines
247 arguments are accepted:
249 .It Cm width Ns = Ns Ar width
250 The output width is set to
252 which will normalise to \(>=60.
257 conforms to HTML-4.01 strict.
260 .Pa example.style.css
261 file documents style-sheet classes available for customising output.
262 If a style-sheet is not specified with
265 defaults to simple output readable in any graphical or text-based web
268 Special characters are rendered in decimal-encoded UTF-8.
272 arguments are accepted:
274 .It Cm includes Ns = Ns Ar fmt
279 is used as a template for linked header files (usually via the
284 are replaced with the include filename.
285 The default is not to present a
287 .It Cm man Ns = Ns Ar fmt
291 .Ar ../html%S/%N.%S.html ,
292 is used as a template for linked manuals (usually via the
299 are replaced with the linked manual's name and section, respectively.
300 If no section is included, section 1 is assumed.
301 The default is not to
303 .It Cm style Ns = Ns Ar style.css
306 is used for an external style-sheet.
307 This must be a valid absolute or
310 .Ss PostScript Output
313 Level-2 pages may be generated by
315 Output pages default to letter sized and are rendered in the Times font
317 Margins are calculated as 1/9 the page length and width.
320 Special characters are rendered as in
325 arguments are accepted:
327 .It Cm paper Ns = Ns Ar name
337 You may also manually specify dimensions as
339 width by height in millimetres.
340 If an unknown value is encountered,
345 PDF-1.1 output may be generated by
348 .Sx PostScript Output
351 arguments and defaults.
355 conforms to XHTML-1.0 strict.
359 for details; beyond generating XHTML tags instead of HTML tags, these
360 output modes are identical.
364 utility exits with one of the following values, controlled by the message
370 .Bl -tag -width Ds -compact
372 No warnings or errors occurred, or those that did were ignored because
373 they were lower than the requested
376 At least one warning occurred, but no error, and
380 At least one parsing error occurred, but no fatal error, and
386 A fatal parsing error occurred.
388 Invalid command line arguments were specified.
389 No input files have been read.
391 An operating system error occurred, for example memory exhaustion or an
392 error accessing input files.
395 to exit at once, possibly in the middle of parsing or formatting a file.
401 .Fl W Ns Cm warning .
403 To page manuals to the terminal:
405 .Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less
406 .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
408 To produce HTML manuals with
412 .Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
414 To check over a large set of manuals:
416 .Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]`
418 To produce a series of PostScript manuals for A4 paper:
420 .Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
422 Standard error messages reporting parsing errors are prefixed by
425 .D1 Ar file : line : column : \ level :
428 where the fields have the following meanings:
429 .Bl -tag -width "column"
431 The name of the input file causing the message.
433 The line number in that input file.
434 Line numbering starts at 1.
436 The column number in that input file.
437 Column numbering starts at 1.
438 If the issue is caused by a word, the column number usually
439 points to the first character of the word.
441 The message level, printed in capital letters.
444 Message levels have the following meanings:
445 .Bl -tag -width "warning"
447 The parser is unable to parse a given input file at all.
448 No formatted output is produced from that input file.
450 An input file contains syntax that cannot be safely interpreted,
451 either because it is invalid or because
453 does not implement it yet.
454 By discarding part of the input or inserting missing tokens,
455 the parser is able to continue, and the error does not prevent
456 generation of formatted output, but typically, preparing that
457 output involves information loss, broken document structure
458 or unintended formatting.
460 An input file uses obsolete, discouraged or non-portable syntax.
461 All the same, the meaning of the input is unambiguous and a correct
462 rendering can be produced.
463 Documents causing warnings may render poorly when using other
464 formatting tools instead of
472 levels are hidden unless their level, or a lower level, is requested using a
480 utility may also print messages related to invalid command line arguments
481 or operating system errors, for example when memory is exhausted or
482 input files cannot be read.
483 Such messages do not carry the prefix described above.
485 This section summarises
487 compatibility with GNU troff.
488 Each input and output format is separately noted.
489 .Ss ASCII Compatibility
492 Unrenderable unicode codepoints specified with
494 escapes are printed as
497 In GNU troff, these raise an error.
507 are synonyms, as are \-filled and \-ragged.
509 In historic GNU troff, the
512 macro does not underline when scoped under an
514 in the FILES section.
515 This behaves correctly in
518 A list or display following the
523 does not assert a prior vertical break, just as it doesn't with
533 Words aren't hyphenated.
535 .Ss HTML/XHTML Compatibility
540 escape will revert the font to the previous
542 escape, not to the last rendered decoration, which is now dictated by
543 CSS instead of hard-coded.
544 It also will not span past the current scope,
548 mode, this will work fine.
555 list types render similarly (no break following overreached left-hand
556 side) due to the expressive constraints of HTML.
563 lists render similarly.
575 utility was written by
576 .An Kristaps Dzonsons Aq kristaps@bsd.lv .
582 the maximum size of an element attribute is determined by
584 which is usually 1024 bytes.
585 Be aware of this when setting long link
587 .Fl O Ns Cm style Ns = Ns Ar really/long/link .
589 Nesting elements within next-line element scopes of
599 and cause them to forget the formatting of the prior next-line scope.
603 control character is an alias for the standard macro control character
604 and does not emit a line-break as stipulated in GNU troff.