=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.159 retrieving revision 1.168 diff -u -p -r1.159 -r1.168 --- mandoc/mandoc.1 2015/04/03 08:46:17 1.159 +++ mandoc/mandoc.1 2017/01/08 00:11:23 1.168 @@ -1,7 +1,7 @@ -.\" $Id: mandoc.1,v 1.159 2015/04/03 08:46:17 schwarze Exp $ +.\" $Id: mandoc.1,v 1.168 2017/01/08 00:11:23 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons -.\" Copyright (c) 2012, 2014, 2015 Ingo Schwarze +.\" Copyright (c) 2012, 2014-2017 Ingo Schwarze .\" .\" 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. .\" -.Dd $Mdocdate: April 3 2015 $ +.Dd $Mdocdate: January 8 2017 $ .Dt MANDOC 1 .Os .Sh NAME @@ -75,6 +75,10 @@ This overrides any earlier 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 @@ -85,10 +89,6 @@ and for the .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 @@ -284,6 +284,8 @@ See .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 @@ -347,7 +349,7 @@ Equations rendered from 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 , @@ -490,6 +492,45 @@ to force a UTF\-8 locale. 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 @@ -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 -.Ar style.css +.Pa mandoc.css 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 @@ -768,11 +809,13 @@ This may confuse .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 -child macro. +child macro before the first +.Ic \&Nd +macro. .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 t .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 @@ -934,13 +982,6 @@ list block contains text or macros before the first .Ic \&It macro. The offending children are moved before the beginning of the list. -.It Sy ".Vt block has child macro" -.Pq mdoc -The -.Ic \&Vt -macro supports plain text arguments only. -Formatting may be ugly and semantic searching -for the affected content might not work. .It Sy "fill mode already enabled, skipping" .Pq man A @@ -1113,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. +.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 @@ -1566,6 +1614,13 @@ By requesting the inclusion of a sensitive file, a mal 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 @@ -1574,8 +1629,8 @@ macro fails to specify the list type. .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