version 1.92, 2011/09/18 14:14:15 |
version 1.105, 2014/06/23 22:03:30 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
|
.\" Copyright (c) 2012, 2014 Ingo Schwarze <schwarze@openbsd.org> |
.\" |
.\" |
.\" 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 |
|
|
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.Nm mandoc |
.Nm mandoc |
.Op Fl V |
.Op Fl V |
|
.Sm off |
|
.Op Fl I Cm os Li = Ar name |
|
.Sm on |
.Op Fl m Ns Ar format |
.Op Fl m Ns Ar format |
.Op Fl O Ns Ar option |
.Op Fl O Ns Ar option |
.Op Fl T Ns Ar output |
.Op Fl T Ns Ar output |
|
|
utility formats |
utility formats |
.Ux |
.Ux |
manual pages for display. |
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: |
The arguments are as follows: |
.Bl -tag -width Ds |
.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 |
.It Fl m Ns Ar format |
Input format. |
Input format. |
See |
See |
Line 96 If multiple files are specified, |
|
Line 122 If multiple files are specified, |
|
.Nm |
.Nm |
will halt with the first failed parse. |
will halt with the first failed parse. |
.El |
.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 |
.Ss Input Formats |
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 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 locale |
|
Encode output using the current locale. |
|
See |
|
.Sx Locale Output . |
.It Fl T Ns Cm man |
.It Fl T Ns Cm man |
Produce output in |
Produce |
.Xr man 7 |
.Xr man 7 |
format; only useful when applied to |
format output. |
.Fl m Ns Cm doc |
See |
input. |
.Sx Man Output . |
.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 |
|
|
.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 , |
|
|
.Fl O |
.Fl O |
arguments are accepted: |
arguments are accepted: |
.Bl -tag -width Ds |
.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 |
.It Cm width Ns = Ns Ar width |
The output width is set to |
The output width is set to |
.Ar width , |
.Ar width , |
|
|
.Fl O |
.Fl O |
arguments are accepted: |
arguments are accepted: |
.Bl -tag -width Ds |
.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 |
.It Cm includes Ns = Ns Ar fmt |
The string |
The string |
.Ar fmt , |
.Ar fmt , |
Line 312 is used for an external style-sheet. |
|
Line 333 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 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 |
.Ss PostScript Output |
PostScript |
PostScript |
.Qq Adobe-3.0 |
.Qq Adobe-3.0 |
Line 346 If an unknown value is encountered, |
|
Line 409 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 |
|
|
.Sh DIAGNOSTICS |
.Sh DIAGNOSTICS |
Standard error messages reporting parsing errors are prefixed by |
Standard error messages reporting parsing errors are prefixed by |
.Pp |
.Pp |
.Sm off |
.D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : |
.D1 Ar file : line : column : \ level : |
|
.Sm on |
|
.Pp |
.Pp |
where the fields have the following meanings: |
where the fields have the following meanings: |
.Bl -tag -width "column" |
.Bl -tag -width "column" |
Line 456 points to the first character of the word. |
|
Line 516 points to the first character of the word. |
|
The message level, printed in capital letters. |
The message level, printed in capital letters. |
.El |
.El |
.Pp |
.Pp |
|
The |
|
.Ar line |
|
and |
|
.Ar column |
|
fields are omitted when meaningless. |
|
.Pp |
Message levels have the following meanings: |
Message levels have the following meanings: |
.Bl -tag -width "warning" |
.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 |
.It Cm fatal |
The parser is unable to parse a given input file at all. |
The parser is unable to parse a given input file at all. |
No formatted output is produced from that input file. |
No formatted output is produced from that input file. |
|
|
The |
The |
.Nm |
.Nm |
utility may also print messages related to invalid command line arguments |
utility may also print messages related to invalid command line arguments |
or operating system errors, for example when memory is exhausted or |
or operating system errors, for example when memory is exhausted. |
input files cannot be read. |
Such messages may not carry the prefix described above. |
Such messages do not carry the prefix described above. |
|
.Sh COMPATIBILITY |
.Sh COMPATIBILITY |
This section summarises |
This section summarises |
.Nm |
.Nm |
Line 588 lists render similarly. |
|
Line 656 lists render similarly. |
|
The |
The |
.Nm |
.Nm |
utility was written by |
utility was written by |
.An Kristaps Dzonsons , |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . |
.Mt kristaps@bsd.lv . |
|
.Sh CAVEATS |
.Sh CAVEATS |
In |
In |
.Fl T Ns Cm html |
.Fl T Ns Cm html |