Indentation must be measured in units of the surrounding text,

[mandoc.git] / mandoc.1

diff --git a/mandoc.1 b/mandoc.1
index 2e86ac14a27705ffb890b0c1837126f7066bb3fd..98457b2fb49503854091a100676a5552bde6575f 100644 (file)
--- a/mandoc.1
+++ b/mandoc.1
@@ -1,7 +1,7 @@
-.\"    $Id: mandoc.1,v 1.160 2015/09/14 15:36:14 schwarze Exp $
+.\"    $Id: mandoc.1,v 1.168 2017/01/08 00:11:23 schwarze Exp $

 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>

-.\" Copyright (c) 2012, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2012, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>

 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above


@@ -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 14 2015 $
+.Dd $Mdocdate: January 8 2017 $

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


@@ -75,6 +75,10 @@ This overrides any earlier
 and
 .Fl l
 options.
 and
 .Fl l
 options.

+.It Fl h
+Display only the SYNOPSIS lines.
+Implies
+.Fl c .

 .It Fl I Cm os Ns = Ns Ar name
 Override the default operating system
 .Ar name
 .It Fl I Cm os Ns = Ns Ar name
 Override the default operating system
 .Ar name


@@ -85,10 +89,6 @@ and for the
 .Xr man 7
 .Sq \&TH
 macro.
 .Xr man 7
 .Sq \&TH
 macro.

-.It Fl h
-Display only the SYNOPSIS lines.
-Implies
-.Fl c .

 .It Fl K Ar encoding
 Specify the input encoding.
 The supported
 .It Fl K Ar encoding
 Specify the input encoding.
 The supported


@@ -284,6 +284,8 @@ See
 .Sx PostScript Output .
 .It Fl T Cm tree
 Produce an indented parse tree.
 .Sx PostScript Output .
 .It Fl T Cm tree
 Produce an indented parse tree.

+See
+.Sx Syntax tree output .

 .It Fl T Cm utf8
 Encode output in the UTF\-8 multi-byte format.
 See
 .It Fl T Cm utf8
 Encode output in the UTF\-8 multi-byte format.
 See


@@ -347,7 +349,7 @@ Equations rendered from
 blocks use MathML.
 .Pp
 The
 blocks use MathML.
 .Pp
 The

-.Pa example.style.css
+.Pa mandoc.css

 file documents style-sheet classes available for customising output.
 If a style-sheet is not specified with
 .Fl O Cm style ,
 file documents style-sheet classes available for customising output.
 If a style-sheet is not specified with
 .Fl O Cm style ,


@@ -490,6 +492,45 @@ to force a UTF\-8 locale.
 See
 .Sx Locale Output
 for details and options.
 See
 .Sx Locale Output
 for details and options.

+.Ss Syntax tree output
+Use
+.Fl T Cm tree
+to show a human readable representation of the syntax tree.
+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.
+Each output line shows one syntax tree node.
+Child nodes are indented with respect to their parent node.
+The columns are:
+.Pp
+.Bl -enum -compact
+.It
+For macro nodes, the macro name; for text and
+.Xr tbl 7
+nodes, the content.
+There is a special format for
+.Xr eqn 7
+nodes.
+.It
+Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
+.It
+Flags:
+.Bl -dash -compact
+.It
+An opening parenthesis if the node is an opening delimiter.
+.It
+An asterisk if the node starts a new input line.
+.It
+The input line number (starting at one).
+.It
+A colon.
+.It
+The input column number (starting at one).
+.It
+A closing parenthesis if the node is a closing delimiter.
+.It
+A full stop if the node ends a sentence.
+.El
+.El

 .Sh ENVIRONMENT
 .Bl -tag -width MANPAGER
 .It Ev MANPAGER
 .Sh ENVIRONMENT
 .Bl -tag -width MANPAGER
 .It Ev MANPAGER


@@ -560,10 +601,10 @@ To page manuals to the terminal:
 .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
 .Pp
 To produce HTML manuals with
 .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
 .Pp
 To produce HTML manuals with

-.Ar style.css
+.Pa mandoc.css

 as the style-sheet:
 .Pp
 as the style-sheet:
 .Pp

-.Dl $ mandoc \-T html -O style=style.css mdoc.7 \*(Gt mdoc.7.html
+.Dl $ mandoc \-T html -O style=mandoc.css mdoc.7 \*(Gt mdoc.7.html

 .Pp
 To check over a large set of manuals:
 .Pp
 .Pp
 To check over a large set of manuals:
 .Pp


@@ -768,11 +809,13 @@ This may confuse
 .Xr makewhatis 8
 and
 .Xr apropos 1 .
 .Xr makewhatis 8
 and
 .Xr apropos 1 .

-.It Sy "NAME section without name"
+.It Sy "NAME section without Nm before Nd"

 .Pq mdoc
 The NAME section does not contain any
 .Ic \&Nm
 .Pq mdoc
 The NAME section does not contain any
 .Ic \&Nm

-child macro.
+child macro before the first
+.Ic \&Nd
+macro.

 .It Sy "NAME section without description"
 .Pq mdoc
 The NAME section lacks the mandatory
 .It Sy "NAME section without description"
 .Pq mdoc
 The NAME section lacks the mandatory


@@ -789,6 +832,11 @@ The NAME section contains plain text or macros other than
 .Ic \&Nm
 and
 .Ic \&Nd .
 .Ic \&Nm
 and
 .Ic \&Nd .

+.It Sy "missing comma before name"
+.Pq mdoc
+The NAME section contains an
+.Ic \&Nm
+macro that is neither the first one nor preceded by a comma.

 .It Sy "missing description line, using \(dq\(dq"
 .Pq mdoc
 The
 .It Sy "missing description line, using \(dq\(dq"
 .Pq mdoc
 The


@@ -1106,6 +1154,13 @@ macro is immediately followed by an
 .Ic \&Re
 macro on the next input line.
 Such an empty block does not produce any output.
 .Ic \&Re
 macro on the next input line.
 Such an empty block does not produce any output.

+.It Sy "missing section argument"
+.Pq mdoc
+An
+.Ic \&Xr
+macro lacks its second, section number argument.
+The first argument, i.e. the name, is printed, but without subsequent
+parentheses.

 .It Sy "missing -std argument, adding it"
 .Pq mdoc
 An
 .It Sy "missing -std argument, adding it"
 .Pq mdoc
 An


@@ -1559,6 +1614,13 @@ 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.
 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 "skipping display without arguments"
+.Pq mdoc
+A
+.Ic \&Bd
+block macro does not have any arguments.
+The block is discarded, and the block content is displayed in
+whatever mode was active before the block.

 .It Sy "missing list type, using -item"
 .Pq mdoc
 A
 .It Sy "missing list type, using -item"
 .Pq mdoc
 A


@@ -1567,8 +1629,8 @@ macro fails to specify the list type.
 .It Sy "missing manual name, using \(dq\(dq"
 .Pq mdoc
 The first call to
 .It Sy "missing manual name, using \(dq\(dq"
 .Pq mdoc
 The first call to

-.Ic \&Nm
-lacks the required argument.
+.Ic \&Nm ,
+or any call in the NAME section, lacks the required argument.

 .It Sy "uname(3) system call failed, using UNKNOWN"
 .Pq mdoc
 The
 .It Sy "uname(3) system call failed, using UNKNOWN"
 .Pq mdoc
 The