Generate README.md from template and MANUAL.txt.

`make README.md` will generate the README.md after changes
to MANUAL.txt have been made.

4 files changed, 229 insertions, 120 deletions

diff --git a/Makefile b/Makefile
index f0e0d1b8a..b48bd9287 100644
--- a/Makefile
+++ b/Makefile
@@ -82,6 +82,10 @@ doc/lua-filters.md: tools/ldoc.ltp data/pandoc.lua tools/update-lua-docs.lua
 	       -o $@ $@.tmp
 	rm $@.tmp
 
+README.md: README.template MANUAL.txt tools/update-readme.lua
+	pandoc --lua-filter tools/update-readme.lua --reference-links \
+	      --reference-location=section $< -o $@
+
 download_stats:
 	curl https://api.github.com/repos/jgm/pandoc/releases | \
 		jq -r '.[] | .assets | .[] | "\(.download_count)\t\(.name)"'
diff --git a/README.md b/README.md
index 5a894ba78..5c5909b2b 100644
--- a/README.md
+++ b/README.md
@@ -1,155 +1,168 @@
+<!-- Do not edit this file.  It is generated automatically from
+README.template and MANUAL.txt via the command:
+pandoc --lua-filter tools/update-readme.lua README.template -o README.md
+-->
 Pandoc
 ======
 
