-.\" $Id: mandoc.1,v 1.108 2014/08/22 04:52:55 schwarze Exp $
+.\" $Id: mandoc.1,v 1.130 2014/12/28 14:42:27 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2012, 2014 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: August 22 2014 $
+.Dd $Mdocdate: December 28 2014 $
.Dt MANDOC 1
.Os
.Sh NAME
.Nd format and display UNIX manuals
.Sh SYNOPSIS
.Nm mandoc
-.Op Fl acV
+.Op Fl acfhklV
.Sm off
.Op Fl I Cm os Li = Ar name
.Sm on
+.Op Fl K Ns Ar encoding
.Op Fl m Ns Ar format
.Op Fl O Ns Ar option
.Op Fl T Ns Ar output
text from stdin, implying
.Fl m Ns Cm andoc ,
and produces
-.Fl T Ns Cm ascii
+.Fl T Ns Cm locale
output.
.Pp
-The arguments are as follows:
+The options are as follows:
.Bl -tag -width Ds
.It Fl a
If the standard output is a terminal device and
This is the default.
It can be specified to override
.Fl a .
+.It Fl f
+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
for the
.Xr mdoc 7
.Sq \&Os
+and for the
+.Xr man 7
+.Sq \&TH
macro.
+.It Fl h
+Display only the SYNOPSIS lines.
+Implies
+.Fl c .
+.It Fl K Ns Ar encoding
+Specify the input encoding.
+The supported
+.Ar encoding
+arguments are
+.Cm us-ascii ,
+.Cm iso-8859-1 ,
+and
+.Cm utf-8 .
+If not specified, autodetection uses the first match:
+.Bl -tag -width iso-8859-1
+.It Cm utf-8
+if the first three bytes of the input file
+are the UTF-8 byte order mark (BOM, 0xefbbbf)
+.It Ar encoding
+if the first or second line of the input file matches the
+.Sy emacs
+mode line format
+.Pp
+.D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*-
+.It Cm utf-8
+if the first non-ASCII byte in the file introduces a valid UTF-8 sequence
+.It Cm iso-8859-1
+otherwise
+.El
+.It Fl k
+A synonym for
+.Xr apropos 1 .
+This overrides any earlier
+.Fl f
+and
+.Fl l
+options.
+.It Fl l
+A synonym for
+.Fl a .
+Also reverts any earlier
+.Fl f
+and
+.Fl k
+options.
.It Fl m Ns Ar format
Input format.
See
.Sx Output Formats
for available formats.
Defaults to
-.Fl T Ns Cm ascii .
+.Fl T Ns Cm locale .
.It Fl V
Print version and exit.
.It Fl W Ns Ar level
.Nm
will halt with the first failed parse.
.El
+.Pp
+In
+.Fl f
+and
+.Fl k
+mode,
+.Nm
+also supports the options
+.Fl CMmOSsw
+described in the
+.Xr apropos 1
+manual.
.Ss Input Formats
The
.Nm
.Bl -tag -width "-Tlocale"
.It Fl T Ns Cm ascii
Produce 7-bit ASCII output.
-This is the default.
See
.Sx ASCII Output .
.It Fl T Ns Cm html
-Produce strict CSS1/HTML-4.01 output.
+Produce HTML5, CSS1, and MathML output.
See
.Sx HTML Output .
.It Fl T Ns Cm lint
.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
See
.Sx UTF\-8 Output .
.It Fl T Ns Cm xhtml
-Produce strict CSS1/XHTML-1.0 output.
-See
-.Sx XHTML Output .
+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
Output produced by
-.Fl T Ns Cm ascii ,
-which is the default, is rendered in standard 7-bit ASCII documented in
+.Fl T Ns Cm ascii
+is rendered in standard 7-bit ASCII documented in
.Xr ascii 7 .
.Pp
Font styles are applied by using back-spaced encoding such that an
.Ss HTML Output
Output produced by
.Fl T Ns Cm html
-conforms to HTML-4.01 strict.
+conforms to HTML5 using optional self-closing tags.
+Default styles use only CSS1.
+Equations rendered from
+.Xr eqn 7
+blocks use MathML.
.Pp
The
.Pa example.style.css
If a style-sheet is not specified with
.Fl O Ns Ar style ,
.Fl T Ns Cm html
-defaults to simple output readable in any graphical or text-based web
+defaults to simple output (via an embedded style-sheet)
+readable in any graphical or text-based web
browser.
.Pp
Special characters are rendered in decimal-encoded UTF\-8.
arguments are accepted:
.Bl -tag -width Ds
.It Cm fragment
-Omit the
-.Aq !DOCTYPE
-declaration and the
-.Aq html ,
-.Aq head ,
-and
-.Aq body
-elements and only emit the subtree below the
-.Aq body
-element.
+Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body>
+elements and only emit the subtree below the <body> element.
The
.Cm style
argument will be ignored.
.Ss Locale Output
Locale-depending output encoding is triggered with
.Fl T Ns Cm locale .
+This is the default.
+.Pp
This option is not available on all systems: systems without locale
support, or those whose internal representation is not natively UCS-4,
will fall back to
See
.Sx Locale Output
for details and options.
-.Ss XHTML Output
-Output produced by
-.Fl T Ns Cm xhtml
-conforms to XHTML-1.0 strict.
-.Pp
-See
-.Sx HTML Output
-for details; beyond generating XHTML tags instead of HTML tags, these
-output modes are identical.
.Sh ENVIRONMENT
.Bl -tag -width MANPAGER
.It Ev MANPAGER
The section number in a
.Ic \&Dt
line is invalid, but still used.
-.It Sy "unknown manual volume or arch"
-.Pq mdoc
-The volume name in a
-.Ic \&Dt
-line is invalid, but still used.
-The manual is assumed to be architecture-independent.
.It Sy "missing date, using today's date"
.Pq mdoc, man
The document was parsed as
.Pq mdoc
A standard section header occurs in a section of the manual
where it normally isn't useful.
+.It Sy "unusual Xr order"
+.Pq mdoc
+In the SEE ALSO section, an
+.Ic \&Xr
+macro with a lower section number follows one with a higher number,
+or two
+.Ic \&Xr
+macros refering to the same section are out of alphabetical order.
+.It Sy "unusual Xr punctuation"
+.Pq mdoc
+In the SEE ALSO section, punctuation between two
+.Ic \&Xr
+macros differs from a single comma, or there is trailing punctuation
+after the last
+.Ic \&Xr
+macro.
+.It Sy "AUTHORS section without An macro"
+.Pq mdoc
+An AUTHORS sections contains no
+.Ic \&An
+macros, or only empty ones.
+Probably, there are author names lacking markup.
.El
.Ss "Warnings related to macros and nesting"
.Bl -ohang
See the
.Xr mdoc 7
manual for replacements.
+.It Sy "macro neither callable nor escaped"
+.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;
+otherwise, escape it by prepending
+.Sq \e& .
.It Sy "skipping paragraph macro"
In
.Xr mdoc 7
.Ss "Warnings related to missing arguments"
.Bl -ohang
.It Sy "skipping empty request"
-.Pq roff
-The macro name is missing from a macro definition request.
+.Pq roff , eqn
+The macro name is missing from a macro definition request,
+or an
+.Xr eqn 7
+control statement or operation keyword lacks its required argument.
.It Sy "conditional request controls empty scope"
.Pq roff
A conditional request is only useful if any of the following
The default font
.Cm \efR
is used instead.
+.It Sy "nothing follows prefix"
+.Pq mdoc
+A
+.Ic \&Pf
+macro has no argument, or only one argument and no macro follows
+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 "missing -std argument, adding it"
.Pq mdoc
An
utility assumes
.Fl std
even when it is not specified, but other implementations may not.
+.It Sy "missing eqn box, using \(dq\(dq"
+.Pq eqn
+A diacritic mark or a binary operator is found,
+but there is nothing to the left of it.
+An empty box is inserted.
.El
.Ss "Warnings related to bad macro arguments"
.Bl -ohang
It is used verbatim, with
.Qq "AT&T UNIX "
prefixed to it.
+.It Sy "comma in function argument"
+.Pq mdoc
+An argument of an
+.Ic \&Fa
+or
+.Ic \&Fn
+macro contains a comma; it should probably be split into two arguments.
+.It Sy "parenthesis in function name"
+.Pq mdoc
+The first argument of an
+.Ic \&Fc
+or
+.Ic \&Fn
+macro contains an opening or closing parenthesis; that's probably wrong,
+parentheses are added automatically.
.It Sy "invalid content in Rs block"
.Pq mdoc
An
The invalid argument is moved out of the macro, which leaves the macro
empty, causing it to toggle the spacing mode.
.It Sy "unknown font, skipping request"
-.Pq man
+.Pq man , tbl
A
.Xr roff 7
.Ic \&ft
-request has an invalid argument.
+request or a
+.Xr tbl 7
+.Ic \&f
+layout modifier has an unknown
+.Ar font
+argument.
.El
.Ss "Warnings related to plain text"
.Bl -ohang
.It "equation scope open on exit"
.It "overlapping equation scopes"
.It "unexpected end of equation"
-.It "equation syntax error"
.El
.Ss "Errors related to tables"
.Bl -inset -compact
.It "ignore data in cell"
.It "data block still open"
.It "ignoring extra data cells"
+.It "ignoring macro in table"
.El
.Ss "Errors related to roff, mdoc, and man code"
.Bl -ohang
It may be mistyped or unsupported.
The request or macro is discarded including its arguments.
.It Sy "skipping item outside list"
-.Pq mdoc
+.Pq mdoc , eqn
An
.Ic \&It
macro occurs outside any
.Ic \&Bl
-list.
+list, or an
+.Xr eqn 7
+.Ic above
+delimiter occurs outside any pile.
It is discarded including its arguments.
.It Sy "skipping column outside column list"
.Pq mdoc
.Ic \&RE
or
.Ic \&UE
-macro, or the end of an equation, table, or
+macro, an
+.Xr eqn 7
+right delimiter or closing brace, or the end of an equation, table, or
.Xr roff 7
conditional request is encountered but no matching block is open.
The offending request or macro is discarded.
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 \&Bd
+macro does not support the
+.Fl file
+argument.
+By requesting the inclusion of a sensitive file, a malicious document
+might otherwise trick a privileged user into inadvertently displaying
+the file on the screen, revealing the file content to bystanders.
+The argument is ignored including the file name following it.
.It Sy "missing list type, using -item"
.Pq mdoc
A
.Ic \&St
macro has an unknown argument and is discarded.
.It Sy "skipping request without numeric argument"
-.Pq roff
+.Pq roff , eqn
An
.Ic \&it
-request has a non-numeric or negative argument or no argument at all.
-The invalid request is ignored.
+request or an
+.Xr eqn 7
+.Ic \&size
+or
+.Ic \&gsize
+statement has a non-numeric or negative argument or no argument at all.
+The invalid request or statement is ignored.
.It Sy "skipping all arguments"
.Pq mdoc , man , eqn , roff
An
.Ic \&PP
macro, an
.Xr eqn 7
+.Ic \&EQ
+or
.Ic \&EN
macro, or a
.Xr roff 7
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 "NOT IMPLEMENTED: Bd -file"
-.Pq mdoc
-For security reasons, the
-.Ic \&Bd
-macro does not support the
-.Fl file
-argument.
-By requesting the inclusion of a sensitive file, a malicious document
-might otherwise trick a privileged user into inadvertently displaying
-the file on the screen, revealing the file content to bystanders.
-The parser exits immediately.
.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
.Pq roff
For security reasons,
.It
Words aren't hyphenated.
.El
-.Ss HTML/XHTML Compatibility
+.Ss HTML Compatibility
.Bl -bullet -compact
.It
The
git.ckatri.com / mandoc.git / blobdiff