.\" $OpenBSD: mandoc.1,v 1.75 2015/01/29 00:33:14 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" Copyright (c) 2012, 2014, 2015 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd $Mdocdate: January 29 2015 $ .Dt MANDOC 1 .Os .Sh NAME .Nm mandoc .Nd format and display UNIX manuals .Sh SYNOPSIS .Nm mandoc .Op Fl acfhklV .Sm off .Op Fl I Cm os Li = Ar name .Sm on .Op Fl K Ns Ar encoding .Op Fl m Ns Ar format .Op Fl O Ns Ar option .Op Fl T Ns Ar output .Op Fl W Ns Ar level .Op Ar .Sh DESCRIPTION The .Nm utility formats .Ux manual pages for display. .Pp By default, .Nm reads .Xr mdoc 7 or .Xr man 7 text from stdin, implying .Fl m Ns Cm andoc , and produces .Fl T Ns Cm locale output. .Pp The options are as follows: .Bl -tag -width Ds .It Fl a If the standard output is a terminal device and .Fl c is not specified, use .Xr more 1 to paginate the output, just like .Xr man 1 would. .It Fl c Copy the formatted manual pages to the standard output without using .Xr more 1 to paginate them. This is the default. It can be specified to override .Fl a . .It Fl f A synonym for .Xr whatis 1 . This overrides any earlier .Fl k and .Fl l options. .Sm off .It Fl I Cm os Li = Ar name .Sm on Override the default operating system .Ar name for the .Xr mdoc 7 .Sq \&Os and for the .Xr man 7 .Sq \&TH macro. .It Fl h Display only the SYNOPSIS lines. Implies .Fl c . .It Fl K Ns Ar encoding Specify the input encoding. The supported .Ar encoding arguments are .Cm us-ascii , .Cm iso-8859-1 , and .Cm utf-8 . If not specified, autodetection uses the first match: .Bl -tag -width iso-8859-1 .It Cm utf-8 if the first three bytes of the input file are the UTF-8 byte order mark (BOM, 0xefbbbf) .It Ar encoding if the first or second line of the input file matches the .Sy emacs mode line format .Pp .D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*- .It Cm utf-8 if the first non-ASCII byte in the file introduces a valid UTF-8 sequence .It Cm iso-8859-1 otherwise .El .It Fl k A synonym for .Xr apropos 1 . This overrides any earlier .Fl f and .Fl l options. .It Fl l A synonym for .Fl a . Also reverts any earlier .Fl f and .Fl k options. .It Fl m Ns Ar format Input format. See .Sx Input Formats for available formats. Defaults to .Fl m Ns Cm andoc . .It Fl O Ns Ar option Comma-separated output options. .It Fl T Ns Ar output Output format. See .Sx Output Formats for available formats. Defaults to .Fl T Ns Cm locale . .It Fl V Print version and exit. .It Fl W Ns Ar level Specify the minimum message .Ar level to be reported on the standard error output and to affect the exit status. The .Ar level can be .Cm warning , .Cm error , or .Cm unsupp ; .Cm all is an alias for .Cm warning . By default, .Nm is silent. See .Sx EXIT STATUS and .Sx DIAGNOSTICS for details. .Pp The special option .Fl W Ns Cm stop tells .Nm to exit after parsing a file that causes warnings or errors of at least the requested level. No formatted output will be produced from that file. If both a .Ar level and .Cm stop are requested, they can be joined with a comma, for example .Fl W Ns Cm error , Ns Cm stop . .It Ar file Read input from zero or more files. If unspecified, reads from stdin. If multiple files are specified, .Nm will halt with the first failed parse. .El .Pp In .Fl f and .Fl k mode, .Nm also supports the options .Fl CMmOSsw described in the .Xr apropos 1 manual. .Ss Input Formats The .Nm utility accepts .Xr mdoc 7 and .Xr man 7 input with .Fl m Ns Cm doc and .Fl m Ns Cm an , respectively. The .Xr mdoc 7 format is .Em strongly recommended; .Xr man 7 should only be used for legacy manuals. .Pp A third option, .Fl m Ns Cm andoc , which is also the default, determines encoding on-the-fly: if the first non-comment macro is .Sq \&Dd or .Sq \&Dt , the .Xr mdoc 7 parser is used; otherwise, the .Xr man 7 parser is used. .Pp If multiple files are specified with .Fl m Ns Cm andoc , each has its file-type determined this way. If multiple files are specified and .Fl m Ns Cm doc or .Fl m Ns Cm an is specified, then this format is used exclusively. .Ss Output Formats The .Nm utility accepts the following .Fl T arguments, which correspond to output modes: .Bl -tag -width "-Tlocale" .It Fl T Ns Cm ascii Produce 7-bit ASCII output. See .Sx ASCII Output . .It Fl T Ns Cm html Produce HTML5, CSS1, and MathML output. See .Sx HTML Output . .It Fl T Ns Cm lint Parse only: produce no output. Implies .Fl W Ns Cm warning . .It Fl T Ns Cm locale Encode output using the current locale. This is the default. See .Sx Locale Output . .It Fl T Ns Cm man Produce .Xr man 7 format output. See .Sx Man Output . .It Fl T Ns Cm pdf Produce PDF output. See .Sx PDF Output . .It Fl T Ns Cm ps Produce PostScript output. See .Sx PostScript Output . .It Fl T Ns Cm tree Produce an indented parse tree. .It Fl T Ns Cm utf8 Encode output in the UTF\-8 multi-byte format. See .Sx UTF\-8 Output . .It Fl T Ns Cm xhtml This is a synonym for .Fl T Ns Cm html . .El .Pp If multiple input files are specified, these will be processed by the corresponding filter in-order. .Ss ASCII Output Output produced by .Fl T Ns Cm ascii is rendered in standard 7-bit ASCII documented in .Xr ascii 7 . .Pp Font styles are applied by using back-spaced encoding such that an underlined character .Sq c is rendered as .Sq _ Ns \e[bs] Ns c , where .Sq \e[bs] is the back-space character number 8. Emboldened characters are rendered as .Sq c Ns \e[bs] Ns c . .Pp The special characters documented in .Xr mandoc_char 7 are rendered best-effort in an ASCII equivalent. .Pp Output width is limited to 78 visible columns unless literal input lines exceed this limit. .Pp The following .Fl O arguments are accepted: .Bl -tag -width Ds .It Cm indent Ns = Ns Ar indent The left margin for normal text is set to .Ar indent blank characters instead of the default of five for .Xr mdoc 7 and seven for .Xr man 7 . Increasing this is not recommended; it may result in degraded formatting, for example overfull lines or ugly line breaks. .It Cm width Ns = Ns Ar width The output width is set to .Ar width , which will normalise to \(>=58. .El .Ss HTML Output Output produced by .Fl T Ns Cm html conforms to HTML5 using optional self-closing tags. Default styles use only CSS1. Equations rendered from .Xr eqn 7 blocks use MathML. .Pp The .Pa example.style.css file documents style-sheet classes available for customising output. If a style-sheet is not specified with .Fl O Ns Ar style , .Fl T Ns Cm html defaults to simple output (via an embedded style-sheet) readable in any graphical or text-based web browser. .Pp Special characters are rendered in decimal-encoded UTF\-8. .Pp The following .Fl O arguments are accepted: .Bl -tag -width Ds .It Cm fragment Omit the declaration and the , , and elements and only emit the subtree below the element. The .Cm style argument will be ignored. This is useful when embedding manual content within existing documents. .It Cm includes Ns = Ns Ar fmt The string .Ar fmt , for example, .Ar ../src/%I.html , is used as a template for linked header files (usually via the .Sq \&In macro). Instances of .Sq \&%I are replaced with the include filename. The default is not to present a hyperlink. .It Cm man Ns = Ns Ar fmt The string .Ar fmt , for example, .Ar ../html%S/%N.%S.html , is used as a template for linked manuals (usually via the .Sq \&Xr macro). Instances of .Sq \&%N and .Sq %S are replaced with the linked manual's name and section, respectively. If no section is included, section 1 is assumed. The default is not to present a hyperlink. .It Cm style Ns = Ns Ar style.css The file .Ar style.css is used for an external style-sheet. This must be a valid absolute or relative URI. .El .Ss Locale Output Locale-depending output encoding is triggered with .Fl T Ns Cm locale . This is the default. .Pp This option is not available on all systems: systems without locale support, or those whose internal representation is not natively UCS-4, will fall back to .Fl T Ns Cm ascii . See .Sx ASCII Output for font style specification and available command-line arguments. .Ss Man Output Translate input format into .Xr man 7 output format. This is useful for distributing manual sources to legacy systems lacking .Xr mdoc 7 formatters. .Pp If .Xr mdoc 7 is passed as input, it is translated into .Xr man 7 . If the input format is .Xr man 7 , the input is copied to the output, expanding any .Xr roff 7 .Sq so requests. The parser is also run, and as usual, the .Fl W level controls which .Sx DIAGNOSTICS are displayed before copying the input to the output. .Ss PDF Output PDF-1.1 output may be generated by .Fl T Ns Cm pdf . See .Sx PostScript Output for .Fl O arguments and defaults. .Ss PostScript Output PostScript .Qq Adobe-3.0 Level-2 pages may be generated by .Fl T Ns Cm ps . Output pages default to letter sized and are rendered in the Times font family, 11-point. Margins are calculated as 1/9 the page length and width. Line-height is 1.4m. .Pp Special characters are rendered as in .Sx ASCII Output . .Pp The following .Fl O arguments are accepted: .Bl -tag -width Ds .It Cm paper Ns = Ns Ar name The paper size .Ar name may be one of .Ar a3 , .Ar a4 , .Ar a5 , .Ar legal , or .Ar letter . You may also manually specify dimensions as .Ar NNxNN , width by height in millimetres. If an unknown value is encountered, .Ar letter is used. .El .Ss UTF\-8 Output Use .Fl T Ns Cm utf8 to force a UTF\-8 locale. See .Sx Locale Output for details and options. .Sh ENVIRONMENT .Bl -tag -width MANPAGER .It Ev MANPAGER Any non-empty value of the environment variable .Ev MANPAGER will be used instead of the standard pagination program, .Xr more 1 . .It Ev PAGER Specifies the pagination program to use when .Ev MANPAGER is not defined. If neither PAGER nor MANPAGER is defined, .Pa /usr/bin/more Fl s will be used. .El .Sh EXIT STATUS The .Nm utility exits with one of the following values, controlled by the message .Ar level associated with the .Fl W option: .Pp .Bl -tag -width Ds -compact .It 0 No warnings or errors occurred, or those that did were ignored because they were lower than the requested .Ar level . .It 2 At least one warning occurred, but no error, and .Fl W Ns Cm warning was specified. .It 3 At least one parsing error occurred, but no unsupported feature was encountered, and .Fl W Ns Cm error or .Fl W Ns Cm warning was specified. .It 4 At least one unsupported feature was encountered, and .Fl W Ns Cm unsupp , .Fl W Ns Cm error or .Fl W Ns Cm warning was specified. .It 5 Invalid command line arguments were specified. No input files have been read. .It 6 An operating system error occurred, for example exhaustion of memory, file descriptors, or process table entries. Such errors cause .Nm to exit at once, possibly in the middle of parsing or formatting a file. .El .Pp Note that selecting .Fl T Ns Cm lint output mode implies .Fl W Ns Cm warning . .Sh EXAMPLES To page manuals to the terminal: .Pp .Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less .Pp To produce HTML manuals with .Ar style.css as the style-sheet: .Pp .Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html .Pp To check over a large set of manuals: .Pp .Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]` .Pp To produce a series of PostScript manuals for A4 paper: .Pp .Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps .Pp Convert a modern .Xr mdoc 7 manual to the older .Xr man 7 format, for use on systems lacking an .Xr mdoc 7 parser: .Pp .Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man .Sh DIAGNOSTICS Messages displayed by .Nm follow this format: .Pp .D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args .Pp Line and column numbers start at 1. Both are omitted for messages referring to an input file as a whole. Macro names and arguments are omitted where meaningless. Fatal messages about invalid command line arguments or operating system errors, for example when memory is exhausted, may also omit the .Ar file and .Ar level fields. .Pp Message levels have the following meanings: .Bl -tag -width "warning" .It Cm unsupp An input file uses unsupported low-level .Xr roff 7 features. The output may be incomplete and/or misformatted, so using GNU troff instead of .Nm to process the file may be preferable. .It Cm error An input file contains invalid syntax that cannot be safely interpreted. By discarding part of the input or inserting missing tokens, the parser is able to continue, and the error does not prevent generation of formatted output, but typically, preparing that output involves information loss, broken document structure or unintended formatting, no matter whether .Nm or GNU troff is used. In many cases, the output of .Nm and GNU troff is identical, but in some, .Nm is more resilient than GNU troff with respect to malformed input. .Pp Non-existent or unreadable input files are also reported on the .Cm error level. In that case, the parser cannot even be started and no output is produced from those input files. .It Cm warning An input file uses obsolete, discouraged or non-portable syntax. All the same, the meaning of the input is unambiguous and a correct rendering can be produced. Documents causing warnings may render poorly when using other formatting tools instead of .Nm . .El .Pp Messages of the .Cm warning , .Cm error , and .Cm unsupp levels except those about non-existent or unreadable input files are hidden unless their level, or a lower level, is requested using a .Fl W option or .Fl T Ns Cm lint output mode. .Sh SEE ALSO .Xr apropos 1 , .Xr man 1 , .Xr eqn 7 , .Xr man 7 , .Xr mandoc_char 7 , .Xr mdoc 7 , .Xr roff 7 , .Xr tbl 7 .Sh AUTHORS The .Nm utility was written by .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv and is maintained by .An Ingo Schwarze Aq Mt schwarze@openbsd.org . .Sh BUGS In .Fl T Ns Cm html , the maximum size of an element attribute is determined by .Dv BUFSIZ , which is usually 1024 bytes. Be aware of this when setting long link formats such as .Fl O Ns Cm style Ns = Ns Ar really/long/link .