version 1.81, 2010/12/16 23:07:01 |
version 1.91, 2011/09/17 15:00:51 |
|
|
.Op Fl O Ns Ar option |
.Op Fl O Ns Ar option |
.Op Fl T Ns Ar output |
.Op Fl T Ns Ar output |
.Op Fl W Ns Ar level |
.Op Fl W Ns Ar level |
.Op Ar file... |
.Op Ar |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
.Nm |
.Nm |
Line 158 utility accepts the following |
|
Line 158 utility accepts the following |
|
.Fl T |
.Fl T |
arguments, which correspond to output modes: |
arguments, which correspond to output modes: |
.Bl -tag -width Ds |
.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 |
.It Fl T Ns Cm ascii |
Produce 7-bit ASCII output. |
Produce 7-bit ASCII output. |
This is the default. |
This is the default. |
|
|
Parse only: produce no output. |
Parse only: produce no output. |
Implies |
Implies |
.Fl W Ns Cm warning . |
.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 |
.It Fl T Ns Cm pdf |
Produce PDF output. |
Produce PDF output. |
See |
See |
|
|
.Pp |
.Pp |
If multiple input files are specified, these will be processed by the |
If multiple input files are specified, these will be processed by the |
corresponding filter in-order. |
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 |
.Ss ASCII Output |
Output produced by |
Output produced by |
.Fl T Ns Cm ascii , |
.Fl T Ns Cm ascii , |
Line 209 Emboldened characters are rendered as |
|
Line 240 Emboldened characters are rendered as |
|
The special characters documented in |
The special characters documented in |
.Xr mandoc_char 7 |
.Xr mandoc_char 7 |
are rendered best-effort in an ASCII equivalent. |
are rendered best-effort in an ASCII equivalent. |
|
If no equivalent is found, |
|
.Sq \&? |
|
is used instead. |
.Pp |
.Pp |
Output width is limited to 78 visible columns unless literal input lines |
Output width is limited to 78 visible columns unless literal input lines |
exceed this limit. |
exceed this limit. |
Line 227 Output produced by |
|
Line 261 Output produced by |
|
.Fl T Ns Cm html |
.Fl T Ns Cm html |
conforms to HTML-4.01 strict. |
conforms to HTML-4.01 strict. |
.Pp |
.Pp |
Font styles and page structure are applied using CSS1. |
|
By default, no font style is applied to any text, |
|
although CSS1 is hard-coded to format |
|
the basic structure of output. |
|
.Pp |
|
The |
The |
.Pa example.style.css |
.Pa example.style.css |
file documents the range of styles applied to output and, if used, will |
file documents style-sheet classes available for customising output. |
cause rendered documents to appear as they do in |
If a style-sheet is not specified with |
.Fl T Ns Cm ascii . |
.Fl O Ns Ar style , |
|
.Fl T Ns Cm html |
|
defaults to simple output readable in any graphical or text-based web |
|
browser. |
.Pp |
.Pp |
Special characters are rendered in decimal-encoded UTF-8. |
Special characters are rendered in decimal-encoded UTF\-8. |
.Pp |
.Pp |
The following |
The following |
.Fl O |
.Fl O |
Line 375 output mode implies |
|
Line 407 output mode implies |
|
.Sh EXAMPLES |
.Sh EXAMPLES |
To page manuals to the terminal: |
To page manuals to the terminal: |
.Pp |
.Pp |
.D1 $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less |
.Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less |
.D1 $ mandoc mandoc.1 mdoc.3 mdoc.7 | less |
.Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less |
.Pp |
.Pp |
To produce HTML manuals with |
To produce HTML manuals with |
.Ar style.css |
.Ar style.css |
as the style-sheet: |
as the style-sheet: |
.Pp |
.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 |
.Pp |
To check over a large set of manuals: |
To check over a large set of manuals: |
.Pp |
.Pp |
Line 390 To check over a large set of manuals: |
|
Line 422 To check over a large set of manuals: |
|
.Pp |
.Pp |
To produce a series of PostScript manuals for A4 paper: |
To produce a series of PostScript manuals for A4 paper: |
.Pp |
.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 |
.Sh DIAGNOSTICS |
Standard error messages reporting parsing errors are prefixed by |
Standard error messages reporting parsing errors are prefixed by |
.Pp |
.Pp |
Line 462 Each input and output format is separately noted. |
|
Line 504 Each input and output format is separately noted. |
|
.Ss ASCII Compatibility |
.Ss ASCII Compatibility |
.Bl -bullet -compact |
.Bl -bullet -compact |
.It |
.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 |
The |
.Sq \&Bd \-literal |
.Sq \&Bd \-literal |
and |
and |
|
|
.Fl T Ns Cm ascii |
.Fl T Ns Cm ascii |
are synonyms, as are \-filled and \-ragged. |
are synonyms, as are \-filled and \-ragged. |
.It |
.It |
In GNU troff, the |
In historic GNU troff, the |
.Sq \&Pa |
.Sq \&Pa |
.Xr mdoc 7 |
.Xr mdoc 7 |
macro does not underline when scoped under an |
macro does not underline when scoped under an |
|
|
has no effect. |
has no effect. |
.It |
.It |
Words aren't hyphenated. |
Words aren't hyphenated. |
.It |
|
Sentences are unilaterally monospaced. |
|
.El |
.El |
.Ss HTML/XHTML Compatibility |
.Ss HTML/XHTML Compatibility |
.Bl -bullet -compact |
.Bl -bullet -compact |
|
|
lists render similarly. |
lists render similarly. |
.El |
.El |
.Sh SEE ALSO |
.Sh SEE ALSO |
|
.Xr eqn 7 , |
.Xr man 7 , |
.Xr man 7 , |
.Xr mandoc_char 7 , |
.Xr mandoc_char 7 , |
.Xr mdoc 7 |
.Xr mdoc 7 , |
|
.Xr roff 7 , |
|
.Xr tbl 7 |
.Sh AUTHORS |
.Sh AUTHORS |
The |
The |
.Nm |
.Nm |
utility was written by |
utility was written by |
.An Kristaps Dzonsons Aq kristaps@bsd.lv . |
.An Kristaps Dzonsons , |
|
.Mt kristaps@bsd.lv . |
.Sh CAVEATS |
.Sh CAVEATS |
In |
In |
.Fl T Ns Cm html |
.Fl T Ns Cm html |