Return to mandoc.1 CVS log | Up to [cvsweb.bsd.lv] / mandoc |
version 1.145, 2015/02/04 22:30:10 | version 1.239, 2019/05/26 01:28:09 | ||
---|---|---|---|
|
|
||
.\" $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, 2015 Ingo Schwarze <schwarze@openbsd.org> | .\" Copyright (c) 2012, 2014-2018 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 | ||
|
|
||
.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 acfhklV | .Op Fl ac | ||
.Sm off | .Op Fl I Cm os Ns = Ns Ar name | ||
.Op Fl I Cm os Li = Ar name | .Op Fl K Ar encoding | ||
.Sm on | .Op Fl mdoc | man | ||
.Op Fl K Ns Ar encoding | .Op Fl O Ar options | ||
.Op Fl m Ns Ar format | .Op Fl T Ar output | ||
.Op Fl O Ns Ar option | .Op Fl W Ar level | ||
.Op Fl T Ns Ar output | |||
.Op Fl W Ns Ar level | |||
.Op Ar | .Op Ar | ||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||
The | The | ||
.Nm | .Nm | ||
utility formats | utility formats manual pages for display. | ||
.Ux | |||
manual pages for display. | |||
.Pp | .Pp | ||
By default, | By default, | ||
.Nm | .Nm | ||
|
|
||
.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 , | .Fl T Cm locale | ||
and produces | |||
.Fl T Ns Cm locale | |||
output. | output. | ||
.Pp | .Pp | ||
The options are as follows: | The options are as follows: | ||
|
|
||
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 | .It Fl I Cm os Ns = Ns Ar name | ||
A synonym for | |||
.Xr whatis 1 . | |||
This overrides any earlier | |||
.Fl k | |||
and | |||
.Fl l | |||
options. | |||
.Sm off | |||
.It Fl I Cm os Li = Ar name | |||
.Sm on | |||
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 h | .It Fl K Ar encoding | ||
Display only the SYNOPSIS lines. | |||
Implies | |||
.Fl c . | |||
.It Fl K Ns Ar encoding | |||
Specify the input encoding. | Specify the input encoding. | ||
The supported | The supported | ||
.Ar encoding | .Ar 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 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 Ns Ar option | |||
Comma-separated output options. | Comma-separated output options. | ||
.It Fl T Ns Ar output | See the descriptions of the individual output formats for supported | ||
Output format. | .Ar options . | ||
See | .It Fl T Ar output | ||
.Sx Output Formats | Select the output format. | ||
for available formats. | Supported values for the | ||
Defaults to | .Ar output | ||
.Fl T Ns Cm locale . | argument are | ||
.It Fl V | .Cm ascii , | ||
Print version and exit. | .Cm html , | ||
.It Fl W Ns Ar level | the default of | ||
.Cm locale , | |||
.Cm man , | |||
.Cm markdown , | |||
.Cm pdf , | |||
.Cm ps , | |||
.Cm tree , | |||
and | |||
.Cm utf8 . | |||
.Pp | |||
The special | |||
.Fl T Cm lint | |||
mode only parses the input and produces no output. | |||
It implies | |||
.Fl W Cm all | |||
and redirects parser messages, which usually appear on standard | |||
error output, to standard output. | |||
.It Fl W Ar level | |||
Specify the minimum message | Specify the minimum message | ||
.Ar level | .Ar level | ||
to be reported on the standard error output and to affect the exit status. | to be reported on the standard error output and to affect the exit status. | ||
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. | ||
|
|
||
for details. | for details. | ||
.Pp | .Pp | ||
The special option | The special option | ||
.Fl W Ns Cm stop | .Fl W Cm stop | ||
tells | tells | ||
.Nm | .Nm | ||
to exit after parsing a file that causes warnings or errors of at least | to exit after parsing a file that causes warnings or errors of at least | ||
|
|
||
and | and | ||
.Cm stop | .Cm stop | ||
are requested, they can be joined with a comma, for example | are requested, they can be joined with a comma, for example | ||
.Fl W Ns Cm error , Ns Cm stop . | .Fl W Cm error , Ns Cm stop . | ||
.It Ar file | .It Ar file | ||
Read input from zero or more files. | Read from the given input file. | ||
If unspecified, reads from stdin. | If multiple files are specified, they are processed in the given order. | ||
If multiple files are specified, | If unspecified, | ||
.Nm | .Nm | ||
will halt with the first failed parse. | reads from standard input. | ||
.El | .El | ||
.Pp | .Pp | ||
The options | |||
.Fl fhklw | |||
are also supported and are documented in | |||
.Xr 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 | |||
The | |||
.Nm | |||
utility accepts the following | |||
.Fl T | |||
arguments, which correspond to output modes: | |||
.Bl -tag -width "-Tlocale" | |||
.It Fl T Ns Cm ascii | |||
Produce 7-bit ASCII output. | |||
See | |||
.Sx ASCII Output . | |||
.It Fl T Ns Cm html | |||
Produce HTML5, CSS1, and MathML output. | |||
See | |||
.Sx HTML Output . | |||
.It Fl T Ns Cm lint | |||
Parse only: produce no output. | |||
Implies | |||
.Fl W Ns Cm warning . | |||
.It Fl T Ns Cm locale | |||
Encode output using the current locale. | |||
This is the default. | |||
See | |||
.Sx Locale Output . | |||
.It Fl T Ns Cm man | |||
Produce | |||
.Xr man 7 | |||
format output. | |||
See | |||
.Sx Man Output . | |||
.It Fl T Ns Cm pdf | |||
Produce PDF output. | |||
See | |||
.Sx PDF Output . | |||
.It Fl T Ns Cm ps | |||
Produce PostScript output. | |||
See | |||
.Sx PostScript Output . | |||
.It Fl T Ns Cm 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 | |||
This is a synonym for | |||
.Fl T Ns Cm html . | |||
.El | |||
.Pp | |||
If multiple input files are specified, these will be processed by the | |||
corresponding filter in-order. | |||
.Ss ASCII Output | .Ss ASCII Output | ||
Output produced by | Use | ||
.Fl T Ns Cm ascii | .Fl T Cm ascii | ||
is rendered in standard 7-bit ASCII documented in | to force text output in 7-bit ASCII character encoding documented in the | ||
.Xr ascii 7 . | .Xr ascii 7 | ||
manual page, ignoring the | |||
.Xr locale 1 | |||
set in the environment. | |||
.Pp | .Pp | ||
Font styles are applied by using back-spaced encoding such that an | Font styles are applied by using back-spaced encoding such that an | ||
underlined character | underlined character | ||
|
|
||
is the back-space character number 8. | is the back-space character number 8. | ||
Emboldened characters are rendered as | Emboldened characters are rendered as | ||
.Sq c Ns \e[bs] Ns c . | .Sq c Ns \e[bs] Ns c . | ||
This markup is typically converted to appropriate terminal sequences by | |||
the pager or | |||
.Xr ul 1 . | |||
To remove the markup, pipe the output to | |||
.Xr col 1 | |||
.Fl b | |||
instead. | |||
.Pp | .Pp | ||
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. | ||
In particular, opening and closing | |||
.Sq single quotes | |||
are represented as characters number 0x60 and 0x27, respectively, | |||
which agrees with all ASCII standards from 1965 to the latest | |||
revision (2012) and which matches the traditional way in which | |||
.Xr roff 7 | |||
formatters represent single quotes in ASCII output. | |||
This correct ASCII rendering may look strange with modern | |||
Unicode-compatible fonts because contrary to ASCII, Unicode uses | |||
the code point U+0060 for the grave accent only, never for an opening | |||
quote. | |||
.Pp | .Pp | ||
Output width is limited to 78 visible columns unless literal input lines | |||
exceed this limit. | |||
.Pp | |||
The following | The following | ||
.Fl O | .Fl O | ||
arguments are accepted: | arguments are accepted: | ||
|
|
||
.Xr man 7 . | .Xr man 7 . | ||
Increasing this is not recommended; it may result in degraded formatting, | Increasing this is not recommended; it may result in degraded formatting, | ||
for example overfull lines or ugly line breaks. | for example overfull lines or ugly line breaks. | ||
When output is to a pager on a terminal that is less than 66 columns | |||
wide, the default is reduced to three columns. | |||
.It Cm mdoc | |||
Format | |||
.Xr man 7 | |||
input files in | |||
.Xr mdoc 7 | |||
output style. | |||
Specifically, this suppresses the two additional blank lines near the | |||
top and the bottom of each page, and it implies | |||
.Fl O Cm indent Ns =5 . | |||
One useful application is for checking that | |||
.Fl T Cm man | |||
output formats in the same way as the | |||
.Xr mdoc 7 | |||
source it was generated from. | |||
.It Cm tag Ns Op = Ns Ar term | |||
If the formatted manual page is opened in a pager, | |||
go to the definition of the | |||
.Ar term | |||
rather than showing the manual page from the beginning. | |||
If no | |||
.Ar term | |||
is specified, reuse the first command line argument that is not a | |||
.Ar section | |||
number. | |||
If that argument is in | |||
.Xr apropos 1 | |||
.Ar key Ns = Ns Ar val | |||
format, only the | |||
.Ar val | |||
is used rather than the argument as a whole. | |||
This is useful for commands like | |||
.Ql man -akO tag Ic=ulimit | |||
to search for a keyword and jump right to its definition | |||
in the matching manual pages. | |||
.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. | instead of the default of 78. | ||
When output is to a pager on a terminal that is less than 79 columns | |||
wide, the default is reduced to one less than the terminal width. | |||
In any case, lines that are output in literal mode are never wrapped | |||
and may exceed the output width. | |||
.El | .El | ||
.Ss HTML Output | .Ss HTML Output | ||
Output produced by | Output produced by | ||
.Fl T Ns Cm html | .Fl T Cm html | ||
conforms to HTML5 using optional self-closing tags. | conforms to HTML5 using optional self-closing tags. | ||
Default styles use only CSS1. | Default styles use only CSS1. | ||
Equations rendered from | Equations rendered from | ||
.Xr eqn 7 | .Xr eqn 7 | ||
blocks use MathML. | blocks use MathML. | ||
.Pp | .Pp | ||
The | The file | ||
.Pa example.style.css | .Pa /usr/share/misc/mandoc.css | ||
file documents style-sheet classes available for customising output. | documents style-sheet classes available for customising output. | ||
If a style-sheet is not specified with | If a style-sheet is not specified with | ||
.Fl O Ns Ar style , | .Fl O Cm style , | ||
.Fl T Ns Cm html | .Fl T Cm html | ||
defaults to simple output (via an embedded style-sheet) | defaults to simple output (via an embedded style-sheet) | ||
readable in any graphical or text-based web | readable in any graphical or text-based web | ||
browser. | browser. | ||
.Pp | .Pp | ||
Special characters are rendered in decimal-encoded UTF\-8. | Non-ASCII characters are rendered | ||
as hexadecimal Unicode character references. | |||
.Pp | .Pp | ||
The following | The following | ||
.Fl O | .Fl O | ||
|
|
||
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 | ||
are replaced with the include filename. | are replaced with the include filename. | ||
The default is not to present a | The default is not to present a | ||
hyperlink. | hyperlink. | ||
.It Cm man Ns = Ns Ar fmt | .It Cm man Ns = Ns Ar fmt Ns Op ; Ns Ar fmt | ||
The string | The string | ||
.Ar fmt , | .Ar fmt , | ||
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 | ||
|
|
||
If no section is included, section 1 is assumed. | If no section is included, section 1 is assumed. | ||
The default is not to | The default is not to | ||
present a hyperlink. | present a hyperlink. | ||
If two formats are given and a file | |||
.Ar %N.%S | |||
exists in the current directory, the first format is used; | |||
otherwise, the second format is used. | |||
.It Cm style Ns = Ns Ar style.css | .It Cm style Ns = Ns Ar style.css | ||
The file | The file | ||
.Ar style.css | .Ar style.css | ||
is used for an external style-sheet. | 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. | ||
.It Cm toc | |||
If an input file contains at least two non-standard sections, | |||
print a table of contents near the beginning of the output. | |||
.El | .El | ||
.Ss Locale Output | .Ss Locale Output | ||
Locale-depending output encoding is triggered with | By default, | ||
.Fl T Ns Cm locale . | .Nm | ||
This is the default. | automatically selects UTF-8 or ASCII output according to the current | ||
.Pp | .Xr locale 1 . | ||
This option is not available on all systems: systems without locale | If any of the environment variables | ||
support, or those whose internal representation is not natively UCS-4, | .Ev LC_ALL , | ||
will fall back to | .Ev LC_CTYPE , | ||
.Fl T Ns Cm ascii . | or | ||
See | .Ev LANG | ||
.Sx ASCII Output | are set and the first one that is set | ||
for font style specification and available command-line arguments. | selects the UTF-8 character encoding, it produces | ||
.Sx UTF-8 Output ; | |||
otherwise, it falls back to | |||
.Sx ASCII Output . | |||
This output mode can also be selected explicitly with | |||
.Fl T Cm locale . | |||
.Ss Man Output | .Ss Man Output | ||
Translate input format into | Use | ||
.Fl T Cm man | |||
to translate | |||
.Xr mdoc 7 | |||
input into | |||
.Xr man 7 | .Xr man 7 | ||
output format. | output format. | ||
This is useful for distributing manual sources to legacy systems | This is useful for distributing manual sources to legacy systems | ||
|
|
||
.Xr mdoc 7 | .Xr mdoc 7 | ||
formatters. | formatters. | ||
.Pp | .Pp | ||
If | If the input format of a file is | ||
.Xr mdoc 7 | |||
is passed as input, it is translated into | |||
.Xr man 7 . | |||
If the input format is | |||
.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 | ||
level controls which | level controls which | ||
.Sx DIAGNOSTICS | .Sx DIAGNOSTICS | ||
are displayed before copying the input to the output. | are displayed before copying the input to the output. | ||
.Ss Markdown Output | |||
Use | |||
.Fl T Cm markdown | |||
to translate | |||
.Xr mdoc 7 | |||
input to the markdown format conforming to | |||
.Lk http://daringfireball.net/projects/markdown/syntax.text\ | |||
"John Gruber's 2004 specification" . | |||
The output also almost conforms to the | |||
.Lk http://commonmark.org/ CommonMark | |||
specification. | |||
.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 | |||
lost, and even part of the presentational markup may be lost. | |||
Do not use this as an intermediate step in converting to HTML; | |||
instead, use | |||
.Fl T Cm html | |||
directly. | |||
.Pp | |||
The | |||
.Xr man 7 , | |||
.Xr tbl 7 , | |||
and | |||
.Xr eqn 7 | |||
input languages are not supported by | |||
.Fl T Cm markdown | |||
output mode. | |||
.Ss PDF Output | .Ss PDF Output | ||
PDF-1.1 output may be generated by | PDF-1.1 output may be generated by | ||
.Fl T Ns Cm pdf . | .Fl T Cm pdf . | ||
See | See | ||
.Sx PostScript Output | .Sx PostScript Output | ||
for | for | ||
|
|
||
PostScript | PostScript | ||
.Qq Adobe-3.0 | .Qq Adobe-3.0 | ||
Level-2 pages may be generated by | Level-2 pages may be generated by | ||
.Fl T Ns Cm ps . | .Fl T Cm ps . | ||
Output pages default to letter sized and are rendered in the Times font | Output pages default to letter sized and are rendered in the Times font | ||
family, 11-point. | family, 11-point. | ||
Margins are calculated as 1/9 the page length and width. | Margins are calculated as 1/9 the page length and width. | ||
|
|
||
.Ar letter | .Ar letter | ||
is used. | is used. | ||
.El | .El | ||
.Ss UTF\-8 Output | .Ss UTF-8 Output | ||
Use | Use | ||
.Fl T Ns Cm utf8 | .Fl T Cm utf8 | ||
to force a UTF\-8 locale. | to force text output in UTF-8 multi-byte character encoding, | ||
ignoring the | |||
.Xr locale 1 | |||
settings in the environment. | |||
See | See | ||
.Sx Locale Output | .Sx ASCII Output | ||
for details and options. | regarding font styles and | ||
.Fl O | |||
arguments. | |||
.Pp | |||
On operating systems lacking locale or wide character support, and | |||
on those where the internal character representation is not UCS-4, | |||
.Nm | |||
always falls back to | |||
.Sx ASCII Output . | |||
.Ss Syntax tree output | |||
Use | |||
.Fl T Cm tree | |||
to show a human readable representation of the syntax tree. | |||
It is useful for debugging the source code of manual pages. | |||
The exact format is subject to change, so don't write parsers for it. | |||
.Pp | |||
The first paragraph shows meta data found in the | |||
.Xr mdoc 7 | |||
prologue, on the | |||
.Xr man 7 | |||
.Ic \&TH | |||
line, or the fallbacks used. | |||
.Pp | |||
In the tree dump, each output line shows one syntax tree node. | |||
Child nodes are indented with respect to their parent node. | |||
The columns are: | |||
.Pp | |||
.Bl -enum -compact | |||
.It | |||
For macro nodes, the macro name; for text and | |||
.Xr tbl 7 | |||
nodes, the content. | |||
There is a special format for | |||
.Xr eqn 7 | |||
nodes. | |||
.It | |||
Node type (text, elem, block, head, body, body-end, tail, tbl, eqn). | |||
.It | |||
Flags: | |||
.Bl -dash -compact | |||
.It | |||
An opening parenthesis if the node is an opening delimiter. | |||
.It | |||
An asterisk if the node starts a new input line. | |||
.It | |||
The input line number (starting at one). | |||
.It | |||
A colon. | |||
.It | |||
The input column number (starting at one). | |||
.It | |||
A closing parenthesis if the node is a closing delimiter. | |||
.It | |||
A full stop if the node ends a sentence. | |||
.It | |||
BROKEN if the node is a block broken by another block. | |||
.It | |||
NOSRC if the node is not in the input file, | |||
but automatically generated from macros. | |||
.It | |||
NOPRT if the node is not supposed to generate output | |||
for any output format. | |||
.El | |||
.El | |||
.Pp | |||
The following | |||
.Fl O | |||
argument is accepted: | |||
.Bl -tag -width Ds | |||
.It Cm noval | |||
Skip validation and show the unvalidated syntax tree. | |||
This can help to find out whether a given behaviour is caused by | |||
the parser or by the validator. | |||
Meta data is not available in this case. | |||
.El | |||
.Sh ENVIRONMENT | .Sh ENVIRONMENT | ||
.Bl -tag -width MANPAGER | .Bl -tag -width MANPAGER | ||
.It Ev LC_CTYPE | |||
The character encoding | |||
.Xr locale 1 . | |||
When | |||
.Sx Locale Output | |||
is selected, it decides whether to use ASCII or UTF-8 output format. | |||
It never affects the interpretation of input files. | |||
.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 | ||
is not defined. | is not defined. | ||
If neither PAGER nor MANPAGER is defined, | If neither PAGER nor MANPAGER is defined, | ||
.Pa /usr/bin/more Fl s | .Xr more 1 | ||
will be used. | .Fl s | ||
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 Ns 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 Ns Cm error | .Fl W Cm error | ||
or | or a lower | ||
.Fl W Ns 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 Ns Cm unsupp , | .Fl W Cm unsupp | ||
.Fl W Ns Cm error | or a lower | ||
or | .Ar level | ||
.Fl W Ns 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. | ||
|
|
||
.El | .El | ||
.Pp | .Pp | ||
Note that selecting | Note that selecting | ||
.Fl T Ns Cm lint | .Fl T Cm lint | ||
output mode implies | output mode implies | ||
.Fl W Ns 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 \-Wall,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 | ||
.Ar style.css | .Pa /usr/share/misc/mandoc.css | ||
as the style-sheet: | as the style-sheet: | ||
.Pp | .Pp | ||
.Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html | .Dl $ mandoc \-T html -O style=/usr/share/misc/mandoc.css mdoc.7 > mdoc.7.html | ||
.Pp | .Pp | ||
To check over a large set of manuals: | To check over a large set of manuals: | ||
.Pp | .Pp | ||
.Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]` | .Dl $ mandoc \-T lint \(gafind /usr/src -name \e*\e.[1-9]\(ga | ||
.Pp | .Pp | ||
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 \-T ps \-O paper=a4 mdoc.7 man.7 > manuals.ps | ||
.Pp | .Pp | ||
Convert a modern | Convert a modern | ||
.Xr mdoc 7 | .Xr mdoc 7 | ||
|
|
||
.Xr mdoc 7 | .Xr mdoc 7 | ||
parser: | parser: | ||
.Pp | .Pp | ||
.Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man | .Dl $ mandoc \-T man foo.mdoc > foo.man | ||
.Sh DIAGNOSTICS | .Sh DIAGNOSTICS | ||
Messages displayed by | Messages displayed by | ||
.Nm | .Nm | ||
follow this format: | follow this format: | ||
.Bd -ragged -offset indent | |||
.Nm : | |||
.Ar file : Ns Ar line : Ns Ar column : level : message : macro arguments | |||
.Pq Ar os | |||
.Ed | |||
.Pp | .Pp | ||
.D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args | The first three fields identify the | ||
.Pp | .Ar file | ||
Line and column numbers start at 1. | name, | ||
.Ar line | |||
number, and | |||
.Ar column | |||
number of the input file where the message was triggered. | |||
The 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. | All | ||
.Ar level | |||
and | |||
.Ar message | |||
strings are explained below. | |||
The name of the | |||
.Ar macro | |||
triggering the message and its | |||
.Ar 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 | ||
|
|
||
.Nm | .Nm | ||
to process the file may be preferable. | to process the file may be preferable. | ||
.It Cm error | .It Cm error | ||
An input file contains invalid syntax that cannot be safely interpreted. | Indicates a risk of information loss or severe misformatting, | ||
By discarding part of the input or inserting missing tokens, | in most cases caused by serious syntax errors. | ||
the parser is able to continue, and the error does not prevent | |||
generation of formatted output, but typically, preparing that | |||
output involves information loss, broken document structure | |||
or unintended formatting, no matter whether | |||
.Nm | |||
or GNU troff is used. | |||
In many cases, the output of | |||
.Nm | |||
and GNU troff is identical, but in some, | |||
.Nm | |||
is more resilient than GNU troff with respect to malformed input. | |||
.Pp | |||
Non-existent or unreadable input files are also reported on the | |||
.Cm error | |||
level. | |||
In that case, the parser cannot even be started and no output | |||
is produced from those input files. | |||
.It Cm warning | .It Cm warning | ||
An input file uses obsolete, discouraged or non-portable syntax. | Indicates a risk that the information shown or its formatting | ||
All the same, the meaning of the input is unambiguous and a correct | may mismatch the author's intent in minor ways. | ||
rendering can be produced. | Additionally, syntax errors are classified at least as warnings, | ||
Documents causing warnings may render poorly when using other | even if they do not usually cause misformatting. | ||
formatting tools instead of | .It Cm style | ||
.Nm . | 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 convention 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. | |||
Messages of the | |||
.Cm base | |||
level are printed with the more intuitive | |||
.Cm style | |||
.Ar level | |||
tag. | |||
.El | .El | ||
.Pp | .Pp | ||
Messages of the | Messages of the | ||
.Cm base , | |||
.Cm style , | |||
.Cm warning , | .Cm warning , | ||
.Cm error , | .Cm error , | ||
and | and | ||
|
|
||
are hidden unless their level, or a lower level, is requested using a | are hidden unless their level, or a lower level, is requested using a | ||
.Fl W | .Fl W | ||
option or | option or | ||
.Fl T Ns 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 "unknown architecture" | |||
.Pq mdoc , Ox , Nx | |||
The third argument of the | |||
.Ic \&Dt | |||
macro does not match any of the architectures this operating system | |||
is running on. | |||
.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. | |||
.It Sy "referenced manual not found" | |||
.Pq mdoc | |||
An | |||
.Ic \&Xr | |||
macro references a manual page that is not found in the base system. | |||
The path to look for base system manuals is configurable at compile | |||
time and defaults to | |||
.Pa /usr/share/man : /usr/X11R6/man . | |||
.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 "normalizing date format to" : No ... | |||
.Pq mdoc , man | |||
The | |||
.Ic \&Dd | |||
or | |||
.Ic \&TH | |||
macro provides an abbreviated month name or a day number with a | |||
leading zero. | |||
In the formatted output, the month name is written out in full | |||
and the leading zero is omitted. | |||
.It Sy "lower case character in document title" | |||
.Pq mdoc , man | |||
The title is still used as given in the | |||
.Ic \&Dt | |||
or | |||
.Ic \&TH | |||
macro. | |||
.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 "possible typo in section name" | |||
.Pq mdoc | |||
Fuzzy string matching revealed that the argument of an | |||
.Ic \&Sh | |||
macro is similar, but not identical to a standard section name. | |||
.It Sy "unterminated quoted argument" | |||
.Pq roff | |||
Macro arguments can be enclosed in double quote characters | |||
such that space characters and macro names contained in the quoted | |||
argument need not be escaped. | |||
The closing quote of the last argument of a macro can be omitted. | |||
However, omitting it is not recommended because it makes the code | |||
harder to read. | |||
.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 "trailing delimiter" | |||
.Pq mdoc | |||
The last argument of an | |||
.Ic \&Ex , \&Fo , \&Nd , \&Nm , \&Os , \&Sh , \&Ss , \&St , | |||
or | |||
.Ic \&Sx | |||
macro ends with a trailing delimiter. | |||
This is usually bad style and often indicates typos. | |||
Most likely, the delimiter can be removed. | |||
.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 "fill mode already enabled, skipping" | |||
.Pq man | |||
A | |||
.Ic \&fi | |||
request occurs even though the document is still in fill mode, | |||
or already switched back to fill mode. | |||
It has no effect. | |||
.It Sy "fill mode already disabled, skipping" | |||
.Pq man | |||
An | |||
.Ic \&nf | |||
request occurs even though the document already switched to no-fill mode | |||
and did not switch back to fill mode yet. | |||
It has no effect. | |||
.It Sy "verbatim \(dq--\(dq, maybe consider using \e(em" | |||
.Pq mdoc | |||
Even though the ASCII output device renders an em-dash as | |||
.Qq \-\- , | |||
that is not a good way to write it in an input file | |||
because it renders poorly on all other output devices. | |||
.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. | |||
.It Sy "whitespace at end of input line" | |||
.Pq mdoc , man , roff | |||
Whitespace at the end of input lines is almost never semantically | |||
significant \(em but in the odd case where it might be, it is | |||
extremely confusing when reviewing and maintaining documents. | |||
.It Sy "bad comment style" | |||
.Pq roff | |||
Comment lines start with a dot, a backslash, and a double-quote character. | |||
The | |||
.Nm | |||
utility treats the line as a comment line even without the backslash, | |||
but leaving out the backslash might not be portable. | |||
.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" | ||
|
|
||
There is no | There is no | ||
.Ic \&TH | .Ic \&TH | ||
macro, or it has no arguments. | macro, or it has no arguments. | ||
.It Sy "lower case character in document title" | |||
.Pq mdoc , man | |||
The title is still used as given in the | |||
.Ic \&Dt | |||
or | |||
.Ic \&TH | |||
macro. | |||
.It Sy "missing manual section, using \(dq\(dq" | .It Sy "missing manual section, using \(dq\(dq" | ||
.Pq mdoc , man | .Pq mdoc , man | ||
A | A | ||
|
|
||
or | or | ||
.Ic \&TH | .Ic \&TH | ||
macro does not follow the conventional format. | macro does not follow the conventional format. | ||
.It Sy "date in the future, using it anyway" | |||
.Pq mdoc , man | |||
The date given in a | |||
.Ic \&Dd | |||
or | |||
.Ic \&TH | |||
macro is more than a day ahead of the current system | |||
.Xr time 3 . | |||
.It Sy "missing Os macro, using \(dq\(dq" | .It Sy "missing Os macro, using \(dq\(dq" | ||
.Pq mdoc | .Pq mdoc | ||
The default or current system is not shown in this case. | The default or current system is not shown in this case. | ||
.It Sy "duplicate prologue macro" | |||
.Pq mdoc | |||
One of the prologue macros occurs more than once. | |||
The last instance overrides all previous ones. | |||
.It Sy "late prologue macro" | .It Sy "late prologue macro" | ||
.Pq mdoc | .Pq mdoc | ||
A | A | ||
|
|
||
or | or | ||
.Ic \&Os | .Ic \&Os | ||
macro occurs after some non-prologue macro, but still takes effect. | macro occurs after some non-prologue macro, but still takes effect. | ||
.It Sy "skipping late title macro" | |||
.Pq mdoc | |||
The | |||
.Ic \&Dt | |||
macro can only occur before the first non-prologue macro | |||
because traditional formatters write the page header | |||
before parsing the document body. | |||
Even though this technical restriction does not apply to | |||
.Nm , | |||
traditional semantics is preserved. | |||
The late macro is discarded including its arguments. | |||
.It Sy "prologue macros out of order" | .It Sy "prologue macros out of order" | ||
.Pq mdoc | .Pq mdoc | ||
The prologue macros are not given in the conventional order | The prologue macros are not given in the conventional order | ||
|
|
||
.Xr makewhatis 8 | .Xr makewhatis 8 | ||
and | and | ||
.Xr apropos 1 . | .Xr apropos 1 . | ||
.It Sy "bad NAME section contents" | .It Sy "NAME section without Nm before Nd" | ||
.Pq mdoc | .Pq mdoc | ||
The last node in the NAME section is not an | The NAME section does not contain any | ||
.Ic \&Nm | |||
child macro before the first | |||
.Ic \&Nd | .Ic \&Nd | ||
macro, or any preceding macro is not | macro. | ||
.Ic \&Nm , | .It Sy "NAME section without description" | ||
or the NAME section is completely empty. | .Pq mdoc | ||
This may confuse | The NAME section lacks the mandatory | ||
.Xr makewhatis 8 | .Ic \&Nd | ||
child macro. | |||
.It Sy "description not at the end of NAME" | |||
.Pq mdoc | |||
The NAME section does contain an | |||
.Ic \&Nd | |||
child macro, but other content follows it. | |||
.It Sy "bad NAME section content" | |||
.Pq mdoc | |||
The NAME section contains plain text or macros other than | |||
.Ic \&Nm | |||
and | and | ||
.Xr apropos 1 . | .Ic \&Nd . | ||
.It Sy "missing comma before name" | |||
.Pq mdoc | |||
The NAME section contains an | |||
.Ic \&Nm | |||
macro that is neither the first one nor preceded by a comma. | |||
.It Sy "missing description line, using \(dq\(dq" | .It Sy "missing description line, using \(dq\(dq" | ||
.Pq mdoc | .Pq mdoc | ||
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. | ||
|
|
||
.Pq mdoc | .Pq mdoc | ||
A standard section header occurs in a section of the manual | A standard section header occurs in a section of the manual | ||
where it normally isn't useful. | where it normally isn't useful. | ||
.It Sy "cross reference to self" | |||
.Pq mdoc | |||
An | |||
.Ic \&Xr | |||
macro refers to a name and section matching the section of the present | |||
manual page and a name mentioned in an | |||
.Ic \&Nm | |||
macro in the NAME or SYNOPSIS section, or in an | |||
.Ic \&Fn | |||
or | |||
.Ic \&Fo | |||
macro in the SYNOPSIS. | |||
Consider using | |||
.Ic \&Nm | |||
or | |||
.Ic \&Fn | |||
instead of | |||
.Ic \&Xr . | |||
.It Sy "unusual Xr order" | .It Sy "unusual Xr order" | ||
.Pq mdoc | .Pq mdoc | ||
In the SEE ALSO section, an | In the SEE ALSO section, an | ||
|
|
||
macro with a lower section number follows one with a higher number, | macro with a lower section number follows one with a higher number, | ||
or two | or two | ||
.Ic \&Xr | .Ic \&Xr | ||
macros refering to the same section are out of alphabetical order. | macros referring to the same section are out of alphabetical order. | ||
.It Sy "unusual Xr punctuation" | .It Sy "unusual Xr punctuation" | ||
.Pq mdoc | .Pq mdoc | ||
In the SEE ALSO section, punctuation between two | In the SEE ALSO section, punctuation between two | ||
|
|
||
.Pq mdoc | .Pq mdoc | ||
The name of a macro that is not callable appears on a macro line. | The name of a macro that is not callable appears on a macro line. | ||
It is printed verbatim. | It is printed verbatim. | ||
If the intention is to call it, move it to its own line; | If the intention is to call it, move it to its own input line; | ||
otherwise, escape it by prepending | otherwise, escape it by prepending | ||
.Sq \e& . | .Sq \e& . | ||
.It Sy "skipping paragraph macro" | .It Sy "skipping paragraph macro" | ||
|
|
||
.Pq mdoc | .Pq mdoc | ||
An input line begins with an | An input line begins with an | ||
.Ic \&Ns | .Ic \&Ns | ||
macro. | macro, or the next argument after an | ||
.Ic \&Ns | |||
macro is an isolated closing delimiter. | |||
The macro is ignored. | The macro is ignored. | ||
.It Sy "blocks badly nested" | .It Sy "blocks badly nested" | ||
.Pq mdoc | .Pq mdoc | ||
|
|
||
.Ic \&It | .Ic \&It | ||
macro. | macro. | ||
The offending children are moved before the beginning of the list. | The offending children are moved before the beginning of the list. | ||
.It Sy ".Vt block has child macro" | .It Sy "first macro on line" | ||
.Pq mdoc | Inside a | ||
The | .Ic \&Bl Fl column | ||
.Ic \&Vt | list, a | ||
macro supports plain text arguments only. | .Ic \&Ta | ||
Formatting may be ugly and semantic searching | macro occurs as the first macro on a line, which is not portable. | ||
for the affected content might not work. | |||
.It Sy "fill mode already enabled, skipping" | |||
.Pq man | |||
A | |||
.Ic \&fi | |||
request occurs even though the document is still in fill mode, | |||
or already switched back to fill mode. | |||
It has no effect. | |||
.It Sy "fill mode already disabled, skipping" | |||
.Pq man | |||
An | |||
.Ic \&nf | |||
request occurs even though the document already switched to no-fill mode | |||
and did not switch back to fill mode yet. | |||
It has no effect. | |||
.It Sy "line scope broken" | .It Sy "line scope broken" | ||
.Pq man | .Pq man | ||
While parsing the next-line scope of the previous macro, | While parsing the next-line scope of the previous macro, | ||
|
|
||
clause. | clause. | ||
.It Sy "skipping empty macro" | .It Sy "skipping empty macro" | ||
.Pq mdoc | .Pq mdoc | ||
The indicated macro has no arguments or no body content | The indicated macro has no arguments and hence no effect. | ||
and hence no effect. | .It Sy "empty block" | ||
.Pq mdoc , man | |||
A | |||
.Ic \&Bd , | |||
.Ic \&Bk , | |||
.Ic \&Bl , | |||
.Ic \&D1 , | |||
.Ic \&Dl , | |||
.Ic \&MT , | |||
.Ic \&RS , | |||
or | |||
.Ic \&UR | |||
block contains nothing in its body and will produce no output. | |||
.It Sy "empty argument, using 0n" | .It Sy "empty argument, using 0n" | ||
.Pq mdoc | .Pq mdoc | ||
The required width is missing after | The required width is missing after | ||
|
|
||
.Ic \&Bl | .Ic \&Bl | ||
.Fl offset | .Fl offset | ||
or | or | ||
.Fl width. | .Fl width . | ||
.It Sy "argument count wrong" | |||
.Pq mdoc , man | |||
The indicated macro has too few or too many arguments. | |||
The syntax tree will contain the wrong number of arguments as given. | |||
Formatting behaviour depends on the specific macro in question. | |||
Note that the same message may also occur as an ERROR, see below. | |||
.It Sy "missing display type, using -ragged" | .It Sy "missing display type, using -ragged" | ||
.Pq mdoc | .Pq mdoc | ||
The | The | ||
|
|
||
macro is called without an argument before | macro is called without an argument before | ||
.Ic \&Nm | .Ic \&Nm | ||
has first been called with an argument. | has first been called with an argument. | ||
.It Sy "missing function name, using \(dq\(dq" | |||
.Pq mdoc | |||
The | |||
.Ic \&Fo | |||
macro is called without an argument. | |||
No function name is printed. | |||
.It Sy "empty head in list item" | .It Sy "empty head in list item" | ||
.Pq mdoc | .Pq mdoc | ||
In a | In a | ||
|
|
||
.Ic \&It | .Ic \&It | ||
block is empty. | block is empty. | ||
An empty list item is shown. | An empty list item is shown. | ||
.It Sy "missing font type" | .It Sy "missing argument, using next line" | ||
.Pq mdoc | .Pq mdoc | ||
An | |||
.Ic \&It | |||
macro in a | |||
.Ic \&Bd Fl column | |||
list has no arguments. | |||
While | |||
.Nm | |||
uses the text or macros of the following line, if any, for the cell, | |||
other formatters may misformat the list. | |||
.It Sy "missing font type, using \efR" | |||
.Pq mdoc | |||
A | A | ||
.Ic \&Bf | .Ic \&Bf | ||
macro has no argument. | macro has no argument. | ||
It switches to the default font, | It switches to the default font. | ||
.Cm \efR . | .It Sy "unknown font type, using \efR" | ||
.It Sy "unknown font type" | |||
.Pq mdoc | .Pq mdoc | ||
The | The | ||
.Ic \&Bf | .Ic \&Bf | ||
argument is invalid. | argument is invalid. | ||
The default font | The default font is used instead. | ||
.Cm \efR | |||
is used instead. | |||
.It Sy "nothing follows prefix" | .It Sy "nothing follows prefix" | ||
.Pq mdoc | .Pq mdoc | ||
A | A | ||
|
|
||
.Ic \&Re | .Ic \&Re | ||
macro on the next input line. | macro on the next input line. | ||
Such an empty block does not produce any output. | Such an empty block does not produce any output. | ||
.It Sy "missing section argument" | |||
.Pq mdoc | |||
An | |||
.Ic \&Xr | |||
macro lacks its second, section number argument. | |||
The first argument, i.e. the name, is printed, but without subsequent | |||
parentheses. | |||
.It Sy "missing -std argument, adding it" | .It Sy "missing -std argument, adding it" | ||
.Pq mdoc | .Pq mdoc | ||
An | An | ||
|
|
||
utility assumes | utility assumes | ||
.Fl std | .Fl std | ||
even when it is not specified, but other implementations may not. | even when it is not specified, but other implementations may not. | ||
.It Sy "missing option string, using \(dq\(dq" | |||
.Pq man | |||
The | |||
.Ic \&OP | |||
macro is invoked without any argument. | |||
An empty pair of square brackets is shown. | |||
.It Sy "missing resource identifier, using \(dq\(dq" | |||
.Pq man | |||
The | |||
.Ic \&MT | |||
or | |||
.Ic \&UR | |||
macro is invoked without any argument. | |||
An empty pair of angle brackets is shown. | |||
.It Sy "missing eqn box, using \(dq\(dq" | .It Sy "missing eqn box, using \(dq\(dq" | ||
.Pq eqn | .Pq eqn | ||
A diacritic mark or a binary operator is found, | A diacritic mark or a binary operator is found, | ||
|
|
||
.El | .El | ||
.Ss "Warnings related to bad macro arguments" | .Ss "Warnings related to bad macro arguments" | ||
.Bl -ohang | .Bl -ohang | ||
.It Sy "unterminated quoted argument" | |||
.Pq roff | |||
Macro arguments can be enclosed in double quote characters | |||
such that space characters and macro names contained in the quoted | |||
argument need not be escaped. | |||
The closing quote of the last argument of a macro can be omitted. | |||
However, omitting it is not recommended because it makes the code | |||
harder to read. | |||
.It Sy "duplicate argument" | .It Sy "duplicate argument" | ||
.Pq mdoc | .Pq mdoc | ||
A | A | ||
|
|
||
.Fl width | .Fl width | ||
argument. | argument. | ||
That has no effect. | That has no effect. | ||
.It Sy "wrong number of cells" | |||
In a line of a | |||
.Ic \&Bl Fl column | |||
list, the number of tabs or | |||
.Ic \&Ta | |||
macros is less than the number expected from the list header line | |||
or exceeds the expected number by more than one. | |||
Missing cells remain empty, and all cells exceeding the number of | |||
columns are joined into one single cell. | |||
.It Sy "unknown AT&T UNIX version" | .It Sy "unknown AT&T UNIX version" | ||
.Pq mdoc | .Pq mdoc | ||
An | An | ||
|
|
||
.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 | ||
|
|
||
.Cm off . | .Cm off . | ||
The invalid argument is moved out of the macro, which leaves the macro | The invalid argument is moved out of the macro, which leaves the macro | ||
empty, causing it to toggle the spacing mode. | empty, causing it to toggle the spacing mode. | ||
.It Sy "argument contains two font escapes" | |||
.Pq roff | |||
The second argument of a | |||
.Ic char | |||
request contains more than one font escape sequence. | |||
A wrong font may remain active after using the character. | |||
.It Sy "unknown font, skipping request" | .It Sy "unknown font, skipping request" | ||
.Pq man , tbl | .Pq man , tbl | ||
A | A | ||
|
|
||
layout modifier has an unknown | layout modifier has an unknown | ||
.Ar font | .Ar font | ||
argument. | argument. | ||
.It Sy "odd number of characters in request" | |||
.Pq roff | |||
A | |||
.Ic \&tr | |||
request contains an odd number of characters. | |||
The last character is mapped to the blank character. | |||
.El | .El | ||
.Ss "Warnings related to plain text" | .Ss "Warnings related to plain text" | ||
.Bl -ohang | .Bl -ohang | ||
|
|
||
In fill mode, line breaks of text input lines are not supposed to be | In fill mode, line breaks of text input lines are not supposed to be | ||
significant. | significant. | ||
However, for compatibility with groff, blank lines in fill mode | However, for compatibility with groff, blank lines in fill mode | ||
are replaced with | are formatted like | ||
.Ic \&sp | .Ic \&sp | ||
requests. | requests. | ||
To request a paragraph break, use | |||
.Ic \&Pp | |||
instead of a blank line. | |||
.It Sy "tab in filled text" | .It Sy "tab in filled text" | ||
.Pq mdoc , man | .Pq mdoc , man | ||
The meaning of tab characters is only well-defined in non-fill mode: | The meaning of tab characters is only well-defined in non-fill mode: | ||
|
|
||
are passed through to the formatters in any case. | are passed through to the formatters in any case. | ||
Given that the text before the tab character will be filled, | Given that the text before the tab character will be filled, | ||
it is hard to predict which tab stop position the tab will advance to. | it is hard to predict which tab stop position the tab will advance to. | ||
.It Sy "whitespace at end of input line" | .It Sy "new sentence, new line" | ||
.Pq mdoc , man , roff | .Pq mdoc | ||
Whitespace at the end of input lines is almost never semantically | A new sentence starts in the middle of a text line. | ||
significant \(em but in the odd case where it might be, it is | Start it on a new input line to help formatters produce correct spacing. | ||
extremely confusing when reviewing and maintaining documents. | |||
.It Sy "bad comment style" | |||
.Pq roff | |||
Comment lines start with a dot, a backslash, and a double-quote character. | |||
The | |||
.Nm | |||
utility treats the line as a comment line even without the backslash, | |||
but leaving out the backslash might not be portable. | |||
.It Sy "invalid escape sequence" | .It Sy "invalid escape sequence" | ||
.Pq roff | .Pq roff | ||
An escape sequence has an invalid opening argument delimiter, lacks the | An escape sequence has an invalid opening argument delimiter, lacks the | ||
closing argument delimiter, or the argument has too few characters. | closing argument delimiter, the argument is of an invalid form, or it is | ||
a character escape sequence with an invalid name. | |||
If the argument is incomplete, | If the argument is incomplete, | ||
.Ic \e* | .Ic \e* | ||
and | and | ||
|
|
||
.Ic \ew | .Ic \ew | ||
to the length of the incomplete argument. | to the length of the incomplete argument. | ||
All other invalid escape sequences are ignored. | All other invalid escape sequences are ignored. | ||
.It Sy "undefined escape, printing literally" | |||
.Pq roff | |||
In an escape sequence, the first character | |||
right after the leading backslash is invalid. | |||
That character is printed literally, | |||
which is equivalent to ignoring the backslash. | |||
.It Sy "undefined string, using \(dq\(dq" | .It Sy "undefined string, using \(dq\(dq" | ||
.Pq roff | .Pq roff | ||
If a string is used without being defined before, | If a string is used without being defined before, | ||
|
|
||
.El | .El | ||
.Ss "Errors related to roff, mdoc, and man code" | .Ss "Errors related to roff, mdoc, and man code" | ||
.Bl -ohang | .Bl -ohang | ||
.It Sy "duplicate prologue macro" | |||
.Pq mdoc | |||
One of the prologue macros occurs more than once. | |||
The last instance overrides all previous ones. | |||
.It Sy "skipping late title macro" | |||
.Pq mdoc | |||
The | |||
.Ic \&Dt | |||
macro appears after the first non-prologue macro. | |||
Traditional formatters cannot handle this because | |||
they write the page header before parsing the document body. | |||
Even though this technical restriction does not apply to | |||
.Nm , | |||
traditional semantics is preserved. | |||
The late macro is discarded including its arguments. | |||
.It Sy "input stack limit exceeded, infinite loop?" | .It Sy "input stack limit exceeded, infinite loop?" | ||
.Pq roff | .Pq roff | ||
Explicit recursion limits are implemented for the following features, | Explicit recursion limits are implemented for the following features, | ||
|
|
||
macro. | macro. | ||
It may be mistyped or unsupported. | It may be mistyped or unsupported. | ||
The request or macro is discarded including its arguments. | The request or macro is discarded including its arguments. | ||
.It Sy "skipping request outside macro" | |||
.Pq roff | |||
A | |||
.Ic shift | |||
or | |||
.Ic return | |||
request occurs outside any macro definition and has no effect. | |||
.It Sy "skipping insecure request" | .It Sy "skipping insecure request" | ||
.Pq roff | .Pq roff | ||
An input file attempted to run a shell command | An input file attempted to run a shell command | ||
|
|
||
.Xr mdoc 7 | .Xr mdoc 7 | ||
block closing macro, a | block closing macro, a | ||
.Xr man 7 | .Xr man 7 | ||
.Ic \&RE | .Ic \&ME , \&RE | ||
or | or | ||
.Ic \&UE | .Ic \&UE | ||
macro, an | macro, an | ||
|
|
||
A block that doesn't support bad nesting | A block that doesn't support bad nesting | ||
ends before all of its children are properly closed. | ends before all of its children are properly closed. | ||
The open child nodes are closed implicitly. | The open child nodes are closed implicitly. | ||
.It Sy "scope open on exit" | .It Sy "appending missing end of block" | ||
.Pq mdoc , man , eqn , tbl , roff | .Pq mdoc , man , eqn , tbl , roff | ||
At the end of the document, an explicit | At the end of the document, an explicit | ||
.Xr mdoc 7 | .Xr mdoc 7 | ||
block, a | block, a | ||
.Xr man 7 | .Xr man 7 | ||
next-line scope or | next-line scope or | ||
.Ic \&RS | .Ic \&MT , \&RS | ||
or | or | ||
.Ic \&UR | .Ic \&UR | ||
block, an equation, table, or | block, an equation, table, or | ||
|
|
||
only the escape sequence is discarded. | only the escape sequence is discarded. | ||
The characters preceding it are used as the request or macro name, | The characters preceding it are used as the request or macro name, | ||
the characters following it are used as the arguments to the request or macro. | the characters following it are used as the arguments to the request or macro. | ||
.It Sy "argument count wrong" | .It Sy "using macro argument outside macro" | ||
.Pq mdoc , man , roff | .Pq roff | ||
The indicated request or macro has too few or too many arguments. | The escape sequence \e$ occurs outside any macro definition | ||
The syntax tree will contain the wrong number of arguments as given. | and expands to the empty string. | ||
Formatting behaviour depends on the specific request or macro in question. | .It Sy "argument number is not numeric" | ||
Note that the same message may also occur as a WARNING, see above. | .Pq roff | ||
The argument of the escape sequence \e$ is not a digit; | |||
the escape sequence expands to the empty string. | |||
.It Sy "NOT IMPLEMENTED: Bd -file" | .It Sy "NOT IMPLEMENTED: Bd -file" | ||
.Pq mdoc | .Pq mdoc | ||
For security reasons, the | For security reasons, the | ||
|
|
||
might otherwise trick a privileged user into inadvertently displaying | might otherwise trick a privileged user into inadvertently displaying | ||
the file on the screen, revealing the file content to bystanders. | the file on the screen, revealing the file content to bystanders. | ||
The argument is ignored including the file name following it. | The argument is ignored including the file name following it. | ||
.It Sy "skipping display without arguments" | |||
.Pq mdoc | |||
A | |||
.Ic \&Bd | |||
block macro does not have any arguments. | |||
The block is discarded, and the block content is displayed in | |||
whatever mode was active before the block. | |||
.It Sy "missing list type, using -item" | .It Sy "missing list type, using -item" | ||
.Pq mdoc | .Pq mdoc | ||
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 "argument is not a character" | |||
.Pq roff | |||
The first argument of a | |||
.Ic char | |||
request is neither a single ASCII character | |||
nor a single character escape sequence. | |||
The request is ignored including all its arguments. | |||
.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 | ||
.Ic \&Nm | .Ic \&Nm , | ||
lacks the required argument. | or any call in the NAME section, lacks the required argument. | ||
.It Sy "uname(3) system call failed, using UNKNOWN" | .It Sy "uname(3) system call failed, using UNKNOWN" | ||
.Pq mdoc | .Pq mdoc | ||
The | The | ||
|
|
||
.Ic \&gsize | .Ic \&gsize | ||
statement has a non-numeric or negative argument or no argument at all. | statement has a non-numeric or negative argument or no argument at all. | ||
The invalid request or statement is ignored. | The invalid request or statement is ignored. | ||
.It Sy "excessive shift" | |||
.Pq roff | |||
The argument of a | |||
.Ic shift | |||
request is larger than the number of arguments of the macro that is | |||
currently being executed. | |||
All macro arguments are deleted and \en(.$ is set to zero. | |||
.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" | .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" | ||
.Pq roff | .Pq roff | ||
For security reasons, | For security reasons, | ||
|
|
||
.Ic \&EN | .Ic \&EN | ||
macro, or a | macro, or a | ||
.Xr roff 7 | .Xr roff 7 | ||
.Ic \&br | .Ic \&br , | ||
.Ic \&fi , | |||
or | |||
.Ic \&nf | |||
request or | request or | ||
.Sq \&.. | .Sq \&.. | ||
block closing request is invoked with at least one argument. | block closing request is invoked with at least one argument. | ||
All arguments are ignored. | All arguments are ignored. | ||
.It Sy "skipping excess arguments" | .It Sy "skipping excess arguments" | ||
.Pq mdoc , man , roff | .Pq mdoc , man , roff | ||
The | A macro or request is invoked with too many arguments: | ||
.Bl -dash -offset 2n -width 2n -compact | |||
.It | |||
.Ic \&Fo , | |||
.Ic \&MT , | |||
.Ic \&PD , | |||
.Ic \&RS , | |||
.Ic \&UR , | |||
.Ic \&ft , | |||
or | |||
.Ic \&sp | |||
with more than one argument | |||
.It | |||
.Ic \&An | .Ic \&An | ||
macro is invoked with another argument after | with another argument after | ||
.Fl split | .Fl split | ||
or | or | ||
.Fl nosplit , | .Fl nosplit | ||
.It | |||
.Ic \&RE | |||
with more than one argument or with a non-integer argument | |||
.It | |||
.Ic \&OP | |||
or a request of the | |||
.Ic \&de | |||
family with more than two arguments | |||
.It | |||
.Ic \&Dt | |||
with more than three arguments | |||
.It | |||
.Ic \&TH | |||
with more than five arguments | |||
.It | |||
.Ic \&Bd , | .Ic \&Bd , | ||
.Ic \&Bk , | .Ic \&Bk , | ||
or | or | ||
.Ic \&Bl | .Ic \&Bl | ||
are invoked with invalid arguments, the | with invalid arguments | ||
.Ic \&RE | .El | ||
macro is invoked with more than one argument | |||
or with a non-integer argument, the | |||
.Ic \&sp | |||
request is invoked with more than one argument, or a request of the | |||
.Ic \&de | |||
family is invoked with more than two arguments. | |||
The excess arguments are ignored. | The excess arguments are ignored. | ||
.El | .El | ||
.Ss Unsupported features | .Ss Unsupported features | ||
|
|
||
.Nm | .Nm | ||
was found in an input file. | was found in an input file. | ||
It is replaced by a question mark. | It is replaced by a question mark. | ||
.It Sy "unsupported escape sequence" | |||
.Pq roff | |||
An input file contains an escape sequence supported by GNU troff | |||
or Heirloom troff but not by | |||
.Nm , | |||
and it is likely that this will cause information loss | |||
or considerable misformatting. | |||
.It Sy "unsupported roff request" | .It Sy "unsupported roff request" | ||
.Pq roff | .Pq roff | ||
An input file contains a | An input file contains a | ||
|
|
||
.Xr mdoc 7 , | .Xr mdoc 7 , | ||
.Xr roff 7 , | .Xr roff 7 , | ||
.Xr tbl 7 | .Xr tbl 7 | ||
.Sh HISTORY | |||
The | |||
.Nm | |||
utility first appeared in | |||
.Ox 4.8 . | |||
The option | |||
.Fl I | |||
appeared in | |||
.Ox 5.2 , | |||
and | |||
.Fl aCcfhKklMSsw | |||
in | |||
.Ox 5.7 . | |||
.Sh AUTHORS | .Sh AUTHORS | ||
.An -nosplit | |||
The | The | ||
.Nm | .Nm | ||
utility was written by | utility was written by | ||
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv | .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv | ||
and is maintained by | and is maintained by | ||
.An Ingo Schwarze Aq Mt schwarze@openbsd.org . | .An Ingo Schwarze Aq Mt schwarze@openbsd.org . | ||
.Sh BUGS | |||
In | |||
.Fl T Ns Cm html , | |||
the maximum size of an element attribute is determined by | |||
.Dv BUFSIZ , | |||
which is usually 1024 bytes. | |||
Be aware of this when setting long link | |||
formats such as | |||
.Fl O Ns Cm style Ns = Ns Ar really/long/link . |