version 1.78, 2010/09/26 23:05:46 |
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, backspace-encoded for bold and underline |
Produce 7-bit ASCII output. |
styles. |
|
This is the default. |
This is the default. |
See |
See |
.Sx ASCII Output . |
.Sx ASCII Output . |
.It Fl T Ns Cm html |
.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 |
See |
.Sx HTML Output . |
.Sx HTML Output . |
.It Fl T Ns Cm lint |
.It Fl T Ns Cm lint |
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 XHTML-1.0 output, with a sane default style. |
Produce strict CSS1/XHTML-1.0 output. |
See |
See |
.Sx XHTML Output . |
.Sx XHTML Output . |
.El |
.El |
Line 210 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 228 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 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 |
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 281 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 315 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 376 output mode implies |
|
Line 413 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 391 To check over a large set of manuals: |
|
Line 428 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 463 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 |
The |
|
.Fl T Ns Cm html |
|
and |
|
.Fl T Ns Cm xhtml |
|
CSS2 styling used for |
|
.Fl m Ns Cm doc |
|
input lists does not render properly in older browsers, such as Internet |
|
Explorer 6 and earlier. |
|
.Pp |
|
In |
In |
.Fl T Ns Cm html |
.Fl T Ns Cm html |
and |
and |
|
|
.Fl T Ns Cm xhtml |
.Fl T Ns Cm xhtml |
and cause them to forget the formatting of the prior next-line scope. |
and cause them to forget the formatting of the prior next-line scope. |
.Pp |
.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 |
The |
.Sq \(aq |
.Sq \(aq |
control character is an alias for the standard macro control character |
control character is an alias for the standard macro control character |