MANUAL: consolidate input/output format documentation (#4577)

* MANUAL: consolidate format lists

* MANUAL: make formats a proper list

1 files changed, 146 insertions, 113 deletions

diff --git a/MANUAL.txt b/MANUAL.txt
index caba3e3b1..f00614d2c 100644
--- a/MANUAL.txt
+++ b/MANUAL.txt
@@ -13,33 +13,19 @@ Description
 Pandoc is a [Haskell] library for converting from one markup format to
 another, and a command-line tool that uses this library.
 
-Pandoc can read [Markdown], [CommonMark], [PHP Markdown Extra],
-[GitHub-Flavored Markdown], [MultiMarkdown], and (subsets of) [Textile],
-[reStructuredText], [HTML], [LaTeX], [MediaWiki markup], [TWiki
-markup], [TikiWiki markup], [Creole 1.0], [Haddock markup], [OPML],
-[Emacs Org mode], [DocBook], [JATS], [Muse], [txt2tags], [Vimwiki],
-[EPUB], [ODT], and [Word docx].
-
-Pandoc can write plain text, [Markdown],
-[CommonMark], [PHP Markdown Extra], [GitHub-Flavored Markdown],
-[MultiMarkdown], [reStructuredText], [XHTML], [HTML5], [LaTeX]
-\(including [`beamer`] slide shows\), [ConTeXt], [RTF], [OPML],
-[DocBook], [JATS], [OpenDocument], [ODT], [Word docx], [GNU Texinfo],
-[MediaWiki markup], [DokuWiki markup], [ZimWiki markup], [Haddock
-markup], [EPUB] \(v2 or v3\), [FictionBook2], [Textile], [groff man],
-[groff ms], [Emacs Org mode], [AsciiDoc], [InDesign ICML], [TEI
-Simple], [Muse], [PowerPoint] slide shows and [Slidy], [Slideous],
-[DZSlides], [reveal.js] or [S5] HTML slide shows. It can also produce
-[PDF] output on systems where LaTeX, ConTeXt, `pdfroff`,
-`wkhtmltopdf`, `prince`, or `weasyprint` is installed.
+Pandoc can convert between numerous markup and word processing formats,
+including, but not limited to, various flavors of [Markdown], [HTML],
+[LaTeX] and [Word docx]. For the full lists of input and output formats,
+see the `--from` and `--to` [options below][General options].
+
+Pandoc can also produce [PDF] output, see [creating a PDF] below.
 
 Pandoc's enhanced version of Markdown includes syntax for [tables],
 [definition lists], [metadata blocks], [`Div` blocks][Extension:
 `fenced_divs`], [footnotes] and [citations], embedded
 [LaTeX][Extension: `raw_tex`] (including [math]), [Markdown inside HTML
 block elements][Extension: `markdown_in_html_blocks`], and much more.
-These enhancements, described further under [Pandoc's Markdown],
-can be disabled using the `markdown_strict` format.
+See below under [Pandoc's Markdown].
 
 Pandoc has a modular design: it consists of a set of readers, which parse
 text in a given format and produce a native representation of the document
@@ -58,56 +44,6 @@ model.  While conversions from pandoc's Markdown to all formats aspire
 to be perfect, conversions from formats more expressive than pandoc's
 Markdown can be expected to be lossy.
 
-[Markdown]: http://daringfireball.net/projects/markdown/
-[CommonMark]: http://commonmark.org
-[PHP Markdown Extra]: https://michelf.ca/projects/php-markdown/extra/
-[GitHub-Flavored Markdown]: https://help.github.com/articles/github-flavored-markdown/
-[MultiMarkdown]: http://fletcherpenney.net/multimarkdown/
-[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
-[S5]: http://meyerweb.com/eric/tools/s5/
-[Slidy]: http://www.w3.org/Talks/Tools/Slidy/
-[Slideous]: http://goessner.net/articles/slideous/
-[HTML]: http://www.w3.org/html/
-[HTML5]: http://www.w3.org/TR/html5/
-[polyglot markup]: https://www.w3.org/TR/html-polyglot/
-[XHTML]: http://www.w3.org/TR/xhtml1/
-[LaTeX]: http://latex-project.org
-[`beamer`]: https://ctan.org/pkg/beamer
-[Beamer User's Guide]: http://ctan.math.utah.edu/ctan/tex-archive/macros/latex/contrib/beamer/doc/beameruserguide.pdf
-[ConTeXt]: http://www.contextgarden.net/
-[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
-[DocBook]: http://docbook.org
-[JATS]: https://jats.nlm.nih.gov
-[txt2tags]: http://txt2tags.org
-[EPUB]: http://idpf.org/epub
-[OPML]: http://dev.opml.org/spec2.html
-[OpenDocument]: http://opendocument.xml.org
-[ODT]: http://en.wikipedia.org/wiki/OpenDocument
-[Textile]: http://redcloth.org/textile
-[MediaWiki markup]: https://www.mediawiki.org/wiki/Help:Formatting
-[DokuWiki markup]: https://www.dokuwiki.org/dokuwiki
-[ZimWiki markup]: http://zim-wiki.org/manual/Help/Wiki_Syntax.html
-[TWiki markup]: http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules
-[TikiWiki markup]: https://doc.tiki.org/Wiki-Syntax-Text#The_Markup_Language_Wiki-Syntax
-[Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html
-[Creole 1.0]: http://www.wikicreole.org/wiki/Creole1.0
-[groff man]: http://man7.org/linux/man-pages/man7/groff_man.7.html
-[groff ms]: http://man7.org/linux/man-pages/man7/groff_ms.7.html
-[Haskell]: https://www.haskell.org
-[GNU Texinfo]: http://www.gnu.org/software/texinfo/
-[Emacs Org mode]: http://orgmode.org
-[AsciiDoc]: http://www.methods.co.nz/asciidoc/
-[DZSlides]: http://paulrouget.com/dzslides/
-[Word docx]: https://en.wikipedia.org/wiki/Office_Open_XML
-[PDF]: https://www.adobe.com/pdf/
-[reveal.js]: http://lab.hakim.se/reveal-js/
-[FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1
-[InDesign ICML]: http://wwwimages.adobe.com/www.adobe.com/content/dam/acom/en/devnet/indesign/sdk/cs6/idml/idml-cookbook.pdf
-[TEI Simple]: https://github.com/TEIC/TEI-Simple
-[Muse]: https://amusewiki.org/library/manual
-[PowerPoint]: https://en.wikipedia.org/wiki/Microsoft_PowerPoint
-[Vimwiki]: https://vimwiki.github.io
-
 Using `pandoc`
 --------------
 
@@ -283,20 +219,39 @@ General options
 
 `-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT*
 
-:   Specify input format.  *FORMAT* can be `native` (native Haskell),
-    `json` (JSON version of native AST), `markdown` (pandoc's
-    extended Markdown), `markdown_strict` (original unextended
-    Markdown), `markdown_phpextra` (PHP Markdown Extra),
-    `markdown_mmd` (MultiMarkdown), `gfm` (GitHub-Flavored Markdown),
-    `commonmark` (CommonMark Markdown), `textile` (Textile), `rst`
-    (reStructuredText), `html` (HTML), `docbook` (DocBook), `t2t`
-    (txt2tags), `docx` (docx), `odt` (ODT), `epub` (EPUB), `opml` (OPML),
-    `org` (Emacs Org mode), `mediawiki` (MediaWiki markup), `twiki` (TWiki
-    markup), `tikiwiki` (TikiWiki markup), `creole` (Creole 1.0),
-    `haddock` (Haddock markup), or `latex` (LaTeX).
-    (`markdown_github` provides deprecated and less accurate support
-    for Github-Flavored Markdown; please use `gfm` instead, unless you
-    need to use extensions other than `smart`.)
+:   Specify input format.  *FORMAT* can be:
+
+    - `commonmark` ([CommonMark] Markdown)
+    - `creole` ([Creole 1.0])
+    - `docbook` ([DocBook])
+    - `docx` ([Word docx])
+    - `epub` ([EPUB])
+    - `gfm` ([GitHub-Flavored Markdown]),
+      or `markdown_github`, which provides deprecated and less accurate
+      support for Github-Flavored Markdown; please use `gfm` instead,
+      unless you need to use extensions other than `smart`.
+    - `haddock` ([Haddock markup])
+    - `html` ([HTML])
+    - `jats` ([JATS] XML)
+    - `json` (JSON version of native AST)
+    - `latex` ([LaTeX])
+    - `markdown` ([Pandoc's Markdown])
+    - `markdown_mmd` ([MultiMarkdown])
+    - `markdown_phpextra` ([PHP Markdown Extra])
+    - `markdown_strict` (original unextended [Markdown])
+    - `mediawiki` ([MediaWiki markup])
+    - `muse` ([Muse])
+    - `native` (native Haskell)
+    - `odt` ([ODT])
+    - `opml` ([OPML])
+    - `org` ([Emacs Org mode])
+    - `rst` ([reStructuredText])
+    - `t2t` ([txt2tags])
+    - `textile` ([Textile])
+    - `tikiwiki` ([TikiWiki markup])
+    - `twiki` ([TWiki markup])
+    - `vimwiki` ([Vimwiki])
+
     Extensions can be individually enabled or disabled by
     appending `+EXTENSION` or `-EXTENSION` to the format name.
     See [Extensions] below, for a list of extensions and
@@ -305,34 +260,62 @@ General options
 
 `-t` *FORMAT*, `-w` *FORMAT*, `--to=`*FORMAT*, `--write=`*FORMAT*
 
-:   Specify output format.  *FORMAT* can be `native` (native Haskell),
-    `json` (JSON version of native AST), `plain` (plain text),
-    `markdown` (pandoc's extended Markdown), `markdown_strict`
-    (original unextended Markdown), `markdown_phpextra` (PHP Markdown
-    Extra), `markdown_mmd` (MultiMarkdown), `gfm` (GitHub-Flavored
-    Markdown), `commonmark` (CommonMark Markdown), `rst`
-    (reStructuredText), `html4` (XHTML 1.0 Transitional), `html` or
-    `html5` (HTML5/XHTML [polyglot markup]), `latex` (LaTeX), `beamer`
-    (LaTeX beamer slide show), `context` (ConTeXt), `man` (groff man),
-    `mediawiki` (MediaWiki markup), `dokuwiki` (DokuWiki markup),
-    `zimwiki` (ZimWiki markup), `textile` (Textile), `org` (Emacs Org
-    mode), `texinfo` (GNU Texinfo), `opml` (OPML), `docbook` or
-    `docbook4` (DocBook 4), `docbook5` (DocBook 5), `jats` (JATS XML),
-    `opendocument` (OpenDocument), `odt` (OpenOffice text document),
-    `docx` (Word docx), `haddock` (Haddock markup), `rtf` (rich text
-    format), `epub2` (EPUB v2 book), `epub` or `epub3` (EPUB v3),
-    `fb2` (FictionBook2 e-book), `asciidoc` (AsciiDoc), `icml`
-    (InDesign ICML), `tei` (TEI Simple), `slidy` (Slidy HTML and
-    JavaScript slide show), `slideous` (Slideous HTML and JavaScript
-    slide show), `dzslides` (DZSlides HTML5 + JavaScript slide show),
-    `revealjs` (reveal.js HTML5 + JavaScript slide show), `s5` (S5
-    HTML and JavaScript slide show), `pptx` (PowerPoint slide show) or
-    the path of a custom lua writer (see [Custom writers],
-    below). (`markdown_github` provides deprecated and less accurate
-    support for Github-Flavored Markdown; please use `gfm` instead,
-    unless you use extensions that do not work with `gfm`.) Note that
-    `odt`, `docx`, and `epub` output will not be directed to *stdout*
-    unless forced with `-o -`. Extensions can be individually enabled or
+:   Specify output format.  *FORMAT* can be:
+
+    - `asciidoc` ([AsciiDoc])
+    - `beamer` ([LaTeX beamer][`beamer`] slide show)
+    - `commonmark` ([CommonMark] Markdown)
+    - `context` ([ConTeXt])
+    - `docbook` or `docbook4` ([DocBook] 4)
+    - `docbook5` (DocBook 5)
+    - `docx` ([Word docx])
+    - `dokuwiki` ([DokuWiki markup])
+    - `epub` or `epub3` ([EPUB] v3 book)
+    - `epub2` (EPUB v2)
+    - `fb2` ([FictionBook2] e-book)
+    - `gfm` ([GitHub-Flavored Markdown]),
+      or `markdown_github`, which provides deprecated and less accurate
+      support for Github-Flavored Markdown; please use `gfm` instead,
+      unless you use extensions that do not work with `gfm`.
+    - `haddock` ([Haddock markup])
+    - `html` or `html5` ([HTML], i.e. [HTML5]/XHTML [polyglot markup])
+    - `html4` ([XHTML] 1.0 Transitional)
+    - `icml` ([InDesign ICML])
+    - `jats` ([JATS] XML)
+    - `json` (JSON version of native AST)
+    - `latex` ([LaTeX])
+    - `man` ([groff man])
+    - `markdown` ([Pandoc's Markdown])
+    - `markdown_mmd` ([MultiMarkdown])
+    - `markdown_phpextra` ([PHP Markdown Extra])
+    - `markdown_strict` (original unextended [Markdown])
+    - `mediawiki` ([MediaWiki markup])
+    - `ms` ([groff ms])
+    - `muse` ([Muse]),
+    - `native` (native Haskell),
+    - `odt` ([OpenOffice text document][ODT])
+    - `opml` ([OPML])
+    - `opendocument` ([OpenDocument])
+    - `org` ([Emacs Org mode])
+    - `plain` (plain text),
+    - `pptx` ([PowerPoint] slide show)
+    - `rst` ([reStructuredText])
+    - `rtf` ([Rich Text Format])
+    - `texinfo` ([GNU Texinfo])
+    - `textile` ([Textile])
+    - `slideous` ([Slideous] HTML and JavaScript slide show)
+    - `slidy` ([Slidy] HTML and JavaScript slide show)
+    - `dzslides` ([DZSlides] HTML5 + JavaScript slide show),
+    - `revealjs` ([reveal.js] HTML5 + JavaScript slide show)
+    - `s5` ([S5] HTML and JavaScript slide show)
+    - `tei` ([TEI Simple])
+    - `zimwiki` ([ZimWiki markup])
+    - the path of a custom lua writer, see [Custom writers] below
+
+    Note that `odt`, `docx`, and `epub` output will not be directed
+    to *stdout* unless forced with `-o -`.
+
+    Extensions can be individually enabled or
     disabled by appending `+EXTENSION` or `-EXTENSION` to the format
     name.  See [Extensions] below, for a list of extensions and their
     names.  See `--list-output-formats` and `--list-extensions`, below.
@@ -424,6 +407,56 @@ General options
 
 :   Show usage message.
 
+[Markdown]: http://daringfireball.net/projects/markdown/
+[CommonMark]: http://commonmark.org
+[PHP Markdown Extra]: https://michelf.ca/projects/php-markdown/extra/
+[GitHub-Flavored Markdown]: https://help.github.com/articles/github-flavored-markdown/
+[MultiMarkdown]: http://fletcherpenney.net/multimarkdown/
+[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
+[S5]: http://meyerweb.com/eric/tools/s5/
+[Slidy]: http://www.w3.org/Talks/Tools/Slidy/
+[Slideous]: http://goessner.net/articles/slideous/
+[HTML]: http://www.w3.org/html/
+[HTML5]: http://www.w3.org/TR/html5/
+[polyglot markup]: https://www.w3.org/TR/html-polyglot/
+[XHTML]: http://www.w3.org/TR/xhtml1/
+[LaTeX]: http://latex-project.org
+[`beamer`]: https://ctan.org/pkg/beamer
+[Beamer User's Guide]: http://ctan.math.utah.edu/ctan/tex-archive/macros/latex/contrib/beamer/doc/beameruserguide.pdf
+[ConTeXt]: http://www.contextgarden.net/
+[Rich Text Format]: http://en.wikipedia.org/wiki/Rich_Text_Format
+[DocBook]: http://docbook.org
+[JATS]: https://jats.nlm.nih.gov
+[txt2tags]: http://txt2tags.org
+[EPUB]: http://idpf.org/epub
+[OPML]: http://dev.opml.org/spec2.html
+[OpenDocument]: http://opendocument.xml.org
+[ODT]: http://en.wikipedia.org/wiki/OpenDocument
+[Textile]: http://redcloth.org/textile
+[MediaWiki markup]: https://www.mediawiki.org/wiki/Help:Formatting
+[DokuWiki markup]: https://www.dokuwiki.org/dokuwiki
+[ZimWiki markup]: http://zim-wiki.org/manual/Help/Wiki_Syntax.html
+[TWiki markup]: http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules
+[TikiWiki markup]: https://doc.tiki.org/Wiki-Syntax-Text#The_Markup_Language_Wiki-Syntax
+[Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html
+[Creole 1.0]: http://www.wikicreole.org/wiki/Creole1.0
+[groff man]: http://man7.org/linux/man-pages/man7/groff_man.7.html
+[groff ms]: http://man7.org/linux/man-pages/man7/groff_ms.7.html
+[Haskell]: https://www.haskell.org
+[GNU Texinfo]: http://www.gnu.org/software/texinfo/
+[Emacs Org mode]: http://orgmode.org
+[AsciiDoc]: http://www.methods.co.nz/asciidoc/
+[DZSlides]: http://paulrouget.com/dzslides/
+[Word docx]: https://en.wikipedia.org/wiki/Office_Open_XML
+[PDF]: https://www.adobe.com/pdf/
+[reveal.js]: http://lab.hakim.se/reveal-js/
+[FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1
+[InDesign ICML]: http://wwwimages.adobe.com/www.adobe.com/content/dam/acom/en/devnet/indesign/sdk/cs6/idml/idml-cookbook.pdf
+[TEI Simple]: https://github.com/TEIC/TEI-Simple
+[Muse]: https://amusewiki.org/library/manual
+[PowerPoint]: https://en.wikipedia.org/wiki/Microsoft_PowerPoint
+[Vimwiki]: https://vimwiki.github.io
+
 Reader options
 --------------