X-Git-Url: https://git.cameronkatri.com/mandoc.git/blobdiff_plain/6e833a20a85c3db8d206be179927b1591339d982..2a677979d5b94a58bb3b5bac12084fa09a6cfcdd:/mandoc.1 diff --git a/mandoc.1 b/mandoc.1 index 5ab24126..843f3d73 100644 --- a/mandoc.1 +++ b/mandoc.1 @@ -1,6 +1,6 @@ -.\" $Id: mandoc.1,v 1.51 2010/03/22 14:03:03 kristaps Exp $ +.\" $Id: mandoc.1,v 1.84 2011/01/04 23:32:21 kristaps Exp $ .\" -.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se> +.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv> .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -14,79 +14,88 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 22 2010 $ +.Dd $Mdocdate: January 4 2011 $ .Dt MANDOC 1 .Os -. -. .Sh NAME .Nm mandoc .Nd format and display UNIX manuals -. -. .Sh SYNOPSIS .Nm mandoc -.Op Fl f Ns Ar option... +.Op Fl V .Op Fl m Ns Ar format -.Op Fl O Ns Ar option... +.Op Fl O Ns Ar option .Op Fl T Ns Ar output -.Op Fl V -.Op Fl W Ns Ar err... -.Op Ar infile... -. -. +.Op Fl W Ns Ar level +.Op Ar file... .Sh DESCRIPTION The .Nm utility formats .Ux -manual pages for display. The arguments are as follows: -. +manual pages for display. +The arguments are as follows: .Bl -tag -width Ds -.It Fl f Ns Ar option... -Comma-separated compiler options. See -.Sx Compiler Options -for details. -. .It Fl m Ns Ar format -Input format. See +Input format. +See .Sx Input Formats -for available formats. Defaults to -.Fl m Ns Ar andoc . -. -.It Fl O Ns Ar option... -Comma-separated output options. See -.Sx Output Options -for details. -. +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 +Output format. +See .Sx Output Formats -for available formats. Defaults to -.Fl T Ns Ar ascii . -. +for available formats. +Defaults to +.Fl T Ns Cm ascii . .It Fl V Print version and exit. -. -.It Fl W Ns Ar err... -Comma-separated warning options. Use -.Fl W Ns Ar all -to print warnings, -.Fl W Ns Ar error -for warnings to be considered errors and cause utility -termination. Multiple -.Fl W -arguments may be comma-separated, such as -.Fl W Ns Ar error,all . -. -.It Ar infile... -Read input from zero or more -.Ar infile . -If unspecified, reads from stdin. If multiple files are specified, +.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 fatal . +The default is +.Fl W Ns Cm fatal ; +.Fl W Ns Cm all +is an alias for +.Fl W Ns Cm warning . +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 By default, .Nm @@ -95,15 +104,10 @@ reads or .Xr man 7 text from stdin, implying -.Fl m Ns Ar andoc , +.Fl m Ns Cm andoc , and produces -.Fl T Ns Ar ascii +.Fl T Ns Cm ascii output. -. -.Pp -.Ex -std mandoc -. -. .Ss Input Formats The .Nm @@ -112,20 +116,20 @@ utility accepts and .Xr man 7 input with -.Fl m Ns Ar doc +.Fl m Ns Cm doc and -.Fl m Ns Ar an , -respectively. The +.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 Ar andoc , +.Fl m Ns Cm andoc , which is also the default, determines encoding on-the-fly: if the first non-comment macro is .Sq \&Dd @@ -136,183 +140,58 @@ the parser is used; otherwise, the .Xr man 7 parser is used. -. .Pp If multiple files are specified with -.Fl m Ns Ar andoc , -each has its file-type determined this way. If multiple files are +.Fl m Ns Cm andoc , +each has its file-type determined this way. +If multiple files are specified and -.Fl m Ns Ar doc +.Fl m Ns Cm doc or -.Fl m Ns Ar an +.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 (see -.Sx OUTPUT ) : -. +arguments, which correspond to output modes: .Bl -tag -width Ds -.It Fl T Ns Ar ascii -Produce 7-bit ASCII output, backspace-encoded for bold and underline -styles. This is the default. See +.It Fl T Ns Cm ascii +Produce 7-bit ASCII output. +This is the default. +See .Sx ASCII Output . -. -.It Fl T Ns Ar html -Produce strict HTML-4.01 output, with a sane default style. See +.It Fl T Ns Cm html +Produce strict CSS1/HTML-4.01 output. +See .Sx HTML Output . -. -.It Fl T Ns Ar xhtml -Produce strict XHTML-1.0 output, with a sane default style. See -.Sx XHTML Output . -. -.It Fl T Ns Ar tree -Produce an indented parse tree. -. -.It Fl T Ns Ar lint +.It Fl T Ns Cm lint Parse only: produce no output. +Implies +.Fl W Ns Cm warning . +.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 xhtml +Produce strict CSS1/XHTML-1.0 output. +See +.Sx XHTML Output . .El -. .Pp If multiple input files are specified, these will be processed by the corresponding filter in-order. -. -. -.Ss Compiler Options -Default compiler behaviour may be overridden with the -.Fl f -flag. -. -.Bl -tag -width Ds -.It Fl f Ns Ar ign-scope -When rewinding the scope of a block macro, forces the compiler to ignore -scope violations. This can seriously mangle the resulting tree. -.Pq mdoc only -. -.It Fl f Ns Ar ign-escape -Ignore invalid escape sequences. -This is the default, but the option can be used to override an earlier -.Fl f Ns Ar strict . -. -.It Fl f Ns Ar no-ign-escape -Don't ignore invalid escape sequences. -. -.It Fl f Ns Ar no-ign-macro -Do not ignore unknown macros at the start of input lines. -. -.It Fl f Ns Ar no-ign-chars -Do not ignore disallowed characters. -. -.It Fl f Ns Ar strict -Implies -.Fl f Ns Ar no-ign-escape , -.Fl f Ns Ar no-ign-macro -and -.Fl f Ns Ar no-ign-chars . -. -.It Fl f Ns Ar ign-errors -Don't halt when encountering parse errors. Useful with -.Fl T Ns Ar lint -over a large set of manuals passed on the command line. -.El -. -. -.Ss Output Options -For the time being, only -.Fl T Ns Ar html -accepts output options: -.Bl -tag -width Ds -.It Fl O Ns Ar style=style.css -The file -.Ar style.css -is used for an external style-sheet. This must be a valid absolute or -relative URI. -.It Fl O Ns Ar includes=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 Fl O Ns Ar man=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. -.El -. -. -.Sh OUTPUT -This section documents output details of -.Nm . -In general, output conforms to the traditional manual style of a header, -a body composed of sections and sub-sections, and a footer. -.Pp -The text style of output characters (non-macro characters, punctuation, -and white-space) is dictated by context. -.Pp -White-space is generally stripped from input. This can be changed with -character escapes (specified in -.Xr mandoc_char 7 ) -or literal modes (specified in -.Xr mdoc 7 -and -.Xr man 7 ) . -.Pp -If non-macro punctuation is set apart from words, such as in the phrase -.Dq to be \&, or not to be , -it's processed by -.Nm , -regardless of output format, according to the following rules: opening -punctuation -.Po -.Sq \&( , -.Sq \&[ , -and -.Sq \&{ -.Pc -is not followed by a space; closing punctuation -.Po -.Sq \&. , -.Sq \&, , -.Sq \&; , -.Sq \&: , -.Sq \&? , -.Sq \&! , -.Sq \&) , -.Sq \&] -and -.Sq \&} -.Pc -is not preceded by white-space. -. -.Pp -If the input is -.Xr mdoc 7 , -however, these rules are also applied to macro arguments when appropriate. -. -. .Ss ASCII Output Output produced by -.Fl T Ns Ar ascii , +.Fl T Ns Cm ascii , which is the default, is rendered in standard 7-bit ASCII documented in .Xr ascii 7 . .Pp @@ -323,7 +202,8 @@ 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 +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 @@ -332,126 +212,292 @@ 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 width Ns = Ns Ar width +The output width is set to +.Ar width , +which will normalise to \(>=60. +.El .Ss HTML Output Output produced by -.Fl T Ns Ar html +.Fl T Ns Cm html conforms to HTML-4.01 strict. .Pp -Font styles and page structure are applied using CSS2. By default, no -font style is applied to any text, although CSS2 is hard-coded to format -the basic structure of output. -.Pp The .Pa example.style.css -file documents the range of styles applied to output and, if used, will -cause rendered documents to appear as they do in -.Fl T Ns Ar ascii . +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 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 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 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 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 XHTML Output Output produced by -.Fl T Ns Ar xhtml +.Fl T Ns Cm xhtml conforms to XHTML-1.0 strict. .Pp See .Sx HTML Output for details; beyond generating XHTML tags instead of HTML tags, these output modes are identical. -. -. +.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 fatal error, and +.Fl W Ns Cm error +or +.Fl W Ns Cm warning +was specified. +.It 4 +A fatal parsing error occurred. +.It 5 +Invalid command line arguments were specified. +No input files have been read. +.It 6 +An operating system error occurred, for example memory exhaustion or an +error accessing input files. +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 -.D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less -.D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less -. +.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 -.D1 % mandoc \-Thtml -Ostyle=style.css mdoc.7 > mdoc.7.html +.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 \-fign-errors `find /usr/src -name \e*\e.[1-9]` -. -. +.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 +.Sh DIAGNOSTICS +Standard error messages reporting parsing errors are prefixed by +.Pp +.Sm off +.D1 Ar file : line : column : \ level : +.Sm on +.Pp +where the fields have the following meanings: +.Bl -tag -width "column" +.It Ar file +The name of the input file causing the message. +.It Ar line +The line number in that input file. +Line numbering starts at 1. +.It Ar column +The column number in that input file. +Column numbering starts at 1. +If the issue is caused by a word, the column number usually +points to the first character of the word. +.It Ar level +The message level, printed in capital letters. +.El +.Pp +Message levels have the following meanings: +.Bl -tag -width "warning" +.It Cm fatal +The parser is unable to parse a given input file at all. +No formatted output is produced from that input file. +.It Cm error +An input file contains syntax that cannot be safely interpreted, +either because it is invalid or because +.Nm +does not implement it yet. +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. +.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 +and +.Cm error +levels are hidden unless their level, or a lower level, is requested using a +.Fl W +option or +.Fl T Ns Cm lint +output mode. +.Pp +The +.Nm +utility may also print messages related to invalid command line arguments +or operating system errors, for example when memory is exhausted or +input files cannot be read. +Such messages do not carry the prefix described above. .Sh COMPATIBILITY This section summarises .Nm -compatibility with -.Xr groff 1 . +compatibility with GNU troff. Each input and output format is separately noted. -. -. .Ss ASCII Compatibility .Bl -bullet -compact .It The -.Sq \e~ -special character doesn't produce expected behaviour in -.Fl T Ns Ar ascii . -. -.It -The .Sq \&Bd \-literal and .Sq \&Bd \-unfilled macros of .Xr mdoc 7 in -.Fl T Ns Ar ascii +.Fl T Ns Cm ascii are synonyms, as are \-filled and \-ragged. -. .It -In -.Xr groff 1 , -the +In GNU troff, the .Sq \&Pa .Xr mdoc 7 macro does not underline when scoped under an .Sq \&It -in the FILES section. This behaves correctly in +in the FILES section. +This behaves correctly in .Nm . -. .It -A list or display following +A list or display following the .Sq \&Ss .Xr mdoc 7 macro in -.Fl T Ns Ar ascii +.Fl T Ns Cm ascii does not assert a prior vertical break, just as it doesn't with .Sq \&Sh . -. .It The .Sq \&na .Xr man 7 macro in -.Fl T Ns Ar ascii +.Fl T Ns Cm ascii has no effect. -. .It Words aren't hyphenated. -. -.It -In normal mode (not a literal block), blocks of spaces aren't preserved, -so double spaces following sentence closure are reduced to a single space; -.Xr groff 1 -retains spaces. -. .It Sentences are unilaterally monospaced. .El -. -. .Ss HTML/XHTML Compatibility .Bl -bullet -compact .It @@ -460,8 +506,10 @@ The escape will revert the font to the previous .Sq \ef escape, not to the last rendered decoration, which is now dictated by -CSS instead of hard-coded. It also will not span past the current -scope, for the same reason. Note that in +CSS instead of hard-coded. +It also will not span past the current scope, +for the same reason. +Note that in .Sx ASCII Output mode, this will work fine. .It @@ -472,7 +520,6 @@ and .Sq \&Bl \-tag list types render similarly (no break following overreached left-hand side) due to the expressive constraints of HTML. -. .It The .Xr man 7 @@ -481,59 +528,42 @@ and .Sq TP lists render similarly. .El -. -. .Sh SEE ALSO +.Xr man 7 , .Xr mandoc_char 7 , .Xr mdoc 7 , -.Xr man 7 -. +.Xr roff 7 , +.Xr tbl 7 .Sh AUTHORS The .Nm utility was written by -.An Kristaps Dzonsons Aq kristaps@kth.se . -. -. +.An Kristaps Dzonsons Aq kristaps@bsd.lv . .Sh CAVEATS -The -.Fl T Ns Ar html -and -.Fl T Ns Ar xhtml -CSS2 styling used for -.Fl m Ns Ar doc -input lists does not render properly in older browsers, such as Internet -Explorer 6 and earlier. -.Pp In -.Fl T Ns Ar html +.Fl T Ns Cm html and -.Fl T Ns Ar xhtml , +.Fl T Ns Cm xhtml , 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, e.g., -.Fl O Ns Ar style=really/long/link . -.Pp -The -.Fl T Ns Ar html -and -.Fl T Ns Ar xhtml -output modes don't render the -.Sq \es -font size escape documented in -.Xr mdoc 7 -and -.Xr man 7 . +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 . .Pp Nesting elements within next-line element scopes of -.Fl m Ar Ns an , +.Fl m Ns Cm an , such as .Sq br within an empty .Sq B , will confuse -.Fl T Ns Ar html +.Fl T Ns Cm html and -.Fl T Ns Ar xhtml -and cause it to forget the formatting. +.Fl T Ns Cm xhtml +and cause them to forget the formatting of the prior next-line scope. +.Pp +The +.Sq \(aq +control character is an alias for the standard macro control character +and does not emit a line-break as stipulated in GNU troff.