===================================================================
RCS file: /cvs/mandoc/mandoc.1,v
retrieving revision 1.174
retrieving revision 1.176
diff -u -p -r1.174 -r1.176
--- mandoc/mandoc.1	2017/02/10 15:45:28	1.174
+++ mandoc/mandoc.1	2017/03/04 17:17:34	1.176
@@ -1,4 +1,4 @@
-.\"	$Id: mandoc.1,v 1.174 2017/02/10 15:45:28 schwarze Exp $
+.\"	$Id: mandoc.1,v 1.176 2017/03/04 17:17:34 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: February 10 2017 $
+.Dd $Mdocdate: March 4 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 .