8297 update mdocml to 1.14.1

Reviewed by: Robert Mustacchi <rm@joyent.com>
Approved by: Richard Lowe <richlowe@richlowe.net>

3 files changed, 130 insertions, 40 deletions

diff --git a/usr/src/man/man1/mandoc.1 b/usr/src/man/man1/mandoc.1
index d66d47a491..1cddf8ac75 100644
--- a/usr/src/man/man1/mandoc.1
+++ b/usr/src/man/man1/mandoc.1
@@ -1,7 +1,7 @@
-.\"	$Id: mandoc.1,v 1.164 2015/11/05 17:47:51 schwarze Exp $
+.\"	$Id: mandoc.1,v 1.174 2017/02/10 15:45:28 schwarze Exp $
 .\"
 .\" 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
@@ -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: November 5 2015 $
+.Dd $Mdocdate: February 10 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 5
 .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
@@ -463,7 +463,15 @@ Use
 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.
+.Pp
+The first paragraph shows meta data found in the
+.Xr mdoc 5
+prologue, on the
+.Xr man 5
+.Ic \&TH
+line, or the fallbacks used.
+.Pp
+In the tree dump, each output line shows one syntax tree node.
 Child nodes are indented with respect to their parent node.
 The columns are:
 .Pp
@@ -494,8 +502,27 @@ The input column number (starting at one).
 A closing parenthesis if the node is a closing delimiter.
 .It
 A full stop if the node ends a sentence.
+.It
+BROKEN if the node is a block broken by another block.
+.It
+NOSRC if the node is not in the input file,
+but automatically generated from macros.
+.It
+NOPRT if the node is not supposed to generate output
+for any output format.
 .El
 .El
+.Pp
+The following
+.Fl O
+argument is accepted:
+.Bl -tag -width Ds
+.It Cm noval
+Skip validation and show the unvalidated syntax tree.
+This can help to find out whether a given behaviour is caused by
+the parser or by the validator.
+Meta data is not available in this case.
+.El
 .Sh EXIT STATUS
 The
 .Nm
@@ -758,11 +785,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
@@ -779,6 +808,11 @@ The NAME section contains plain text or macros other than
 .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
