===================================================================
RCS file: /cvs/mandoc/mandoc.1,v
retrieving revision 1.159
retrieving revision 1.164
diff -u -p -r1.159 -r1.164
--- mandoc/mandoc.1	2015/04/03 08:46:17	1.159
+++ mandoc/mandoc.1	2015/11/05 17:47:51	1.164
@@ -1,4 +1,4 @@
-.\"	$Id: mandoc.1,v 1.159 2015/04/03 08:46:17 schwarze Exp $
+.\"	$Id: mandoc.1,v 1.164 2015/11/05 17:47:51 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2012, 2014, 2015 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.
 .\"
-.Dd $Mdocdate: April 3 2015 $
+.Dd $Mdocdate: November 5 2015 $
 .Dt MANDOC 1
 .Os
 .Sh NAME
@@ -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
@@ -934,13 +975,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
@@ -1566,6 +1600,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