When a file is given on the command line, actually exists, and its name

[mandoc.git] / mandoc.1

diff --git a/mandoc.1 b/mandoc.1
index 6df15edc2652020311b92e8d2f655ed81800c12a..6ca3ec36d668918cef7060e0d6a08ae004344805 100644 (file)
--- a/mandoc.1
+++ b/mandoc.1
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.1,v 1.110 2014/09/03 05:22:45 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>
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2012, 2014 Ingo Schwarze <schwarze@openbsd.org>


@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: September 3 2014 $
+.Dd $Mdocdate: December 28 2014 $

 .Dt MANDOC 1
 .Os
 .Sh NAME
 .Dt MANDOC 1
 .Os
 .Sh NAME


@@ -27,6 +27,7 @@
 .Sm off
 .Op Fl I Cm os Li = Ar name
 .Sm on
 .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
 .Op Fl m Ns Ar format
 .Op Fl O Ns Ar option
 .Op Fl T Ns Ar output


@@ -48,7 +49,7 @@ or
 text from stdin, implying
 .Fl m Ns Cm andoc ,
 and produces
 text from stdin, implying
 .Fl m Ns Cm andoc ,
 and produces

-.Fl T Ns Cm ascii
+.Fl T Ns Cm locale

 output.
 .Pp
 The options are as follows:
 output.
 .Pp
 The options are as follows:


@@ -84,11 +85,39 @@ Override the default operating system
 for the
 .Xr mdoc 7
 .Sq \&Os
 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
 macro.
 .It Fl h
 Display only the SYNOPSIS lines.
 Implies

-.Fl a .
+.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 .
 .It Fl k
 A synonym for
 .Xr apropos 1 .


@@ -120,7 +149,7 @@ See
 .Sx Output Formats
 for available formats.
 Defaults to
 .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
 .It Fl V
 Print version and exit.
 .It Fl W Ns Ar level


@@ -229,11 +258,10 @@ arguments, which correspond to output modes:
 .Bl -tag -width "-Tlocale"
 .It Fl T Ns Cm ascii
 Produce 7-bit ASCII output.
 .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
 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
 See
 .Sx HTML Output .
 .It Fl T Ns Cm lint


@@ -242,6 +270,7 @@ Implies
 .Fl W Ns Cm warning .
 .It Fl T Ns Cm locale
 Encode output using the current locale.
 .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 Locale Output .
 .It Fl T Ns Cm man


@@ -265,17 +294,16 @@ Encode output in the UTF\-8 multi-byte format.
 See
 .Sx UTF\-8 Output .
 .It Fl T Ns Cm xhtml
 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
 .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
 .Xr ascii 7 .
 .Pp
 Font styles are applied by using back-spaced encoding such that an