-[![github release](https://img.shields.io/github/release/jgm/pandoc.svg?label=current+release)](https://github.com/jgm/pandoc/releases)
-[![hackage release](https://img.shields.io/hackage/v/pandoc.svg?label=hackage)](http://hackage.haskell.org/package/pandoc)
-[![homebrew](https://img.shields.io/homebrew/v/pandoc.svg)](http://brewformulas.org/Pandoc)
-[![stackage LTS package](http://stackage.org/package/pandoc/badge/lts)](http://stackage.org/lts/package/pandoc)
-[![travis build status](https://img.shields.io/travis/jgm/pandoc/master.svg?label=travis+build)](https://travis-ci.org/jgm/pandoc)
-[![appveyor build status](https://ci.appveyor.com/api/projects/status/nvqs4ct090igjiqc?svg=true)](https://ci.appveyor.com/project/jgm/pandoc)
-[![license](https://img.shields.io/badge/license-GPLv2+-lightgray.svg)](https://www.gnu.org/licenses/gpl.html)
-[![pandoc-discuss on google groups](https://img.shields.io/badge/pandoc-discuss-red.svg?style=social)](https://groups.google.com/forum/#!forum/pandoc-discuss)
-
+[![github release][]][] [![hackage release][]][] [![homebrew][]][]
+[![stackage LTS package][]][] [![travis build status][]][] [![appveyor
+build status][]][] [![license][]][] [![pandoc-discuss on google groups]]
+
+  [github release]: https://img.shields.io/github/release/jgm/pandoc.svg?label=current+release
+  [![github release][]]: https://github.com/jgm/pandoc/releases
+  [hackage release]: https://img.shields.io/hackage/v/pandoc.svg?label=hackage
+  [![hackage release][]]: http://hackage.haskell.org/package/pandoc
+  [homebrew]: https://img.shields.io/homebrew/v/pandoc.svg
+  [![homebrew][]]: http://brewformulas.org/Pandoc
+  [stackage LTS package]: http://stackage.org/package/pandoc/badge/lts
+  [![stackage LTS package][]]: http://stackage.org/lts/package/pandoc
+  [travis build status]: https://img.shields.io/travis/jgm/pandoc/master.svg?label=travis+build
+  [![travis build status][]]: https://travis-ci.org/jgm/pandoc
+  [appveyor build status]: https://ci.appveyor.com/api/projects/status/nvqs4ct090igjiqc?svg=true
+  [![appveyor build status][]]: https://ci.appveyor.com/project/jgm/pandoc
+  [license]: https://img.shields.io/badge/license-GPLv2+-lightgray.svg
+  [![license][]]: https://www.gnu.org/licenses/gpl.html
+  [pandoc-discuss on google groups]: https://img.shields.io/badge/pandoc-discuss-red.svg?style=social
+  [![pandoc-discuss on google groups]]: https://groups.google.com/forum/#!forum/pandoc-discuss
 
 The universal markup converter
 ------------------------------
 
+::: {#description}
 Pandoc is a [Haskell] library for converting from one markup format to
-another, and a command-line tool that uses this library. It can read
-[Markdown], [CommonMark], [PHP Markdown Extra], [GitHub-Flavored
-Markdown], [MultiMarkdown], and (subsets of) [Textile],
+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]; and it 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
+[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's enhanced version of Markdown includes syntax for [footnotes],
-[tables], flexible [ordered lists], [definition lists], [fenced code
-blocks], [superscripts and subscripts], [strikeout], [metadata blocks],
-automatic tables of contents, embedded LaTeX [math], [citations], and
-[Markdown inside HTML block elements](#extension-markdown_in_html_blocks).
-(These enhancements, described further under
-[Pandoc's Markdown], can be disabled using the `markdown_strict` input
-or output format.)
-
-In contrast to most existing tools for converting Markdown to HTML, which
-use regex substitutions, 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, and a set of writers, which convert
-this native representation into a target format. Thus, adding an input
-or output format requires only adding a reader or writer.
+Pandoc's enhanced version of Markdown includes syntax for tables,
+definition lists, metadata blocks, `Div` blocks, footnotes and
+citations, embedded LaTeX (including math), Markdown inside HTML block
+elements, and much more. These enhancements, described further under
+Pandoc's Markdown, can be disabled using the `markdown_strict` format.
+
+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 (like an *abstract syntax tree* or AST), and a set of writers,
+which convert this native representation into a target format. Thus,
+adding an input or output format requires only adding a reader or
+writer. Users can also run custom [pandoc filters] to modify the
+intermediate AST.
 
 Because pandoc's intermediate representation of a document is less
-expressive than many of the formats it converts between, one should
-not expect perfect conversions between every format and every other.
-Pandoc attempts to preserve the structural elements of a document, but
-not formatting details such as margin size.  And some document elements,
-such as complex tables, may not fit into pandoc's simple document
-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/
-[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
-[Creole 1.0]: http://www.wikicreole.org/wiki/Creole1.0
-[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
-[Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html
-[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]: https://www.adobe.com/content/dam/Adobe/en/devnet/indesign/cs55-docs/IDML/idml-specification.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
-
-
-
-[footnotes]: http://pandoc.org/MANUAL.html#footnotes
-[tables]: http://pandoc.org/MANUAL.html#tables
-[ordered lists]: http://pandoc.org/MANUAL.html#ordered-lists
-[definition lists]: http://pandoc.org/MANUAL.html#definition-lists
-[fenced code blocks]: http://pandoc.org/MANUAL.html#fenced-code-blocks
-[superscripts and subscripts]: http://pandoc.org/MANUAL.html#superscripts-and-subscripts
-[strikeout]: http://pandoc.org/MANUAL.html#strikeout
-[metadata blocks]: http://pandoc.org/MANUAL.html#metadata-blocks
-[math]: http://pandoc.org/MANUAL.html#math
-[citations]: http://pandoc.org/MANUAL.html#citations
-[Markdown inside HTML block elements]: http://pandoc.org/MANUAL.html#extension-markdown_in_html_blocks
-[Pandoc's Markdown]: http://pandoc.org/MANUAL.html#pandocs-markdown
+expressive than many of the formats it converts between, one should not
+expect perfect conversions between every format and every other. Pandoc
+attempts to preserve the structural elements of a document, but not
+formatting details such as margin size. And some document elements, such
+as complex tables, may not fit into pandoc's simple document 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.
+
+Using `pandoc`
+--------------
+:::
+
+  [Haskell]: https://www.haskell.org
+  [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/
+  [Textile]: http://redcloth.org/textile
+  [reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
+  [HTML]: http://www.w3.org/html/
+  [LaTeX]: http://latex-project.org
+  [MediaWiki markup]: https://www.mediawiki.org/wiki/Help:Formatting
+  [TWiki markup]: http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules
+  [TikiWiki markup]: https://doc.tiki.org/Wiki-Syntax-Text#The_Markup_Language_Wiki-Syntax
+  [Creole 1.0]: http://www.wikicreole.org/wiki/Creole1.0
+  [Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html
+  [OPML]: http://dev.opml.org/spec2.html
+  [Emacs Org mode]: http://orgmode.org
+  [DocBook]: http://docbook.org
+  [JATS]: https://jats.nlm.nih.gov
+  [Muse]: https://amusewiki.org/library/manual
+  [txt2tags]: http://txt2tags.org
+  [Vimwiki]: https://vimwiki.github.io
+  [EPUB]: http://idpf.org/epub
+  [ODT]: http://en.wikipedia.org/wiki/OpenDocument
+  [Word docx]: https://en.wikipedia.org/wiki/Office_Open_XML
+  [XHTML]: http://www.w3.org/TR/xhtml1/
+  [HTML5]: http://www.w3.org/TR/html5/
+  [`beamer`]: https://ctan.org/pkg/beamer
+  [ConTeXt]: http://www.contextgarden.net/
+  [RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
+  [OpenDocument]: http://opendocument.xml.org
+  [GNU Texinfo]: http://www.gnu.org/software/texinfo/
+  [DokuWiki markup]: https://www.dokuwiki.org/dokuwiki
+  [ZimWiki markup]: http://zim-wiki.org/manual/Help/Wiki_Syntax.html
+  [FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1
+  [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
+  [AsciiDoc]: http://www.methods.co.nz/asciidoc/
+  [InDesign ICML]: https://www.adobe.com/content/dam/Adobe/en/devnet/indesign/cs55-docs/IDML/idml-specification.pdf
+  [TEI Simple]: https://github.com/TEIC/TEI-Simple
+  [PowerPoint]: https://en.wikipedia.org/wiki/Microsoft_PowerPoint
+  [Slidy]: http://www.w3.org/Talks/Tools/Slidy/
+  [Slideous]: http://goessner.net/articles/slideous/
+  [DZSlides]: http://paulrouget.com/dzslides/
+  [reveal.js]: http://lab.hakim.se/reveal-js/
+  [S5]: http://meyerweb.com/eric/tools/s5/
+  [PDF]: https://www.adobe.com/pdf/
+  [pandoc filters]: http://pandoc.org/filters.html
 
 Installing
 ----------
 
-Here's [how to install pandoc](INSTALL.md).
+Here's [how to install pandoc].
+
+  [how to install pandoc]: INSTALL.md
 
 Documentation
 -------------
 
-Pandoc's website contains a full [User's Guide](https://pandoc.org/MANUAL.html).
-It is also available [here](MANUAL.txt) as pandoc-flavored Markdown.
-The website also contains some [examples of the use of
-pandoc](https://pandoc.org/demos.html) and a limited [online
-demo](https://pandoc.org/try).
+Pandoc's website contains a full [User's Guide]. It is also available
+[here] as pandoc-flavored Markdown. The website also contains some
+[examples of the use of pandoc] and a limited [online demo].
+
+  [User's Guide]: https://pandoc.org/MANUAL.html
+  [here]: MANUAL.txt
+  [examples of the use of pandoc]: https://pandoc.org/demos.html
+  [online demo]: https://pandoc.org/try
 
 Contributing
 ------------
 
-Pull requests, bug reports, and feature requests are welcome.  Please make
-sure to read [the contributor guidelines](CONTRIBUTING.md) before opening a
-new issue.
+Pull requests, bug reports, and feature requests are welcome. Please
+make sure to read [the contributor guidelines] before opening a new
+issue.
 
+  [the contributor guidelines]: CONTRIBUTING.md
 
 License
 -------
 
 © 2006-2017 John MacFarlane (jgm@berkeley.edu). Released under the
-[GPL], version 2 or greater.  This software carries no warranty of
-any kind.  (See COPYRIGHT for full copyright and warranty notices.)
+[GPL], version 2 or greater. This software carries no warranty of any
+kind. (See COPYRIGHT for full copyright and warranty notices.)
 
-[GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License"
+  [GPL]: http://www.gnu.org/copyleft/gpl.html
+    "GNU General Public License"
diff --git a/README.template b/README.template
new file mode 100644
index 000000000..839e6dfe0
--- /dev/null
+++ b/README.template
@@ -0,0 +1,54 @@
+<!-- Do not edit this file.  It is generated automatically from
+README.template and MANUAL.txt via the command:
+pandoc --lua-filter tools/update-readme.lua README.template -o README.md
+-->
+
+Pandoc
+======
+
+[![github release](https://img.shields.io/github/release/jgm/pandoc.svg?label=current+release)](https://github.com/jgm/pandoc/releases)
+[![hackage release](https://img.shields.io/hackage/v/pandoc.svg?label=hackage)](http://hackage.haskell.org/package/pandoc)
+[![homebrew](https://img.shields.io/homebrew/v/pandoc.svg)](http://brewformulas.org/Pandoc)
+[![stackage LTS package](http://stackage.org/package/pandoc/badge/lts)](http://stackage.org/lts/package/pandoc)
+[![travis build status](https://img.shields.io/travis/jgm/pandoc/master.svg?label=travis+build)](https://travis-ci.org/jgm/pandoc)
+[![appveyor build status](https://ci.appveyor.com/api/projects/status/nvqs4ct090igjiqc?svg=true)](https://ci.appveyor.com/project/jgm/pandoc)
+[![license](https://img.shields.io/badge/license-GPLv2+-lightgray.svg)](https://www.gnu.org/licenses/gpl.html)
+[![pandoc-discuss on google groups](https://img.shields.io/badge/pandoc-discuss-red.svg?style=social)](https://groups.google.com/forum/#!forum/pandoc-discuss)
+
+
+The universal markup converter
+------------------------------
+
+::: description
+:::
+
+Installing
+----------
+
+Here's [how to install pandoc](INSTALL.md).
+
+Documentation
+-------------
+
+Pandoc's website contains a full [User's Guide](https://pandoc.org/MANUAL.html).
+It is also available [here](MANUAL.txt) as pandoc-flavored Markdown.
+The website also contains some [examples of the use of
+pandoc](https://pandoc.org/demos.html) and a limited [online
+demo](https://pandoc.org/try).
+
+Contributing
+------------
+
+Pull requests, bug reports, and feature requests are welcome.  Please make
+sure to read [the contributor guidelines](CONTRIBUTING.md) before opening a
+new issue.
+
+
+License
+-------
+
+© 2006-2017 John MacFarlane (jgm@berkeley.edu). Released under the
+[GPL], version 2 or greater.  This software carries no warranty of
+any kind.  (See COPYRIGHT for full copyright and warranty notices.)
+
+[GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License"
diff --git a/tools/update-readme.lua b/tools/update-readme.lua
new file mode 100644
index 000000000..916b80881
--- /dev/null
+++ b/tools/update-readme.lua
@@ -0,0 +1,38 @@
+-- update README.md based on MANUAL.txt
+-- assumes that the README.md has a div with id 'description'.
+-- this gets replaced by the contents of the 'description' section
+-- of the manual.
+
+function Div(elem)
+    if elem.classes[1] and elem.classes[1] == 'description' then
+        local f = assert(io.open("MANUAL.txt", "r"))
+        local manual = f:read("*all")
+        f:close()
+        local description = {}
+        local i = 1
+        local include = false
+        local mdoc = pandoc.read(manual, "markdown")
+        local blocks = mdoc.blocks
+        while blocks[i] do
+            if include then
+                table.insert(description, pandoc.walk_block(blocks[i],
+                             -- remove internal links
+                             { Link = function(el)
+                                 if el.target:match("^#") then
+                                     return el.content
+                                 end
+                               end }))
+            end
+            if blocks[i].t == 'Header' then
+                if blocks[i].identifier == 'description' then
+                    include = true
+                elseif include then
+                    include = false
+                end
+            end
+            i = i + 1
+        end
+        return pandoc.Div(description, pandoc.Attr("description",{},{}))
+    end
+end
+