From 81b0b208278ea8982d6581bda0dc922c466df2a9 Mon Sep 17 00:00:00 2001
From: John MacFarlane <jgm@berkeley.edu>
Date: Fri, 29 Dec 2017 16:41:51 -0800
Subject: [PATCH] Generate README.md from template and MANUAL.txt.
`make README.md` will generate the README.md after changes
to MANUAL.txt have been made.
---
Makefile | 4 +
README.md | 245 +++++++++++++++++++++-------------------
README.template | 54 +++++++++
tools/update-readme.lua | 38 +++++++
4 files changed, 225 insertions(+), 116 deletions(-)
create mode 100644 README.template
create mode 100644 tools/update-readme.lua
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
======
-[](https://github.com/jgm/pandoc/releases)
-[](http://hackage.haskell.org/package/pandoc)
-[](http://brewformulas.org/Pandoc)
-[](http://stackage.org/lts/package/pandoc)
-[](https://travis-ci.org/jgm/pandoc)
-[](https://ci.appveyor.com/project/jgm/pandoc)
-[](https://www.gnu.org/licenses/gpl.html)
-[](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.)
+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.
-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 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.
+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
+Using `pandoc`
+--------------
+:::
-
-
-[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
+ [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
+======
+
+[](https://github.com/jgm/pandoc/releases)
+[](http://hackage.haskell.org/package/pandoc)
+[](http://brewformulas.org/Pandoc)
+[](http://stackage.org/lts/package/pandoc)
+[](https://travis-ci.org/jgm/pandoc)
+[](https://ci.appveyor.com/project/jgm/pandoc)
+[](https://www.gnu.org/licenses/gpl.html)
+[](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
+