Return to mandoc.1 CVS log | Up to [cvsweb.bsd.lv] / mandoc |
version 1.176, 2017/03/04 17:17:34 | version 1.181, 2017/03/21 18:25:51 | ||
---|---|---|---|
|
|
||
.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 acfhkl | ||
.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 option | ||
.Op Fl T Ar output | .Op Fl T Ar output | ||
.Op Fl W Ar level | .Op Fl W Ar level | ||
|
|
||
.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 | ||
|
|
||
.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. | ||
|
|
||
and | and | ||
.Fl k | .Fl k | ||
options. | options. | ||
.It Fl m Ns Ar format | .It Fl mdoc | man | ||
Input format. | With | ||
See | .Fl mdoc , | ||
.Sx Input Formats | all input files are interpreted as | ||
for available formats. | .Xr mdoc 7 . | ||
Defaults to | With | ||
.Fl m Ns Cm andoc . | .Fl man , | ||
all input files are interpreted as | |||
.Xr man 7 . | |||
By default, the input language is automatically detected for each file: | |||
if the the first macro is | |||
.Ic \&Dd | |||
or | |||
.Ic \&Dt , | |||
the | |||
.Xr mdoc 7 | |||
parser is used; otherwise, the | |||
.Xr man 7 | |||
parser is used. | |||
With other arguments, | |||
.Fl m | |||
is silently ignored. | |||
.It Fl O Ar option | .It Fl O Ar option | ||
Comma-separated output options. | Comma-separated output options. | ||
.It Fl T Ar output | .It Fl T Ar output | ||
|
|
||
described in the | described in the | ||
.Xr apropos 1 | .Xr apropos 1 | ||
manual. | manual. | ||
.Ss Input Formats | |||
The | |||
.Nm | |||
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 | ||
|
|
||
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 | ||
|
|
||
.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. |