-.\" $Id: mandoc.1,v 1.145 2015/02/04 22:30:10 schwarze Exp $
+.\" $Id: mandoc.1,v 1.152 2015/02/07 15:15:20 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2012, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: February 4 2015 $
+.Dd $Mdocdate: February 7 2015 $
.Dt MANDOC 1
.Os
.Sh NAME
.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.
+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.
.Pq mdoc
The name of a macro that is not callable appears on a macro line.
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
.Sq \e& .
.It Sy "skipping paragraph macro"
clause.
.It Sy "skipping empty macro"
.Pq mdoc
-The indicated macro has no arguments or no body content
-and hence no effect.
+The indicated macro has no arguments and hence no effect.
+.It Sy "empty block"
+.Pq mdoc , man
+A
+.Ic \&Bd ,
+.Ic \&Bk ,
+.Ic \&Bl ,
+.Ic \&D1 ,
+.Ic \&Dl ,
+.Ic \&RS ,
+or
+.Ic \&UR
+block contains nothing in its body and will produce no output.
.It Sy "empty argument, using 0n"
.Pq mdoc
The required width is missing after
.Fl offset
or
.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"
.Pq mdoc
The
macro is called without an argument before
.Ic \&Nm
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"
.Pq mdoc
In a
.Ic \&It
block is empty.
An empty list item is shown.
-.It Sy "missing font type"
+.It Sy "missing font type, using \efR"
.Pq mdoc
A
.Ic \&Bf
macro has no argument.
-It switches to the default font,
-.Cm \efR .
-.It Sy "unknown font type"
+It switches to the default font.
+.It Sy "unknown font type, using \efR"
.Pq mdoc
The
.Ic \&Bf
argument is invalid.
-The default font
-.Cm \efR
-is used instead.
+The default font is used instead.
.It Sy "nothing follows prefix"
.Pq mdoc
A
utility assumes
.Fl std
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 \&UR
+macro is invoked without any argument.
+An empty pair of angle brackets is shown.
.It Sy "missing eqn box, using \(dq\(dq"
.Pq eqn
A diacritic mark or a binary operator is found,
.Fl width
argument.
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"
.Pq mdoc
An
layout modifier has an unknown
.Ar font
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
.Ss "Warnings related to plain text"
.Bl -ohang
A block that doesn't support bad nesting
ends before all of its children are properly closed.
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
At the end of the document, an explicit
.Xr mdoc 7
only the escape sequence is discarded.
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.
-.It Sy "argument count wrong"
-.Pq mdoc , man , roff
-The indicated request or 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 request or macro in question.
-Note that the same message may also occur as a WARNING, see above.
.It Sy "NOT IMPLEMENTED: Bd -file"
.Pq mdoc
For security reasons, the
.Ic \&EN
macro, or a
.Xr roff 7
-.Ic \&br
+.Ic \&br ,
+.Ic \&fi ,
+or
+.Ic \&nf
request or
.Sq \&..
block closing request is invoked with at least one argument.
All arguments are ignored.
.It Sy "skipping excess arguments"
.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 \&PD ,
+.Ic \&RS ,
+.Ic \&UR ,
+.Ic \&ft ,
+or
+.Ic \&sp
+with more than one argument
+.It
.Ic \&An
-macro is invoked with another argument after
+with another argument after
.Fl split
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 \&TH
+with more than five arguments
+.It
.Ic \&Bd ,
.Ic \&Bk ,
or
.Ic \&Bl
-are invoked with invalid arguments, the
-.Ic \&RE
-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.
+with invalid arguments
+.El
The excess arguments are ignored.
.El
.Ss Unsupported features
git.ckatri.com / mandoc.git / blobdiff