summaryrefslogtreecommitdiff
path: root/usr/src/man/man1/mandoc.1
diff options
context:
space:
mode:
Diffstat (limited to 'usr/src/man/man1/mandoc.1')
-rw-r--r--usr/src/man/man1/mandoc.1160
1 files changed, 80 insertions, 80 deletions
diff --git a/usr/src/man/man1/mandoc.1 b/usr/src/man/man1/mandoc.1
index eaafde344f..f3ed8b4e92 100644
--- a/usr/src/man/man1/mandoc.1
+++ b/usr/src/man/man1/mandoc.1
@@ -39,9 +39,9 @@ utility formats manual pages for display.
By default,
.Nm
reads
-.Xr mdoc 5
+.Xr mdoc 7
or
-.Xr man 5
+.Xr man 7
text from stdin and produces
.Fl T Cm locale
output.
@@ -67,10 +67,10 @@ It can be specified to override
Override the default operating system
.Ar name
for the
-.Xr mdoc 5
+.Xr mdoc 7
.Ic \&Os
and for the
-.Xr man 5
+.Xr man 7
.Ic \&TH
macro.
.It Fl K Ar encoding
@@ -110,20 +110,20 @@ Otherwise, input is interpreted as
With
.Fl mdoc ,
all input files are interpreted as
-.Xr mdoc 5 .
+.Xr mdoc 7 .
With
.Fl man ,
all input files are interpreted as
-.Xr man 5 .
+.Xr man 7 .
By default, the input language is automatically detected for each file:
if the first macro is
.Ic \&Dd
or
.Ic \&Dt ,
the
-.Xr mdoc 5
+.Xr mdoc 7
parser is used; otherwise, the
-.Xr man 5
+.Xr man 7
parser is used.
With other arguments,
.Fl m
@@ -223,7 +223,7 @@ reads from standard input.
Use
.Fl T Cm ascii
to force text output in 7-bit ASCII character encoding documented in the
-.Xr ascii 5
+.Xr ascii 7
manual page, ignoring the
.Xr locale 1
set in the environment.
@@ -247,14 +247,14 @@ To remove the markup, pipe the output to
instead.
.Pp
The special characters documented in
-.Xr mandoc_char 5
+.Xr mandoc_char 7
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 5
+.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
@@ -269,18 +269,18 @@ arguments are accepted:
The left margin for normal text is set to
.Ar indent
blank characters instead of the default of five for
-.Xr mdoc 5
+.Xr mdoc 7
and seven for
-.Xr man 5 .
+.Xr man 7 .
Increasing this is not recommended; it may result in degraded formatting,
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 5
+.Xr man 7
input files in
-.Xr mdoc 5
+.Xr mdoc 7
output style.
This prints the operating system name rather than the page title
on the right side of the footer line, and it implies
@@ -288,7 +288,7 @@ on the right side of the footer line, and it implies
One useful application is for checking that
.Fl T Cm man
output formats in the same way as the
-.Xr mdoc 5
+.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,
@@ -325,7 +325,7 @@ Output produced by
conforms to HTML5 using optional self-closing tags.
Default styles use only CSS1.
Equations rendered from
-.Xr eqn 5
+.Xr eqn 7
blocks use MathML.
.Pp
The file
@@ -440,22 +440,22 @@ This output mode can also be selected explicitly with
Use
.Fl T Cm man
to translate
-.Xr mdoc 5
+.Xr mdoc 7
input into
-.Xr man 5
+.Xr man 7
output format.
This is useful for distributing manual sources to legacy systems
lacking
-.Xr mdoc 5
+.Xr mdoc 7
formatters.
Embedded
-.Xr eqn 5
+.Xr eqn 7
and
-.Xr tbl 5
+.Xr tbl 7
code is not supported.
.Pp
If the input format of a file is
-.Xr man 5 ,
+.Xr man 7 ,
the input is copied to the output.
The parser is also run, and as usual, the
.Fl W
@@ -466,7 +466,7 @@ are displayed before copying the input to the output.
Use
.Fl T Cm markdown
to translate
-.Xr mdoc 5
+.Xr mdoc 7
input to the markdown format conforming to
.Lk http://daringfireball.net/projects/markdown/syntax.text\
"John Gruber's 2004 specification" .
@@ -489,10 +489,10 @@ instead, use
directly.
.Pp
The
-.Xr man 5 ,
-.Xr tbl 5 ,
+.Xr man 7 ,
+.Xr tbl 7 ,
and
-.Xr eqn 5
+.Xr eqn 7
input languages are not supported by
.Fl T Cm markdown
output mode.
@@ -564,9 +564,9 @@ 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 5
+.Xr mdoc 7
prologue, on the
-.Xr man 5
+.Xr man 7
.Ic \&TH
line, or the fallbacks used.
.Pp
@@ -577,10 +577,10 @@ The columns are:
.Bl -enum -compact
.It
For macro nodes, the macro name; for text and
-.Xr tbl 5
+.Xr tbl 7
nodes, the content.
There is a special format for
-.Xr eqn 5
+.Xr eqn 7
nodes.
.It
Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
@@ -733,11 +733,11 @@ To produce a series of PostScript manuals for A4 paper:
.Dl $ mandoc \-T ps \-O paper=a4 mdoc.5 man.5 > manuals.ps
.Pp
Convert a modern
-.Xr mdoc 5
+.Xr mdoc 7
manual to the older
-.Xr man 5
+.Xr man 7
format, for use on systems lacking an
-.Xr mdoc 5
+.Xr mdoc 7
parser:
.Pp
.Dl $ mandoc \-T man foo.mdoc > foo.man
@@ -793,7 +793,7 @@ Invalid command line arguments were specified.
No input files have been read and no output is produced.
.It Cm unsupp
An input file uses unsupported low-level
-.Xr mandoc_roff 5
+.Xr mandoc_roff 7
features.
The output may be incomplete and/or misformatted,
so using GNU troff instead of
@@ -906,16 +906,16 @@ keyword substitution as conventionally used in these operating systems.
.El
.Ss Style suggestions
.Bl -ohang
-.It Sy "legacy man(5) date format"
+.It Sy "legacy man(7) date format"
.Pq mdoc
The
.Ic \&Dd
macro uses the legacy
-.Xr man 5
+.Xr man 7
date format
.Dq yyyy-dd-mm .
Consider using the conventional
-.Xr mdoc 5
+.Xr mdoc 7
date format
.Dq "Month dd, yyyy"
instead.
@@ -1012,7 +1012,7 @@ and
command line options, the
.Ev MANPATH
environment variable, the
-.Xr man.conf 5
+.Xr man.conf 7
file and falling back to the default of
.Pa /usr/share/man : Ns Pa /usr/X11R6/man : Ns Pa /usr/local/man ,
also configurable at compile time using the
@@ -1120,14 +1120,14 @@ Consider checking whether the file name or the argument need a correction.
.It Sy "missing date, using \(dq\(dq"
.Pq mdoc, man
The document was parsed as
-.Xr mdoc 5
+.Xr mdoc 7
and it has no
.Ic \&Dd
macro, or the
.Ic \&Dd
macro has no arguments or only empty arguments;
or the document was parsed as
-.Xr man 5
+.Xr man 7
and it has no
.Ic \&TH
macro, or the
@@ -1298,7 +1298,7 @@ Probably, there are author names lacking markup.
.It Sy "obsolete macro"
.Pq mdoc
See the
-.Xr mdoc 5
+.Xr mdoc 7
manual for replacements.
.It Sy "macro neither callable nor escaped"
.Pq mdoc
@@ -1309,7 +1309,7 @@ otherwise, escape it by prepending
.Sq \e& .
.It Sy "skipping paragraph macro"
In
-.Xr mdoc 5
+.Xr mdoc 7
documents, this happens
.Bl -dash -compact
.It
@@ -1322,7 +1322,7 @@ at the end of items in non-column, non-compact lists
and for multiple consecutive paragraph macros.
.El
In
-.Xr man 5
+.Xr man 7
documents, it happens
.Bl -dash -compact
.It
@@ -1417,7 +1417,7 @@ The previous, interrupted macro is deleted from the parse tree.
.Pq roff , eqn
The macro name is missing from a macro definition request,
or an
-.Xr eqn 5
+.Xr eqn 7
control statement or operation keyword lacks its required argument.
.It Sy "conditional request controls empty scope"
.Pq roff
@@ -1485,7 +1485,7 @@ macro, at least one other argument precedes the type argument.
The
.Nm
utility copes with any argument order, but some other
-.Xr mdoc 5
+.Xr mdoc 7
implementations do not.
.It Sy "missing -width in -tag list, using 8n"
.Pq mdoc
@@ -1730,10 +1730,10 @@ A wrong font may remain active after using the character.
.It Sy "unknown font, skipping request"
.Pq man , tbl
A
-.Xr mandoc_roff 5
+.Xr mandoc_roff 7
.Ic \&ft
request or a
-.Xr tbl 5
+.Xr tbl 7
.Ic \&f
layout modifier has an unknown
.Ar font
@@ -1924,7 +1924,7 @@ some content, but the parser can continue.
.It Sy "skipping bad character"
.Pq mdoc , man , roff
The input file contains a byte that is not a printable
-.Xr ascii 5
+.Xr ascii 7
character.
The message mentions the character number.
The offending byte is replaced with a question mark
@@ -1934,11 +1934,11 @@ transliteration of the intended character.
.It Sy "skipping unknown macro"
.Pq mdoc , man , roff
The first identifier on a request or macro line is neither recognized as a
-.Xr mandoc_roff 5
+.Xr mandoc_roff 7
request, nor as a user-defined macro, nor, respectively, as an
-.Xr mdoc 5
+.Xr mdoc 7
or
-.Xr man 5
+.Xr man 7
macro.
It may be mistyped or unsupported.
The request or macro is discarded including its arguments.
@@ -1961,7 +1961,7 @@ An
macro occurs outside any
.Ic \&Bl
list, or an
-.Xr eqn 5
+.Xr eqn 7
.Ic above
delimiter occurs outside any pile.
It is discarded including its arguments.
@@ -1978,16 +1978,16 @@ It is discarded including its arguments.
Various syntax elements can only be used to explicitly close blocks
that have previously been opened.
An
-.Xr mdoc 5
+.Xr mdoc 7
block closing macro, a
-.Xr man 5
+.Xr man 7
.Ic \&ME, \&RE
or
.Ic \&UE
macro, an
-.Xr eqn 5
+.Xr eqn 7
right delimiter or closing brace, or the end of an equation, table, or
-.Xr mandoc_roff 5
+.Xr mandoc_roff 7
conditional request is encountered but no matching block is open.
The offending request or macro is discarded.
.It Sy "fewer RS blocks open, skipping"
@@ -2003,7 +2003,7 @@ macro is discarded.
.It Sy "inserting missing end of block"
.Pq mdoc , tbl
Various
-.Xr mdoc 5
+.Xr mdoc 7
macros as well as tables require explicit closing by dedicated macros.
A block that doesn't support bad nesting
ends before all of its children are properly closed.
@@ -2011,15 +2011,15 @@ The open child nodes are closed implicitly.
.It Sy "appending missing end of block"
.Pq mdoc , man , eqn , tbl , roff
At the end of the document, an explicit
-.Xr mdoc 5
+.Xr mdoc 7
block, a
-.Xr man 5
+.Xr man 7
next-line scope or
.Ic \&MT , \&RS
or
.Ic \&UR
block, an equation, table, or
-.Xr mandoc_roff 5
+.Xr mandoc_roff 7
conditional or ignore block is still open.
The open block is closed implicitly.
.It Sy "escaped character not allowed in a name"
@@ -2129,7 +2129,7 @@ macro has an unknown argument and is discarded.
An
.Ic \&it
request or an
-.Xr eqn 5
+.Xr eqn 7
.Ic \&size
or
.Ic \&gsize
@@ -2168,7 +2168,7 @@ only shows the path as it appears behind
.It Sy "skipping all arguments"
.Pq mdoc , man , eqn , roff
An
-.Xr mdoc 5
+.Xr mdoc 7
.Ic \&Bt ,
.Ic \&Ed ,
.Ic \&Ef ,
@@ -2183,18 +2183,18 @@ or
macro, an
.Ic \&It
macro in a list that don't support item heads, a
-.Xr man 5
+.Xr man 7
.Ic \&LP ,
.Ic \&P ,
or
.Ic \&PP
macro, an
-.Xr eqn 5
+.Xr eqn 7
.Ic \&EQ
or
.Ic \&EN
macro, or a
-.Xr mandoc_roff 5
+.Xr mandoc_roff 7
.Ic \&br ,
.Ic \&fi ,
or
@@ -2259,7 +2259,7 @@ Parsing is aborted as soon as the condition is detected.
.It Sy "unsupported control character"
.Pq roff
An ASCII control character supported by other
-.Xr mandoc_roff 5
+.Xr mandoc_roff 7
implementations but not by
.Nm
was found in an input file.
@@ -2274,7 +2274,7 @@ or considerable misformatting.
.It Sy "unsupported roff request"
.Pq roff
An input file contains a
-.Xr mandoc_roff 5
+.Xr mandoc_roff 7
request supported by GNU troff or Heirloom troff but not by
.Nm ,
and it is likely that this will cause information loss
@@ -2292,9 +2292,9 @@ The modifier is discarded.
.It Sy "ignoring macro in table"
.Pq tbl , mdoc , man
A table contains an invocation of an
-.Xr mdoc 5
+.Xr mdoc 7
or
-.Xr man 5
+.Xr man 7
macro or of an undefined macro.
The macro is ignored, and its arguments are handled
as if they were a text line.
@@ -2306,7 +2306,7 @@ macro.
This message is only generated in
.Fl T Cm man
output mode, where
-.Xr tbl 5
+.Xr tbl 7
input is not supported.
.It Sy "skipping eqn in -Tman mode"
.Pq mdoc , eqn
@@ -2316,7 +2316,7 @@ macro.
This message is only generated in
.Fl T Cm man
output mode, where
-.Xr eqn 5
+.Xr eqn 7
input is not supported.
.El
.Ss Bad command line arguments
@@ -2355,22 +2355,22 @@ The
.Fl O Cm tag
option was specified but the tag was not found in any of the displayed
manual pages.
-.It Sy "\-Tmarkdown unsupported for man(5) input"
+.It Sy "\-Tmarkdown unsupported for man(7) input"
.Pq man
The
.Fl T Cm markdown
option was specified but an input file uses the
-.Xr man 5
+.Xr man 7
language.
No output is produced for that input file.
.El
.Sh SEE ALSO
-.Xr eqn 5 ,
-.Xr man 5 ,
-.Xr mandoc_char 5 ,
-.Xr mandoc_roff 5 ,
-.Xr mdoc 5 ,
-.Xr tbl 5
+.Xr eqn 7 ,
+.Xr man 7 ,
+.Xr mandoc_char 7 ,
+.Xr mandoc_roff 7 ,
+.Xr mdoc 7 ,
+.Xr tbl 7
.Sh HISTORY
The
.Nm