=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.79 retrieving revision 1.105 diff -u -p -r1.79 -r1.105 --- mandoc/mandoc.1 2010/12/15 15:59:23 1.79 +++ mandoc/mandoc.1 2014/06/23 22:03:30 1.105 @@ -1,6 +1,7 @@ -.\" $Id: mandoc.1,v 1.79 2010/12/15 15:59:23 kristaps Exp $ +.\" $Id: mandoc.1,v 1.105 2014/06/23 22:03:30 schwarze Exp $ .\" -.\" Copyright (c) 2009, 2010 Kristaps Dzonsons +.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons +.\" Copyright (c) 2012, 2014 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 @@ -14,7 +15,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: December 15 2010 $ +.Dd $Mdocdate: June 23 2014 $ .Dt MANDOC 1 .Os .Sh NAME @@ -23,19 +24,44 @@ .Sh SYNOPSIS .Nm mandoc .Op Fl V +.Sm off +.Op Fl I Cm os Li = Ar name +.Sm on .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 file... +.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 ascii +output. +.Pp The arguments are as follows: .Bl -tag -width Ds +.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 +macro. .It Fl m Ns Ar format Input format. See @@ -96,18 +122,6 @@ If multiple files are specified, .Nm will halt with the first failed parse. .El -.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 ascii -output. .Ss Input Formats The .Nm @@ -157,21 +171,30 @@ The utility accepts the following .Fl T arguments, which correspond to output modes: -.Bl -tag -width Ds +.Bl -tag -width "-Tlocale" .It Fl T Ns Cm ascii -Produce 7-bit ASCII output, backspace-encoded for bold and underline -styles. +Produce 7-bit ASCII output. This is the default. See .Sx ASCII Output . .It Fl T Ns Cm html -Produce strict HTML-4.01 output, with a sane default style. +Produce strict CSS1/HTML-4.01 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. +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 @@ -182,8 +205,12 @@ 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 -Produce strict XHTML-1.0 output, with a sane default style. +Produce strict CSS1/XHTML-1.0 output. See .Sx XHTML Output . .El @@ -210,6 +237,9 @@ Emboldened characters are rendered as The special characters documented in .Xr mandoc_char 7 are rendered best-effort in an ASCII equivalent. +If no equivalent is found, +.Sq \&? +is used instead. .Pp Output width is limited to 78 visible columns unless literal input lines exceed this limit. @@ -218,6 +248,15 @@ 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 , @@ -228,23 +267,36 @@ 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 . +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. +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 +.Aq !DOCTYPE +declaration and the +.Aq html , +.Aq head , +and +.Aq body +elements and only emit the subtree below the +.Aq body +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 , @@ -281,6 +333,48 @@ 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 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 @@ -315,14 +409,13 @@ 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 . +.Ss UTF\-8 Output +Use +.Fl T Ns Cm utf8 +to force a UTF\-8 locale. See -.Sx PostScript Output -for -.Fl O -arguments and defaults. +.Sx Locale Output +for details and options. .Ss XHTML Output Output produced by .Fl T Ns Cm xhtml @@ -376,14 +469,14 @@ output mode implies .Sh EXAMPLES To page manuals to the terminal: .Pp -.D1 $ mandoc \-Wall,stop mandoc.1 2\*(Gt&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 \*(Gt 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 @@ -391,13 +484,21 @@ To check over a large set of manuals: .Pp To produce a series of PostScript manuals for A4 paper: .Pp -.D1 $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps +.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 Standard error messages reporting parsing errors are prefixed by .Pp -.Sm off -.D1 Ar file : line : column : \ level : -.Sm on +.D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : .Pp where the fields have the following meanings: .Bl -tag -width "column" @@ -415,8 +516,17 @@ points to the first character of the word. The message level, printed in capital letters. .El .Pp +The +.Ar line +and +.Ar column +fields are omitted when meaningless. +.Pp Message levels have the following meanings: .Bl -tag -width "warning" +.It Cm syserr +Opening or reading an input file failed, so the parser cannot +even be started and no output is produced from that input file. .It Cm fatal The parser is unable to parse a given input file at all. No formatted output is produced from that input file. @@ -452,9 +562,8 @@ output mode. 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. +or operating system errors, for example when memory is exhausted. +Such messages may not carry the prefix described above. .Sh COMPATIBILITY This section summarises .Nm @@ -463,6 +572,13 @@ Each input and output format is separately noted. .Ss ASCII Compatibility .Bl -bullet -compact .It +Unrenderable unicode codepoints specified with +.Sq \e[uNNNN] +escapes are printed as +.Sq \&? +in mandoc. +In GNU troff, these raise an error. +.It The .Sq \&Bd \-literal and @@ -473,7 +589,7 @@ in .Fl T Ns Cm ascii are synonyms, as are \-filled and \-ragged. .It -In GNU troff, the +In historic GNU troff, the .Sq \&Pa .Xr mdoc 7 macro does not underline when scoped under an @@ -498,8 +614,6 @@ macro in has no effect. .It Words aren't hyphenated. -.It -Sentences are unilaterally monospaced. .El .Ss HTML/XHTML Compatibility .Bl -bullet -compact @@ -532,14 +646,17 @@ and lists render similarly. .El .Sh SEE ALSO +.Xr eqn 7 , .Xr man 7 , .Xr mandoc_char 7 , -.Xr mdoc 7 +.Xr mdoc 7 , +.Xr roff 7 , +.Xr tbl 7 .Sh AUTHORS The .Nm utility was written by -.An Kristaps Dzonsons Aq kristaps@bsd.lv . +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . .Sh CAVEATS In .Fl T Ns Cm html @@ -564,12 +681,6 @@ and .Fl T Ns Cm xhtml and cause them to forget the formatting of the prior next-line scope. .Pp -The -.Sq i -macro in -.Fl m Ns Cm an -should italicise all subsequent text if a line argument is not provided. -This behaviour is not implemented. The .Sq \(aq control character is an alias for the standard macro control character