Return to mandoc.1 CVS log | Up to [cvsweb.bsd.lv] / mandoc |
version 1.175, 2017/03/03 14:23:23 | version 1.203, 2017/06/24 15:59:50 | ||
---|---|---|---|
|
|
||
.Os | .Os | ||
.Sh NAME | .Sh NAME | ||
.Nm mandoc | .Nm mandoc | ||
.Nd format and display UNIX manuals | .Nd format manual pages | ||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||
.Nm mandoc | .Nm mandoc | ||
.Op Fl acfhkl | .Op Fl ac | ||
.Op Fl I Cm os Ns = Ns Ar name | .Op Fl I Cm os Ns = Ns Ar name | ||
.Op Fl K Ar encoding | .Op Fl K Ar encoding | ||
.Op Fl m Ns Ar format | .Op Fl mdoc | man | ||
.Op Fl O Ar option | .Op Fl O Ar options | ||
.Op Fl T Ar output | .Op Fl T Ar output | ||
.Op Fl W Ar level | .Op Fl W Ar level | ||
.Op Ar | .Op Ar | ||
|
|
||
.Xr mdoc 7 | .Xr mdoc 7 | ||
or | or | ||
.Xr man 7 | .Xr man 7 | ||
text from stdin, implying | text from stdin and produces | ||
.Fl m Ns Cm andoc , | |||
and produces | |||
.Fl T Cm locale | .Fl T Cm locale | ||
output. | output. | ||
.Pp | .Pp | ||
|
|
||
This is the default. | This is the default. | ||
It can be specified to override | It can be specified to override | ||
.Fl a . | .Fl a . | ||
.It Fl f | |||
A synonym for | |||
.Xr whatis 1 . | |||
This overrides any earlier | |||
.Fl k | |||
and | |||
.Fl l | |||
options. | |||
.It Fl h | |||
Display only the SYNOPSIS lines. | |||
Implies | |||
.Fl c . | |||
.It Fl I Cm os Ns = Ns Ar name | .It Fl I Cm os Ns = Ns Ar name | ||
Override the default operating system | Override the default operating system | ||
.Ar name | .Ar name | ||
for the | for the | ||
.Xr mdoc 7 | .Xr mdoc 7 | ||
.Sq \&Os | .Ic \&Os | ||
and for the | and for the | ||
.Xr man 7 | .Xr man 7 | ||
.Sq \&TH | .Ic \&TH | ||
macro. | macro. | ||
.It Fl K Ar encoding | .It Fl K Ar encoding | ||
Specify the input encoding. | Specify the input encoding. | ||
|
|
||
.Cm iso-8859-1 , | .Cm iso-8859-1 , | ||
and | and | ||
.Cm utf-8 . | .Cm utf-8 . | ||
If not specified, autodetection uses the first match: | If not specified, autodetection uses the first match in the following | ||
.Bl -tag -width iso-8859-1 | list: | ||
.It Cm utf-8 | .Bl -enum | ||
if the first three bytes of the input file | .It | ||
are the UTF-8 byte order mark (BOM, 0xefbbbf) | If the first three bytes of the input file are the UTF-8 byte order | ||
.It Ar encoding | mark (BOM, 0xefbbbf), input is interpreted as | ||
if the first or second line of the input file matches the | .Cm utf-8 . | ||
.It | |||
If the first or second line of the input file matches the | |||
.Sy emacs | .Sy emacs | ||
mode line format | mode line format | ||
.Pp | .Pp | ||
.D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*- | .D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*- | ||
.It Cm utf-8 | .Pp | ||
if the first non-ASCII byte in the file introduces a valid UTF-8 sequence | then input is interpreted according to | ||
.It Cm iso-8859-1 | .Ar encoding . | ||
otherwise | .It | ||
If the first non-ASCII byte in the file introduces a valid UTF-8 | |||
sequence, input is interpreted as | |||
.Cm utf-8 . | |||
.It | |||
Otherwise, input is interpreted as | |||
.Cm iso-8859-1 . | |||
.El | .El | ||
.It Fl k | .It Fl mdoc | man | ||
A synonym for | With | ||
.Xr apropos 1 . | .Fl mdoc , | ||
This overrides any earlier | all input files are interpreted as | ||
.Fl f | .Xr mdoc 7 . | ||
and | With | ||
.Fl l | .Fl man , | ||
options. | all input files are interpreted as | ||
.It Fl l | .Xr man 7 . | ||
A synonym for | By default, the input language is automatically detected for each file: | ||
.Fl a . | if the the first macro is | ||
Also reverts any earlier | .Ic \&Dd | ||
.Fl f | or | ||
and | .Ic \&Dt , | ||
.Fl k | the | ||
options. | .Xr mdoc 7 | ||
.It Fl m Ns Ar format | parser is used; otherwise, the | ||
Input format. | .Xr man 7 | ||
See | parser is used. | ||
.Sx Input Formats | With other arguments, | ||
for available formats. | .Fl m | ||
Defaults to | is silently ignored. | ||
.Fl m Ns Cm andoc . | .It Fl O Ar options | ||
.It Fl O Ar option | |||
Comma-separated output options. | Comma-separated output options. | ||
.It Fl T Ar output | .It Fl T Ar output | ||
Output format. | Output format. | ||
|
|
||
The | The | ||
.Ar level | .Ar level | ||
can be | can be | ||
.Cm base , | |||
.Cm style , | |||
.Cm warning , | .Cm warning , | ||
.Cm error , | .Cm error , | ||
or | or | ||
.Cm unsupp ; | .Cm unsupp . | ||
The | |||
.Cm base | |||
level automatically derives the operating system from the contents of the | |||
.Ic \&Os | |||
macro, from the | |||
.Fl Ios | |||
command line option, or from the | |||
.Xr uname 3 | |||
return value. | |||
The levels | |||
.Cm openbsd | |||
and | |||
.Cm netbsd | |||
are variants of | |||
.Cm base | |||
that bypass autodetection and request validation of base system | |||
conventions for a particular operating system. | |||
The level | |||
.Cm all | .Cm all | ||
is an alias for | is an alias for | ||
.Cm warning . | .Cm base . | ||
By default, | By default, | ||
.Nm | .Nm | ||
is silent. | is silent. | ||
|
|
||
will halt with the first failed parse. | will halt with the first failed parse. | ||
.El | .El | ||
.Pp | .Pp | ||
The options | |||
.Fl fhklw | |||
are also supported and are documented in man(1). | |||
In | In | ||
.Fl f | .Fl f | ||
and | and | ||
|
|
||
mode, | mode, | ||
.Nm | .Nm | ||
also supports the options | also supports the options | ||
.Fl CMmOSsw | .Fl CMmOSs | ||
described in the | described in the | ||
.Xr apropos 1 | .Xr apropos 1 | ||
manual. | manual. | ||
.Ss Input Formats | The options | ||
The | .Fl fkl | ||
.Nm | are mutually exclusive and override each other. | ||
utility accepts | |||
.Xr mdoc 7 | |||
and | |||
.Xr man 7 | |||
input with | |||
.Fl m Ns Cm doc | |||
and | |||
.Fl m Ns Cm an , | |||
respectively. | |||
The | |||
.Xr mdoc 7 | |||
format is | |||
.Em strongly | |||
recommended; | |||
.Xr man 7 | |||
should only be used for legacy manuals. | |||
.Pp | |||
A third option, | |||
.Fl m Ns Cm andoc , | |||
which is also the default, determines encoding on-the-fly: if the first | |||
non-comment macro is | |||
.Sq \&Dd | |||
or | |||
.Sq \&Dt , | |||
the | |||
.Xr mdoc 7 | |||
parser is used; otherwise, the | |||
.Xr man 7 | |||
parser is used. | |||
.Pp | |||
If multiple | |||
files are specified with | |||
.Fl m Ns Cm andoc , | |||
each has its file-type determined this way. | |||
If multiple files are | |||
specified and | |||
.Fl m Ns Cm doc | |||
or | |||
.Fl m Ns Cm an | |||
is specified, then this format is used exclusively. | |||
.Ss Output Formats | .Ss Output Formats | ||
The | The | ||
.Nm | .Nm | ||
|
|
||
.It Fl T Cm lint | .It Fl T Cm lint | ||
Parse only: produce no output. | Parse only: produce no output. | ||
Implies | Implies | ||
.Fl W Cm warning . | .Fl W Cm all . | ||
.It Fl T Cm locale | .It Fl T Cm locale | ||
Encode output using the current locale. | Encode output using the current locale. | ||
This is the default. | This is the default. | ||
|
|
||
Encode output in the UTF\-8 multi-byte format. | Encode output in the UTF\-8 multi-byte format. | ||
See | See | ||
.Sx UTF\-8 Output . | .Sx UTF\-8 Output . | ||
.It Fl T Cm xhtml | |||
This is a synonym for | |||
.Fl T Cm html . | |||
.El | .El | ||
.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 | ||
|
|
||
for example overfull lines or ugly line breaks. | 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 . | ||
which will normalise to \(>=58. | |||
.El | .El | ||
.Ss HTML Output | .Ss HTML Output | ||
Output produced by | Output produced by | ||
|
|
||
for example, | for example, | ||
.Ar ../src/%I.html , | .Ar ../src/%I.html , | ||
is used as a template for linked header files (usually via the | is used as a template for linked header files (usually via the | ||
.Sq \&In | .Ic \&In | ||
macro). | macro). | ||
Instances of | Instances of | ||
.Sq \&%I | .Sq \&%I | ||
|
|
||
for example, | for example, | ||
.Ar ../html%S/%N.%S.html , | .Ar ../html%S/%N.%S.html , | ||
is used as a template for linked manuals (usually via the | is used as a template for linked manuals (usually via the | ||
.Sq \&Xr | .Ic \&Xr | ||
macro). | macro). | ||
Instances of | Instances of | ||
.Sq \&%N | .Sq \&%N | ||
|
|
||
.Xr man 7 , | .Xr man 7 , | ||
the input is copied to the output, expanding any | the input is copied to the output, expanding any | ||
.Xr roff 7 | .Xr roff 7 | ||
.Sq so | .Ic so | ||
requests. | requests. | ||
The parser is also run, and as usual, the | The parser is also run, and as usual, the | ||
.Fl W | .Fl W | ||
|
|
||
format conforming to | format conforming to | ||
.Lk http://daringfireball.net/projects/markdown/syntax.text\ | .Lk http://daringfireball.net/projects/markdown/syntax.text\ | ||
"John Gruber's 2004 specification" . | "John Gruber's 2004 specification" . | ||
The output also almost conforms to the | |||
.Lk http://commonmark.org/ CommonMark | |||
specification. | |||
.Pp | .Pp | ||
The character set used for the markdown output is ASCII. | |||
Non-ASCII characters are encoded as HTML entities. | |||
Since that is not possible in literal font contexts, because these | |||
are rendered as code spans and code blocks in the markdown output, | |||
non-ASCII characters are transliterated to ASCII approximations in | |||
these contexts. | |||
.Pp | |||
Markdown is a very weak markup language, so all semantic markup is | Markdown is a very weak markup language, so all semantic markup is | ||
lost, and even part of the presentational markup may be lost. | lost, and even part of the presentational markup may be lost. | ||
Do not use this as an intermediate step in converting to HTML; | Do not use this as an intermediate step in converting to HTML; | ||
|
|
||
.It Ev MANPAGER | .It Ev MANPAGER | ||
Any non-empty value of the environment variable | Any non-empty value of the environment variable | ||
.Ev MANPAGER | .Ev MANPAGER | ||
will be used instead of the standard pagination program, | is used instead of the standard pagination program, | ||
.Xr more 1 . | .Xr more 1 ; | ||
see | |||
.Xr man 1 | |||
for details. | |||
Only used if | |||
.Fl a | |||
or | |||
.Fl l | |||
is specified. | |||
.It Ev PAGER | .It Ev PAGER | ||
Specifies the pagination program to use when | Specifies the pagination program to use when | ||
.Ev MANPAGER | .Ev MANPAGER | ||
|
|
||
If neither PAGER nor MANPAGER is defined, | If neither PAGER nor MANPAGER is defined, | ||
.Xr more 1 | .Xr more 1 | ||
.Fl s | .Fl s | ||
will be used. | is used. | ||
Only used if | |||
.Fl a | |||
or | |||
.Fl l | |||
is specified. | |||
.El | .El | ||
.Sh EXIT STATUS | .Sh EXIT STATUS | ||
The | The | ||
|
|
||
.Pp | .Pp | ||
.Bl -tag -width Ds -compact | .Bl -tag -width Ds -compact | ||
.It 0 | .It 0 | ||
No warnings or errors occurred, or those that did were ignored because | No base system convention violations, style suggestions, warnings, | ||
they were lower than the requested | or errors occurred, or those that did were ignored because they | ||
were lower than the requested | |||
.Ar level . | .Ar level . | ||
.It 1 | |||
At least one base system convention violation or style suggestion | |||
occurred, but no warning or error, and | |||
.Fl W Cm base | |||
or | |||
.Fl W Cm style | |||
was specified. | |||
.It 2 | .It 2 | ||
At least one warning occurred, but no error, and | At least one warning occurred, but no error, and | ||
.Fl W Cm warning | .Fl W Cm warning | ||
was specified. | or a lower | ||
.Ar level | |||
was requested. | |||
.It 3 | .It 3 | ||
At least one parsing error occurred, | At least one parsing error occurred, | ||
but no unsupported feature was encountered, and | but no unsupported feature was encountered, and | ||
.Fl W Cm error | .Fl W Cm error | ||
or | or a lower | ||
.Fl W Cm warning | .Ar level | ||
was specified. | was requested. | ||
.It 4 | .It 4 | ||
At least one unsupported feature was encountered, and | At least one unsupported feature was encountered, and | ||
.Fl W Cm unsupp , | .Fl W Cm unsupp | ||
.Fl W Cm error | or a lower | ||
or | .Ar level | ||
.Fl W Cm warning | was requested. | ||
was specified. | |||
.It 5 | .It 5 | ||
Invalid command line arguments were specified. | Invalid command line arguments were specified. | ||
No input files have been read. | No input files have been read. | ||
|
|
||
Note that selecting | Note that selecting | ||
.Fl T Cm lint | .Fl T Cm lint | ||
output mode implies | output mode implies | ||
.Fl W Cm warning . | .Fl W Cm all . | ||
.Sh EXAMPLES | .Sh EXAMPLES | ||
To page manuals to the terminal: | To page manuals to the terminal: | ||
.Pp | .Pp | ||
.Dl $ mandoc \-W all,stop mandoc.1 2\*(Gt&1 | less | .Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8 | ||
.Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less | |||
.Pp | .Pp | ||
To produce HTML manuals with | To produce HTML manuals with | ||
.Pa mandoc.css | .Pa mandoc.css | ||
|
|
||
Messages displayed by | Messages displayed by | ||
.Nm | .Nm | ||
follow this format: | follow this format: | ||
.Bd -ragged -offset indent | |||
.Nm Ns : | |||
.Ar file : Ns Ar line : Ns Ar column : level : message : macro args | |||
.Pq Ar os | |||
.Ed | |||
.Pp | .Pp | ||
.D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args | |||
.Pp | |||
Line and column numbers start at 1. | Line and column numbers start at 1. | ||
Both are omitted for messages referring to an input file as a whole. | Both are omitted for messages referring to an input file as a whole. | ||
Macro names and arguments are omitted where meaningless. | Macro names and arguments are omitted where meaningless. | ||
The | |||
.Ar os | |||
operating system specifier is omitted for messages that are relevant | |||
for all operating systems. | |||
Fatal messages about invalid command line arguments | Fatal messages about invalid command line arguments | ||
or operating system errors, for example when memory is exhausted, | or operating system errors, for example when memory is exhausted, | ||
may also omit the | may also omit the | ||
|
|
||
Documents causing warnings may render poorly when using other | Documents causing warnings may render poorly when using other | ||
formatting tools instead of | formatting tools instead of | ||
.Nm . | .Nm . | ||
.It Cm style | |||
An input file uses dubious or discouraged style. | |||
This is not a complaint about the syntax, and probably neither | |||
formatting nor portability are in danger. | |||
While great care is taken to avoid false positives on the higher | |||
message levels, the | |||
.Cm style | |||
level tries to reduce the probability that issues go unnoticed, | |||
so it may occasionally issue bogus suggestions. | |||
Please use your good judgement to decide whether any particular | |||
.Cm style | |||
suggestion really justifies a change to the input file. | |||
.It Cm base | |||
A convertion used in the base system of a specific operating system | |||
is not adhered to. | |||
These are not markup mistakes, and neither the quality of formatting | |||
nor portability are in danger. | |||
.El | .El | ||
.Pp | .Pp | ||
Messages of the | Messages of the | ||
.Cm base , | |||
.Cm style , | |||
.Cm warning , | .Cm warning , | ||
.Cm error , | .Cm error , | ||
and | and | ||
|
|
||
option or | option or | ||
.Fl T Cm lint | .Fl T Cm lint | ||
output mode. | output mode. | ||
.Pp | |||
As indicated below, all | |||
.Cm base | |||
and some | |||
.Cm style | |||
checks are only performed if a specific operating system name occurs | |||
in the arguments of the | |||
.Fl W | |||
command line option, of the | |||
.Ic \&Os | |||
macro, of the | |||
.Fl Ios | |||
command line option, or, if neither are present, in the return value | |||
of the | |||
.Xr uname 3 | |||
function. | |||
.Ss Conventions for base system manuals | |||
.Bl -ohang | |||
.It Sy "Mdocdate found" | |||
.Pq mdoc , Nx | |||
The | |||
.Ic \&Dd | |||
macro uses CVS | |||
.Ic Mdocdate | |||
keyword substitution, which is not supported by the | |||
.Nx | |||
base system. | |||
Consider using the conventional | |||
.Dq "Month dd, yyyy" | |||
format instead. | |||
.It Sy "Mdocdate missing" | |||
.Pq mdoc , Ox | |||
The | |||
.Ic \&Dd | |||
macro does not use CVS | |||
.Ic Mdocdate | |||
keyword substitution, but using it is conventionally expected in the | |||
.Ox | |||
base system. | |||
.It Sy "operating system explicitly specified" | |||
.Pq mdoc , Ox , Nx | |||
The | |||
.Ic \&Os | |||
macro has an argument. | |||
In the base system, it is conventionally left blank. | |||
.It Sy "RCS id missing" | |||
.Pq Ox , Nx | |||
The manual page lacks the comment line with the RCS identifier | |||
generated by CVS | |||
.Ic OpenBSD | |||
or | |||
.Ic NetBSD | |||
keyword substitution as conventionally used in these operating systems. | |||
.El | |||
.Ss Style suggestions | |||
.Bl -ohang | |||
.It Sy "legacy man(7) date format" | |||
.Pq mdoc | |||
The | |||
.Ic \&Dd | |||
macro uses the legacy | |||
.Xr man 7 | |||
date format | |||
.Dq yyyy-dd-mm . | |||
Consider using the conventional | |||
.Xr mdoc 7 | |||
date format | |||
.Dq "Month dd, yyyy" | |||
instead. | |||
.It Sy "duplicate RCS id" | |||
A single manual page contains two copies of the RCS identifier for | |||
the same operating system. | |||
Consider deleting the later instance and moving the first one up | |||
to the top of the page. | |||
.It Sy "useless macro" | |||
.Pq mdoc | |||
A | |||
.Ic \&Bt , | |||
.Ic \&Tn , | |||
or | |||
.Ic \&Ud | |||
macro was found. | |||
Simply delete it: it serves no useful purpose. | |||
.It Sy "consider using OS macro" | |||
.Pq mdoc | |||
A string was found in plain text or in a | |||
.Ic \&Bx | |||
macro that could be represented using | |||
.Ic \&Ox , | |||
.Ic \&Nx , | |||
.Ic \&Fx , | |||
or | |||
.Ic \&Dx . | |||
.It Sy "errnos out of order" | |||
.Pq mdoc, Nx | |||
The | |||
.Ic \&Er | |||
items in a | |||
.Ic \&Bl | |||
list are not in alphabetical order. | |||
.It Sy "duplicate errno" | |||
.Pq mdoc, Nx | |||
A | |||
.Ic \&Bl | |||
list contains two consecutive | |||
.Ic \&It | |||
entries describing the same | |||
.Ic \&Er | |||
number. | |||
.It Sy "description line ends with a full stop" | |||
.Pq mdoc | |||
Do not use punctuation at the end of an | |||
.Ic \&Nd | |||
block. | |||
.It Sy "no blank before trailing delimiter" | |||
.Pq mdoc | |||
The last argument of a macro that supports trailing delimiter | |||
arguments is longer than one byte and ends with a trailing delimiter. | |||
Consider inserting a blank such that the delimiter becomes a separate | |||
argument, thus moving it out of the scope of the macro. | |||
.It Sy "function name without markup" | |||
.Pq mdoc | |||
A word followed by an empty pair of parentheses occurs on a text line. | |||
Consider using an | |||
.Ic \&Fn | |||
or | |||
.Ic \&Xr | |||
macro. | |||
.El | |||
.Ss Warnings related to the document prologue | .Ss Warnings related to the document prologue | ||
.Bl -ohang | .Bl -ohang | ||
.It Sy "missing manual title, using UNTITLED" | .It Sy "missing manual title, using UNTITLED" | ||
|
|
||
.Ic \&Nd | .Ic \&Nd | ||
macro lacks the required argument. | macro lacks the required argument. | ||
The title line of the manual will end after the dash. | The title line of the manual will end after the dash. | ||
.It Sy "description line outside NAME section" | |||
.Pq mdoc | |||
An | |||
.Ic \&Nd | |||
macro appears outside the NAME section. | |||
The arguments are printed anyway and the following text is used for | |||
.Xr apropos 1 , | |||
but none of that behaviour is portable. | |||
.It Sy "sections out of conventional order" | .It Sy "sections out of conventional order" | ||
.Pq mdoc | .Pq mdoc | ||
A standard section occurs after another section it usually precedes. | A standard section occurs after another section it usually precedes. | ||
|
|
||
.Ic \&Bl | .Ic \&Bl | ||
.Fl offset | .Fl offset | ||
or | or | ||
.Fl width. | .Fl width . | ||
.It Sy "missing display type, using -ragged" | .It Sy "missing display type, using -ragged" | ||
.Pq mdoc | .Pq mdoc | ||
The | The | ||
|
|
||
.Ic \&Fn | .Ic \&Fn | ||
macro contains an opening or closing parenthesis; that's probably wrong, | macro contains an opening or closing parenthesis; that's probably wrong, | ||
parentheses are added automatically. | parentheses are added automatically. | ||
.It Sy "unknown library name" | |||
.Pq mdoc, not on Ox | |||
An | |||
.Ic \&Lb | |||
macro has an unknown name argument and will be rendered as | |||
.Qq library Dq Ar name . | |||
.It Sy "invalid content in Rs block" | .It Sy "invalid content in Rs block" | ||
.Pq mdoc | .Pq mdoc | ||
An | An | ||
|
|
||
A | A | ||
.Ic \&Bl | .Ic \&Bl | ||
macro fails to specify the list type. | macro fails to specify the list type. | ||
.It Sy "argument is not numeric, using 1" | |||
.Pq roff | |||
The argument of a | |||
.Ic \&ce | |||
request is not a number. | |||
.It Sy "missing manual name, using \(dq\(dq" | .It Sy "missing manual name, using \(dq\(dq" | ||
.Pq mdoc | .Pq mdoc | ||
The first call to | The first call to |