diff options
| -rw-r--r-- | Makefile | 4 | ||||
| -rw-r--r-- | README.md | 253 | ||||
| -rw-r--r-- | README.template | 54 | ||||
| -rw-r--r-- | tools/update-readme.lua | 38 |
4 files changed, 229 insertions, 120 deletions
@@ -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)"' @@ -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.) - -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 +====== + +[](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 + |