@@ -320,7 +348,11 @@ which will normalise to \(>=60.
 .Ss HTML Output
 Output produced by
 .Fl T Ns Cm html
 .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
 .Pp
 The
 .Pa example.style.css


@@ -328,7 +360,8 @@ file documents style-sheet classes available for customising output.
 If a style-sheet is not specified with
 .Fl O Ns Ar style ,
 .Fl T Ns Cm html
 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.
 browser.
 .Pp
 Special characters are rendered in decimal-encoded UTF\-8.


@@ -338,16 +371,8 @@ The following
 arguments are accepted:
 .Bl -tag -width Ds
 .It Cm fragment
 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.
 The
 .Cm style
 argument will be ignored.


@@ -391,6 +416,8 @@ relative URI.
 .Ss Locale Output
 Locale-depending output encoding is triggered with
 .Fl T Ns Cm locale .
 .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
 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


@@ -471,15 +498,6 @@ to force a UTF\-8 locale.
 See
 .Sx Locale Output
 for details and options.
 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
 .Sh ENVIRONMENT
 .Bl -tag -width MANPAGER
 .It Ev MANPAGER


@@ -652,12 +670,6 @@ macro lacks the mandatory section argument.
 The section number in a
 .Ic \&Dt
 line is invalid, but still used.
 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
 .It Sy "missing date, using today's date"
 .Pq mdoc, man
 The document was parsed as


@@ -766,6 +778,28 @@ The same standard section title occurs more than once.
 .Pq mdoc
 A standard section header occurs in a section of the manual
 where it normally isn't useful.
 .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
 .El
 .Ss "Warnings related to macros and nesting"
 .Bl -ohang


@@ -774,6 +808,13 @@ where it normally isn't useful.
 See the
 .Xr mdoc 7
 manual for replacements.
 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
 .It Sy "skipping paragraph macro"
 In
 .Xr mdoc 7


@@ -894,8 +935,11 @@ The previous, interrupted macro is deleted from the parse tree.
 .Ss "Warnings related to missing arguments"
 .Bl -ohang
 .It Sy "skipping empty request"
 .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
 .It Sy "conditional request controls empty scope"
 .Pq roff
 A conditional request is only useful if any of the following


@@ -1015,6 +1059,14 @@ argument is invalid.
 The default font
 .Cm \efR
 is used instead.
 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
 .It Sy "missing -std argument, adding it"
 .Pq mdoc
 An


@@ -1029,6 +1081,11 @@ The
 utility assumes
 .Fl std
 even when it is not specified, but other implementations may not.
 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
 .El
 .Ss "Warnings related to bad macro arguments"
 .Bl -ohang


@@ -1096,6 +1153,21 @@ macro has an invalid argument.
 It is used verbatim, with
 .Qq "AT&T UNIX "
 prefixed to it.
 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
 .It Sy "invalid content in Rs block"
 .Pq mdoc
 An


@@ -1114,11 +1186,16 @@ or
 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"
 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
 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
 .El
 .Ss "Warnings related to plain text"
 .Bl -ohang


@@ -1181,7 +1258,6 @@ keeps the code more readable.
 .It "equation scope open on exit"
 .It "overlapping equation scopes"
 .It "unexpected end of equation"
 .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
 .El
 .Ss "Errors related to tables"
 .Bl -inset -compact


@@ -1193,6 +1269,7 @@ keeps the code more readable.
 .It "ignore data in cell"
 .It "data block still open"
 .It "ignoring extra data cells"
 .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
 .El
 .Ss "Errors related to roff, mdoc, and man code"
 .Bl -ohang


@@ -1235,12 +1312,15 @@ macro.
 It may be mistyped or unsupported.
 The request or macro is discarded including its arguments.
 .It Sy "skipping item outside list"
 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
 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
 It is discarded including its arguments.
 .It Sy "skipping column outside column list"
 .Pq mdoc


@@ -1261,7 +1341,9 @@ block closing macro, a
 .Ic \&RE
 or
 .Ic \&UE
 .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.
 .Xr roff 7
 conditional request is encountered but no matching block is open.
 The offending request or macro is discarded.


@@ -1329,6 +1411,17 @@ 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.
 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
 .It Sy "missing list type, using -item"
 .Pq mdoc
 A


@@ -1358,11 +1451,16 @@ An
 .Ic \&St
 macro has an unknown argument and is discarded.
 .It Sy "skipping request without numeric argument"
 .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
 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
 .It Sy "skipping all arguments"
 .Pq mdoc , man , eqn , roff
 An


@@ -1385,6 +1483,8 @@ or
 .Ic \&PP
 macro, an
 .Xr eqn 7
 .Ic \&PP
 macro, an
 .Xr eqn 7

+.Ic \&EQ
+or

 .Ic \&EN
 macro, or a
 .Xr roff 7
 .Ic \&EN
 macro, or a
 .Xr roff 7


@@ -1410,17 +1510,6 @@ cannot handle input files larger than its arbitrary size limit
 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.
 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 Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
 .Pq roff
 For security reasons,


@@ -1500,7 +1589,7 @@ has no effect.
 .It
 Words aren't hyphenated.
 .El
 .It
 Words aren't hyphenated.
 .El

-.Ss HTML/XHTML Compatibility
+.Ss HTML Compatibility

 .Bl -bullet -compact
 .It
 The
 .Bl -bullet -compact
 .It
 The