===================================================================
RCS file: /cvs/mandoc/mandoc.1,v
retrieving revision 1.173
retrieving revision 1.177
diff -u -p -r1.173 -r1.177
--- mandoc/mandoc.1	2017/01/31 19:44:04	1.173
+++ mandoc/mandoc.1	2017/03/06 17:26:04	1.177
@@ -1,4 +1,4 @@
-.\"	$Id: mandoc.1,v 1.173 2017/01/31 19:44:04 schwarze Exp $
+.\"	$Id: mandoc.1,v 1.177 2017/03/06 17:26:04 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2012, 2014-2017 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: January 31 2017 $
+.Dd $Mdocdate: March 6 2017 $
 .Dt MANDOC 1
 .Os
 .Sh NAME
@@ -98,21 +98,29 @@ arguments are
 .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
+If not specified, autodetection uses the first match in the following
+list:
+.Bl -enum
+.It
+If the first three bytes of the input file are the UTF-8 byte order
+mark (BOM, 0xefbbbf), input is interpreted as
+.Cm utf-8 .
+.It
+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
+.Pp
+then input is interpreted according to
+.Ar encoding .
+.It
+If the first non-ASCII byte in the file introduces a valid UTF-8
+sequence, input is interpreted as
+.Cm utf-8 .
+.It
+Otherwise, input is interpreted as
+.Cm iso-8859-1 .
 .El
 .It Fl k
 A synonym for
@@ -250,7 +258,7 @@ The
 utility accepts the following
 .Fl T
 arguments, which correspond to output modes:
-.Bl -tag -width "-T locale"
+.Bl -tag -width "-T markdown"
 .It Fl T Cm ascii
 Produce 7-bit ASCII output.
 See
@@ -274,6 +282,12 @@ Produce
 format output.
 See
 .Sx Man Output .
+.It Fl T Cm markdown
+Produce output in
+.Sy markdown
+format.
+See
+.Sx Markdown Output .
 .It Fl T Cm pdf
 Produce PDF output.
 See
@@ -443,6 +457,30 @@ The parser is also run, and as usual, the
 level controls which
 .Sx DIAGNOSTICS
 are displayed before copying the input to the output.
+.Ss Markdown Output
+Translate
+.Xr mdoc 7
+input to the
+.Sy markdown
+format conforming to
+.Lk http://daringfireball.net/projects/markdown/syntax.text\
+ "John Gruber's 2004 specification" .
+.Pp
+Markdown is a very weak markup language, so all semantic markup is
+lost, and even part of the presentational markup may be lost.
+Do not use this as an intermediate step in converting to HTML;
+instead, use
+.Fl T Cm html
+directly.
+.Pp
+The
+.Xr man 7 ,
+.Xr tbl 7 ,
+and
+.Xr eqn 7
+input languages are not supported by
+.Fl T Cm markdown
+output mode.
 .Ss PDF Output
 PDF-1.1 output may be generated by
 .Fl T Cm pdf .
@@ -538,6 +576,8 @@ A closing parenthesis if the node is a closing delimit
 .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
@@ -545,6 +585,17 @@ 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 ENVIRONMENT
 .Bl -tag -width MANPAGER
 .It Ev MANPAGER
@@ -857,6 +908,14 @@ The
 .Ic \&Nd
 macro lacks the required argument.
 The title line of the manual will end after the dash.
+.It Sy "description line outside NAME section"
+.Pq mdoc
+An
+.Ic \&Nd
+macro appears outside the NAME section.
+The arguments are printed anyway and the following text is used for
+.Xr apropos 1 ,
+but none of that behaviour is portable.
 .It Sy "sections out of conventional order"
 .Pq mdoc
 A standard section occurs after another section it usually precedes.