version 1.82, 2010/12/17 11:18:57 |
version 1.94, 2011/10/05 21:35:17 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
|
|
.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 |
|
|
utility accepts the following |
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 "-Tlocale" |
.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 locale |
|
Encode output using the current locale. |
|
See |
|
.Sx Locale Output . |
|
.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 |
|
|
.Sx PostScript Output . |
.Sx PostScript Output . |
.It Fl T Ns Cm tree |
.It Fl T Ns Cm tree |
Produce an indented parse 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 |
.It Fl T Ns Cm xhtml |
Produce strict CSS1/XHTML-1.0 output. |
Produce strict CSS1/XHTML-1.0 output. |
See |
See |
Line 209 Emboldened characters are rendered as |
|
Line 223 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 244 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 |
arguments are accepted: |
arguments are accepted: |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
|
.It Cm fragment |
|
Do not emit doctype, html, and body elements. |
|
The |
|
.Cm style |
|
argument shall be unused. |
|
This is useful when embedding manual content within existing documents. |
.It Cm includes Ns = Ns Ar fmt |
.It Cm includes Ns = Ns Ar fmt |
The string |
The string |
.Ar fmt , |
.Ar fmt , |
Line 280 is used for an external style-sheet. |
|
Line 301 is used for an external style-sheet. |
|
This must be a valid absolute or |
This must be a valid absolute or |
relative URI. |
relative URI. |
.El |
.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 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 |
.Ss PostScript Output |
PostScript |
PostScript |
.Qq Adobe-3.0 |
.Qq Adobe-3.0 |
Line 314 If an unknown value is encountered, |
|
Line 353 If an unknown value is encountered, |
|
.Ar letter |
.Ar letter |
is used. |
is used. |
.El |
.El |
.Ss PDF Output |
.Ss UTF\-8 Output |
PDF-1.1 output may be generated by |
Use |
.Fl T Ns Cm pdf . |
.Fl T Ns Cm utf8 |
|
to force a UTF\-8 locale. |
See |
See |
.Sx PostScript Output |
.Sx Locale Output |
for |
for details and options. |
.Fl O |
|
arguments and defaults. |
|
.Ss XHTML Output |
.Ss XHTML Output |
Output produced by |
Output produced by |
.Fl T Ns Cm xhtml |
.Fl T Ns Cm xhtml |
Line 391 To check over a large set of manuals: |
|
Line 429 To check over a large set of manuals: |
|
To produce a series of PostScript manuals for A4 paper: |
To produce a series of PostScript manuals for A4 paper: |
.Pp |
.Pp |
.Dl $ 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 510 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 |