===================================================================
RCS file: /cvs/mandoc/mandoc.1,v
retrieving revision 1.174
retrieving revision 1.175
diff -u -p -r1.174 -r1.175
--- mandoc/mandoc.1	2017/02/10 15:45:28	1.174
+++ mandoc/mandoc.1	2017/03/03 14:23:23	1.175
@@ -1,4 +1,4 @@
-.\"	$Id: mandoc.1,v 1.174 2017/02/10 15:45:28 schwarze Exp $
+.\"	$Id: mandoc.1,v 1.175 2017/03/03 14:23:23 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 3 2017 $
 .Dt MANDOC 1
 .Os
 .Sh NAME
@@ -250,7 +250,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 +274,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 +449,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 .