Generate README.md from template and MANUAL.txt.
`make README.md` will generate the README.md after changes to MANUAL.txt have been made.
This commit is contained in:
John MacFarlane
parent
0d968c4bbb
commit
81b0b20827
4 changed files with 225 additions and 116 deletions
4
Makefile
4
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)"'
|
||||
|
|
|
|||
245
README.md
245
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"
|
||||
|
|
|
|||
54
README.template
Normal file
54
README.template
Normal file
|
|
@ -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"
|
||||
38
tools/update-readme.lua
Normal file
38
tools/update-readme.lua
Normal file
|
|
@ -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
|
||||
|
||||
Loading…
Add table
Reference in a new issue