X-Git-Url: https://git.cameronkatri.com/mandoc.git/blobdiff_plain/a0a09dc999ed5bd2a42918fc6f4143ef92b81ba4..4482840eccb9facf57a7a0f8e7d4f447563804dd:/mandoc.1 diff --git a/mandoc.1 b/mandoc.1 index ebd82bdc..b28b2d4e 100644 --- a/mandoc.1 +++ b/mandoc.1 @@ -1,6 +1,6 @@ -.\" $Id: mandoc.1,v 1.64 2010/06/25 19:02:48 kristaps Exp $ +.\" $Id: mandoc.1,v 1.77 2010/08/20 01:02:07 schwarze Exp $ .\" -.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv> +.\" 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,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: June 25 2010 $ +.Dd $Mdocdate: August 20 2010 $ .Dt MANDOC 1 .Os .Sh NAME @@ -23,11 +23,10 @@ .Sh SYNOPSIS .Nm mandoc .Op Fl V -.Op Fl f Ns Ar option .Op Fl m Ns Ar format .Op Fl O Ns Ar option .Op Fl T Ns Ar output -.Op Fl W Ns Ar err +.Op Fl W Ns Ar level .Op Ar file... .Sh DESCRIPTION The @@ -37,11 +36,6 @@ utility formats 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 @@ -51,9 +45,6 @@ Defaults to .Fl m Ns Cm andoc . .It Fl O Ns Ar option Comma-separated output options. -See -.Sx Output Options -for details. .It Fl T Ns Ar output Output format. See @@ -63,18 +54,41 @@ 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 +.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 -to print warnings, -.Fl W Ns Cm error -for warnings to be considered errors and cause utility -termination. -Multiple -.Fl W -arguments may be comma-separated, such as -.Fl W Ns Cm error , 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. @@ -94,8 +108,6 @@ text from stdin, implying and produces .Fl T Ns Cm ascii output. -.Pp -.Ex -std mandoc .Ss Input Formats The .Nm @@ -144,8 +156,7 @@ 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 Cm ascii Produce 7-bit ASCII output, backspace-encoded for bold and underline @@ -160,9 +171,11 @@ See .It Fl T Ns Cm lint Parse only: produce no output. Implies -.Fl W Ns Cm all -and -.Fl f Ns Cm strict . +.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 @@ -177,43 +190,60 @@ See .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. +.Ss ASCII Output +Output produced by +.Fl T Ns Cm ascii , +which is the default, 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 Fl f Ns Cm ign-errors -When parsing multiple files, don't halt when one errors out. -Useful with -.Fl T Ns Cm lint -over a large set of manuals passed on the command line. -.It Fl f Ns Cm ign-escape -Ignore invalid escape sequences. -This is the default, but the option can be used to override an earlier -.Fl f Ns Cm strict . -.It Fl f Ns Cm 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 Cm no-ign-escape -Do not ignore invalid escape sequences. -.It Fl f Ns Cm no-ign-macro -Do not ignore unknown macros at the start of input lines. -.It Fl f Ns Cm strict -Implies -.Fl f Ns Cm no-ign-escape -and -.Fl f Ns Cm no-ign-macro . +.It Cm width Ns = Ns Ar width +The output width is set to +.Ar width , +which will normalise to \(>=60. .El -.Ss Output Options +.Ss HTML Output +Output produced by +.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 -.Fl T Ns Ar html -and -.Fl T Ns Ar xhtml -modes accept the following +.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 Cm ascii . +.Pp +Special characters are rendered in decimal-encoded UTF-8. +.Pp +The following .Fl O -arguments: +arguments are accepted: .Bl -tag -width Ds .It Cm includes Ns = Ns Ar fmt The string @@ -251,111 +281,48 @@ 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 -The -.Fl T Ns Ar ascii -mode accepts the following +Special characters are rendered as in +.Sx ASCII Output . +.Pp +The following .Fl O -argument: +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. +.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 -.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 Cm ascii , -which is the default, 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. -.Ss HTML Output -Output produced by -.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 Cm ascii . -.Pp -Special characters are rendered in decimal-encoded UTF-8. -.Ss PostScript Output -PostScript Level 2 pages may be generated by -.Fl T Ns Cm ps . -Output pages are US-letter sized (215.9 x 279.4 mm) and rendered in -fixed, 10-point Courier font. +.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 Cm xhtml @@ -365,10 +332,51 @@ 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\*(Gt&1 | less +.D1 $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less .D1 $ mandoc mandoc.1 mdoc.3 mdoc.7 | less .Pp To produce HTML manuals with @@ -379,22 +387,83 @@ as the style-sheet: .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 +.D1 $ 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 Cm ascii . -.It -The .Sq \&Bd \-literal and .Sq \&Bd \-unfilled @@ -404,9 +473,7 @@ in .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 @@ -432,11 +499,6 @@ 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 @@ -499,17 +561,6 @@ Be aware of this when setting long link formats such as .Fl O Ns Cm style Ns = Ns Ar really/long/link . .Pp -The -.Fl T Ns Cm html -and -.Fl T Ns Cm xhtml -output modes don't render the -.Sq \es -font size escape documented in -.Xr mdoc 7 -and -.Xr man 7 . -.Pp Nesting elements within next-line element scopes of .Fl m Ns Cm an , such as