@@ -1096,6 +1130,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
@@ -1278,6 +1319,10 @@ it is hard to predict which tab stop position the tab will advance to.
 Whitespace at the end of input lines is almost never semantically
 significant \(em but in the odd case where it might be, it is
 extremely confusing when reviewing and maintaining documents.
+.It Sy "new sentence, new line"
+.Pq mdoc
+A new sentence starts in the middle of a text line.
+Start it on a new input line to help formatters produce correct spacing.
 .It Sy "bad comment style"
 .Pq roff
 Comment lines start with a dot, a backslash, and a double-quote character.
@@ -1564,8 +1609,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
@@ -1751,6 +1796,19 @@ as if they were a text line.
 .Xr mandoc_roff 5 ,
 .Xr mdoc 5 ,
 .Xr tbl 5
+.Sh HISTORY
+The
+.Nm
+utility first appeared in
+.Ox 4.8 .
+The option
+.Fl I
+appeared in
+.Ox 5.2 ,
+and
+.Fl aCcfhKklMSsw
+in
+.Ox 5.7 .
 .Sh AUTHORS
 .An -nosplit
 The
@@ -1759,12 +1817,3 @@ utility was written by
 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 and is maintained by
 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
-.Sh BUGS
-In
-.Fl T Cm html ,
-the maximum size of an element attribute is determined by
-.Dv BUFSIZ ,
-which is usually 1024 bytes.
-Be aware of this when setting long link
-formats such as
-.Fl O Cm style Ns = Ns Ar really/long/link .
diff --git a/usr/src/man/man5/mandoc_char.5 b/usr/src/man/man5/mandoc_char.5
index cf102bb840..16b1f4b94f 100644
--- a/usr/src/man/man5/mandoc_char.5
+++ b/usr/src/man/man5/mandoc_char.5
@@ -1,4 +1,4 @@
-.\"	$Id: mandoc_char.7,v 1.63 2015/09/02 15:38:35 schwarze Exp $
+.\"	$Id: mandoc_char.7,v 1.64 2017/02/05 21:41:21 schwarze Exp $
 .\"
 .\" Copyright (c) 2003 Jason McIntyre <jmc@openbsd.org>
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
@@ -16,7 +16,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: September 2 2015 $
+.Dd $Mdocdate: February 5 2017 $
 .Dt MANDOC_CHAR 5
 .Os
 .Sh NAME
@@ -62,6 +62,30 @@ blue-eyed
 lorry-driver
 .Ed
 .Pp
+If a word on a text input line contains a hyphen, a formatter may decide
+to insert an output line break after the hyphen if that helps filling
+the current output line, but the whole word would overflow the line.
+If it is important that the word is not broken across lines in this
+way, a zero-width space
+.Pq Sq \e&
+can be inserted before or after the hyphen.
+While
+.Xr mandoc 1
+never breaks the output line after hyphens adjacent to a zero-width
+space, after any of the other dash- or hyphen-like characters
+represented by escape sequences, or after hyphens inside words in
+macro arguments, other software may not respect these rules and may
+break the line even in such cases.
+.Pp
+Some
+.Xr mandoc_roff 5
+implementations contains dictionaries allowing to break the line
+at syllable boundaries even inside words that contain no hyphens.
+Such automatic hyphenation is not supported by
+.Xr mandoc 1 ,
+which only breaks the line at whitespace, and inside words only
+after existing hyphens.
+.Pp
 The mathematical minus sign is used for negative numbers or subtraction.
 It should be written as
 .Sq \e(mi :
diff --git a/usr/src/man/man5/mdoc.5 b/usr/src/man/man5/mdoc.5
index 6d81124b02..d0123d86c5 100644
--- a/usr/src/man/man5/mdoc.5
+++ b/usr/src/man/man5/mdoc.5
@@ -1,7 +1,7 @@
-.\"	$Id: mdoc.7,v 1.257 2015/11/05 12:06:45 schwarze Exp $
+.\"	$Id: mdoc.7,v 1.262 2017/02/16 14:38:12 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
-.\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2010, 2011, 2013-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
@@ -19,7 +19,7 @@
 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
 .\" Copyright 2015 Nexenta Systems, Inc.  All rights reserved.
 .\"
-.Dd $Mdocdate: November 5 2015 $
+.Dd $Mdocdate: February 16 2017 $
 .Dt MDOC 5
 .Os
 .Sh NAME
@@ -1099,10 +1099,8 @@ argument.
 A columnated list.
 The
 .Fl width
-argument has no effect; instead, each argument specifies the width
-of one column, using either the scaling width syntax described in
-.Xr mandoc_roff 5
-or the string length of the argument.
+argument has no effect; instead, the string length of each argument
+specifies the width of one column.
 If the first line of the body of a
 .Fl column
 list is not an
@@ -1922,14 +1920,25 @@ The
 list is the most complicated.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
 .D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...
+.D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
 .Pp
 The arguments consist of one or more lines of text and macros
 representing a complete table line.
-Cells within the line are delimited by tabs or by the special
+Cells within the line are delimited by the special
 .Sx \&Ta
-block macro.
+block macro or by literal tab characters.
+.Pp
+Using literal tabs is strongly discouraged because they are very
+hard to use correctly and
+.Nm
+code using them is very hard to read.
+In particular, a blank character is syntactically significant
+before and after the literal tab character.
+If a word precedes or follows the tab without an intervening blank,
+that word is never interpreted as a macro call, but always output
+literally.
+.Pp
 The tab cell delimiter may only be used within the
 .Sx \&It
 line itself; on following lines, only the
@@ -1944,9 +1953,10 @@ Note that quoted strings may span tab-delimited cells on an
 line.
 For example,
 .Pp
-.Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
+.Dl .It \(dqcol1 ,\& <TAB> col2 ,\(dq \&;
 .Pp
-will preserve the semicolon whitespace except for the last.
+will preserve the whitespace before both commas,
+but not the whitespace before the semicolon.
 .Pp
 See also
 .Sx \&Bl .
@@ -2805,14 +2815,13 @@ Link to another manual
 .Pq Qq cross-reference .
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Xr Ar name Op section
+.D1 Pf \. Sx \&Xr Ar name section
 .Pp
 Cross reference the
 .Ar name
 and
 .Ar section
-number of another man page;
-omitting the section number is rarely useful.
+number of another man page.
 .Pp
 Examples:
 .Dl \&.Xr mandoc 1
@@ -3124,7 +3133,7 @@ then the macro accepts an arbitrary number of arguments.
 .It Sx \&Ux  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Va  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Vt  Ta    Yes      Ta    Yes      Ta    >0
-.It Sx \&Xr  Ta    Yes      Ta    Yes      Ta    >0
+.It Sx \&Xr  Ta    Yes      Ta    Yes      Ta    2
 .It Sx \&br  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&sp  Ta    \&No     Ta    \&No     Ta    1
 .El
@@ -3144,6 +3153,8 @@ For many macros, when the leading arguments are opening delimiters,
 these delimiters are put before the macro scope,
 and when the trailing arguments are closing delimiters,
 these delimiters are put after the macro scope.
+Spacing is suppressed after opening delimiters
+and before closing delimiters.
 For example,
 .Pp
 .D1 Pf \. \&Aq "( [ word ] ) ."
@@ -3200,7 +3211,7 @@ renders as:
 .D1 Fl a ( b | c \*(Ba d ) e
 .Pp
 This applies to both opening and closing delimiters,
-and also to the middle delimiter:
+and also to the middle delimiter, which does not suppress spacing:
 .Pp
 .Bl -tag -width Ds -offset indent -compact
 .It \&|
@@ -3308,6 +3319,12 @@ but produces large indentations.
 .Xr mandoc_char 5 ,
 .Xr mandoc_roff 5 ,
 .Xr tbl 5
+.Pp
+The web page
+.Lk http://mdocml.bsd.lv/mdoc/ "extended documentation for the mdoc language"
+provides a few tutorial-style pages for beginners, an extensive style
+guide for advanced authors, and an alphabetic index helping to choose
+the best macros for various kinds of content.
 .Sh HISTORY
 The
 .Nm