=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.79 retrieving revision 1.91 diff -u -p -r1.79 -r1.91 --- mandoc/mandoc.1 2010/12/15 15:59:23 1.79 +++ mandoc/mandoc.1 2011/09/17 15:00:51 1.91 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.1,v 1.79 2010/12/15 15:59:23 kristaps Exp $ +.\" $Id: mandoc.1,v 1.91 2011/09/17 15:00:51 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010 Kristaps Dzonsons .\" @@ -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: December 15 2010 $ +.Dd $Mdocdate: September 17 2011 $ .Dt MANDOC 1 .Os .Sh NAME @@ -27,7 +27,7 @@ .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 @@ -158,20 +158,33 @@ utility accepts the following .Fl T arguments, which correspond to output modes: .Bl -tag -width Ds +.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 locale +Encode output using the current locale. +See +.Sx Locale Output . .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 man +Produce output in +.Xr man 7 +format; only useful when applied to +.Fl m Ns Cm doc +input. .It Fl T Ns Cm pdf Produce PDF output. See @@ -183,13 +196,30 @@ See .It Fl T Ns Cm tree Produce an indented parse tree. .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 .Pp If multiple input files are specified, these will be processed by the corresponding filter in-order. +.Ss UTF\-8 Output +Use +.Fl T Ns Cm utf8 +to force a UTF\-8 locale. +See +.Sx Locale Output +for details and options. +.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 ASCII Output Output produced by .Fl T Ns Cm ascii , @@ -210,6 +240,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. @@ -228,18 +261,16 @@ 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 @@ -376,14 +407,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,7 +422,17 @@ 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 @@ -463,6 +504,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 +521,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 +546,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 +578,18 @@ 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 , +.Mt kristaps@bsd.lv . .Sh CAVEATS In .Fl T Ns Cm html @@ -564,12 +614,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