-.\" $Id: mandoc.1,v 1.133 2015/01/20 21:16:51 schwarze Exp $
+.\" $Id: mandoc.1,v 1.143 2015/02/04 18:03:47 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: January 20 2015 $
+.Dd $Mdocdate: February 4 2015 $
.Dt MANDOC 1
.Os
.Sh NAME
The special characters documented in
.Xr mandoc_char 7
are rendered best-effort in an ASCII equivalent.
-If no equivalent is found,
-.Sq \&?
-is used instead.
.Pp
Output width is limited to 78 visible columns unless literal input lines
exceed this limit.
.It Cm width Ns = Ns Ar width
The output width is set to
.Ar width ,
-which will normalise to \(>=60.
+which will normalise to \(>=58.
.El
.Ss HTML Output
Output produced by
.Fl W Ns Cm warning
was specified.
.It 4
-At least on unsupported feature was encountered, and
+At least one unsupported feature was encountered, and
.Fl W Ns Cm unsupp ,
.Fl W Ns Cm error
or
.Xr makewhatis 8
and
.Xr apropos 1 .
+.It Sy "missing description line, using \(dq\(dq"
+.Pq mdoc
+The
+.Ic \&Nd
+macro lacks the required argument.
+The title line of the manual will end after the dash.
.It Sy "sections out of conventional order"
.Pq mdoc
A standard section occurs after another section it usually precedes.
on the same input line.
This defeats its purpose; in particular, spacing is not suppressed
before the text or macros following on the next input line.
+.It Sy "empty reference block"
+.Pq mdoc
+An
+.Ic \&Rs
+macro is immediately followed by an
+.Ic \&Re
+macro on the next input line.
+Such an empty block does not produce any output.
.It Sy "missing -std argument, adding it"
.Pq mdoc
An
However, defining strings explicitly before use
keeps the code more readable.
.El
-.Ss "Errors related to equations"
-.Bl -inset -compact
-.It "unexpected equation scope closure"
-.It "equation scope open on exit"
-.It "overlapping equation scopes"
-.It "unexpected end of equation"
+.Ss "Warnings related to tables"
+.Bl -ohang
+.It Sy "tbl line starts with span"
+.Pq tbl
+The first cell in a table layout line is a horizontal span
+.Pq Sq Cm s .
+Data provided for this cell is ignored, and nothing is printed in the cell.
+.It Sy "tbl column starts with span"
+.Pq tbl
+The first line of a table layout specification
+requests a vertical span
+.Pq Sq Cm ^ .
+Data provided for this cell is ignored, and nothing is printed in the cell.
+.It Sy "skipping vertical bar in tbl layout"
+.Pq tbl
+A table layout specification contains more than two consecutive vertical bars.
+A double bar is printed, all additional bars are discarded.
.El
.Ss "Errors related to tables"
-.Bl -inset -compact
-.It "no table layout cells specified"
-.It "no table data cells specified"
-.It "ignore data in cell"
-.It "data block still open"
-.It "ignoring extra data cells"
+.Bl -ohang
+.It Sy "non-alphabetic character in tbl options"
+.Pq tbl
+The table options line contains a character other than a letter,
+blank, or comma where the beginning of an option name is expected.
+The character is ignored.
+.It Sy "skipping unknown tbl option"
+.Pq tbl
+The table options line contains a string of letters that does not
+match any known option name.
+The word is ignored.
+.It Sy "missing tbl option argument"
+.Pq tbl
+A table option that requires an argument is not followed by an
+opening parenthesis, or the opening parenthesis is immediately
+followed by a closing parenthesis.
+The option is ignored.
+.It Sy "wrong tbl option argument size"
+.Pq tbl
+A table option argument contains an invalid number of characters.
+Both the option and the argument are ignored.
+.It Sy "empty tbl layout"
+.Pq tbl
+A table layout specification is completely empty,
+specifying zero lines and zero columns.
+As a fallback, a single left-justified column is used.
+.It Sy "invalid character in tbl layout"
+.Pq tbl
+A table layout specification contains a character that can neither
+be interpreted as a layout key character nor as a layout modifier,
+or a modifier precedes the first key.
+The invalid character is discarded.
+.It Sy "unmatched parenthesis in tbl layout"
+.Pq tbl
+A table layout specification contains an opening parenthesis,
+but no matching closing parenthesis.
+The rest of the input line, starting from the parenthesis, has no effect.
+.It Sy "tbl without any data cells"
+.Pq tbl
+A table does not contain any data cells.
+It will probably produce no output.
+.It Sy "ignoring data in spanned tbl cell"
+.Pq tbl
+A table cell is marked as a horizontal span
+.Pq Sq Cm s
+or vertical span
+.Pq Sq Cm ^
+in the table layout, but it contains data.
+The data is ignored.
+.It Sy "ignoring extra tbl data cells"
+.Pq tbl
+A data line contains more cells than the corresponding layout line.
+The data in the extra cells is ignored.
+.It Sy "data block open at end of tbl"
+.Pq tbl
+A data block is opened with
+.Cm T{ ,
+but never closed with a matching
+.Cm T} .
+The remaining data lines of the table are all put into one cell,
+and any remaining cells stay empty.
.El
.Ss "Errors related to roff, mdoc, and man code"
.Bl -ohang
.Xr 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"
+.Pq man
+The
+.Ic \&RE
+macro is invoked with an argument, but less than the specified number of
+.Ic \&RS
+blocks is open.
+The
+.Ic \&RE
+macro is discarded.
.It Sy "inserting missing end of block"
.Pq mdoc , tbl
Various
.Ic \&Ek ,
.Ic \&El ,
.Ic \&Re ,
+.Ic \&Rs ,
or
.Ic \&Ud
macro, an
block closing request is invoked with at least one argument.
All arguments are ignored.
.It Sy "skipping excess arguments"
-.Pq mdoc , roff
+.Pq mdoc , man , roff
The
.Ic \&Bf
-macro is invoked with more than one argument, or a request of the
+macro is invoked with more than one argument, the
+.Ic \&RE
+macro is invoked with more than one argument
+or with a non-integer argument, or a request of the
.Ic \&de
family is invoked with more than two arguments.
The excess arguments are ignored.
of 2^31 bytes (2 Gigabytes).
Since useful manuals are always small, this is not a problem in practice.
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 roff 7
+implementations but not by
+.Nm
+was found in an input file.
+It is replaced by a question mark.
.It Sy "unsupported roff request"
.Pq roff
An input file contains a
.Nm ,
and it is likely that this will cause information loss
or considerable misformatting.
-.It Sy "bad table syntax"
-.It Sy "bad table option"
-.It Sy "bad table layout"
+.It Sy "eqn delim option in tbl"
+.Pq eqn , tbl
+The options line of a table defines equation delimiters.
+Any equation source code contained in the table will be printed unformatted.
+.It Sy "unsupported table layout modifier"
+.Pq tbl
+A table layout specification contains an
+.Sq Cm m
+modifier.
+The modifier is discarded.
.It Sy "ignoring macro in table"
-.El
-.Sh COMPATIBILITY
-This section summarises
-.Nm
-compatibility with GNU troff.
-Each input and output format is separately noted.
-.Ss ASCII Compatibility
-.Bl -bullet -compact
-.It
-Unrenderable unicode codepoints specified with
-.Sq \e[uNNNN]
-escapes are printed as
-.Sq \&?
-in mandoc.
-In GNU troff, these raise an error.
-.It
-The
-.Sq \&Bd \-literal
-and
-.Sq \&Bd \-unfilled
-macros of
-.Xr mdoc 7
-in
-.Fl T Ns Cm ascii
-are synonyms, as are \-filled and \-ragged.
-.It
-In historic GNU troff, the
-.Sq \&Pa
+.Pq tbl , mdoc , man
+A table contains an invocation of an
.Xr mdoc 7
-macro does not underline when scoped under an
-.Sq \&It
-in the FILES section.
-This behaves correctly in
-.Nm .
-.It
-A list or display following the
-.Sq \&Ss
-.Xr mdoc 7
-macro in
-.Fl T Ns Cm ascii
-does not assert a prior vertical break, just as it doesn't with
-.Sq \&Sh .
-.It
-The
-.Sq \&na
-.Xr man 7
-macro in
-.Fl T Ns Cm ascii
-has no effect.
-.It
-Words aren't hyphenated.
-.El
-.Ss HTML Compatibility
-.Bl -bullet -compact
-.It
-The
-.Sq \efP
-escape will revert the font to the previous
-.Sq \ef
-escape, not to the last rendered decoration, which is now dictated by
-CSS instead of hard-coded.
-It also will not span past the current scope,
-for the same reason.
-Note that in
-.Sx ASCII Output
-mode, this will work fine.
-.It
-The
-.Xr mdoc 7
-.Sq \&Bl \-hang
-and
-.Sq \&Bl \-tag
-list types render similarly (no break following overreached left-hand
-side) due to the expressive constraints of HTML.
-.It
-The
+or
.Xr man 7
-.Sq IP
-and
-.Sq TP
-lists render similarly.
+macro or of an undefined macro.
+The macro is ignored, and its arguments are handled
+as if they were a text line.
.El
.Sh SEE ALSO
+.Xr apropos 1 ,
+.Xr man 1 ,
.Xr eqn 7 ,
.Xr man 7 ,
.Xr mandoc_char 7 ,
The
.Nm
utility was written by
-.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
-.Sh CAVEATS
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
+and is maintained by
+.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
+.Sh BUGS
In
-.Fl T Ns Cm html
-and
-.Fl T Ns Cm xhtml ,
+.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 .
-.Pp
-Nesting elements within next-line element scopes of
-.Fl m Ns Cm an ,
-such as
-.Sq br
-within an empty
-.Sq B ,
-will confuse
-.Fl T Ns Cm html
-and
-.Fl T Ns Cm xhtml
-and cause them to forget the formatting of the prior next-line scope.
-.Pp
-The
-.Sq \(aq
-control character is an alias for the standard macro control character
-and does not emit a line-break as stipulated in GNU troff.
git.ckatri.com / mandoc.git / blobdiff