Tissevert/pandoc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

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

Browse source 
* MANUAL: consolidate format lists

* MANUAL: make formats a proper list
This commit is contained in:
Mauro Bieg 2018-04-22 19:37:36 +02:00 • committed by John MacFarlane
parent c92f7b3fd3
commit 873a4c4bf5
1 changed files with 145 additions and 112 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

257
MANUAL.txt
View file

@ -13,33 +13,19 @@ Description
Pandoc is a [Haskell] library for converting from one markup format to Pandoc is a [Haskell] library for converting from one markup format to
another, and a command-line tool that uses this library. another, and a command-line tool that uses this library.
Pandoc can read [Markdown], [CommonMark], [PHP Markdown Extra], Pandoc can convert between numerous markup and word processing formats,
[GitHub-Flavored Markdown], [MultiMarkdown], and (subsets of) [Textile], including, but not limited to, various flavors of [Markdown], [HTML],
[reStructuredText], [HTML], [LaTeX], [MediaWiki markup], [TWiki [LaTeX] and [Word docx]. For the full lists of input and output formats,
markup], [TikiWiki markup], [Creole 1.0], [Haddock markup], [OPML], see the `--from` and `--to` [options below][General options].
[Emacs Org mode], [DocBook], [JATS], [Muse], [txt2tags], [Vimwiki],
[EPUB], [ODT], and [Word docx].
Pandoc can write plain text, [Markdown], Pandoc can also produce [PDF] output, see [creating a PDF] below.
[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 [tables], Pandoc's enhanced version of Markdown includes syntax for [tables],
[definition lists], [metadata blocks], [`Div` blocks][Extension: [definition lists], [metadata blocks], [`Div` blocks][Extension:
`fenced_divs`], [footnotes] and [citations], embedded `fenced_divs`], [footnotes] and [citations], embedded
[LaTeX][Extension: `raw_tex`] (including [math]), [Markdown inside HTML [LaTeX][Extension: `raw_tex`] (including [math]), [Markdown inside HTML
block elements][Extension: `markdown_in_html_blocks`], and much more. block elements][Extension: `markdown_in_html_blocks`], and much more.
These enhancements, described further under [Pandoc's Markdown], See below 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 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 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 to be perfect, conversions from formats more expressive than pandoc's
Markdown can be expected to be lossy. 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` Using `pandoc`
-------------- --------------
@ -283,20 +219,39 @@ General options
`-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT* `-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT*
: Specify input format. *FORMAT* can be `native` (native Haskell), : Specify input format. *FORMAT* can be:
`json` (JSON version of native AST), `markdown` (pandoc's
extended Markdown), `markdown_strict` (original unextended - `commonmark` ([CommonMark] Markdown)
Markdown), `markdown_phpextra` (PHP Markdown Extra), - `creole` ([Creole 1.0])
`markdown_mmd` (MultiMarkdown), `gfm` (GitHub-Flavored Markdown), - `docbook` ([DocBook])
`commonmark` (CommonMark Markdown), `textile` (Textile), `rst` - `docx` ([Word docx])
(reStructuredText), `html` (HTML), `docbook` (DocBook), `t2t` - `epub` ([EPUB])
(txt2tags), `docx` (docx), `odt` (ODT), `epub` (EPUB), `opml` (OPML), - `gfm` ([GitHub-Flavored Markdown]),
`org` (Emacs Org mode), `mediawiki` (MediaWiki markup), `twiki` (TWiki or `markdown_github`, which provides deprecated and less accurate
markup), `tikiwiki` (TikiWiki markup), `creole` (Creole 1.0), support for Github-Flavored Markdown; please use `gfm` instead,
`haddock` (Haddock markup), or `latex` (LaTeX). unless you need to use extensions other than `smart`.
(`markdown_github` provides deprecated and less accurate support - `haddock` ([Haddock markup])
for Github-Flavored Markdown; please use `gfm` instead, unless you - `html` ([HTML])
need to use extensions other than `smart`.) - `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 Extensions can be individually enabled or disabled by
appending `+EXTENSION` or `-EXTENSION` to the format name. appending `+EXTENSION` or `-EXTENSION` to the format name.
See [Extensions] below, for a list of extensions and See [Extensions] below, for a list of extensions and
@ -305,34 +260,62 @@ General options
`-t` *FORMAT*, `-w` *FORMAT*, `--to=`*FORMAT*, `--write=`*FORMAT* `-t` *FORMAT*, `-w` *FORMAT*, `--to=`*FORMAT*, `--write=`*FORMAT*
: Specify output format. *FORMAT* can be `native` (native Haskell), : Specify output format. *FORMAT* can be:
`json` (JSON version of native AST), `plain` (plain text),
`markdown` (pandoc's extended Markdown), `markdown_strict` - `asciidoc` ([AsciiDoc])
(original unextended Markdown), `markdown_phpextra` (PHP Markdown - `beamer` ([LaTeX beamer][`beamer`] slide show)
Extra), `markdown_mmd` (MultiMarkdown), `gfm` (GitHub-Flavored - `commonmark` ([CommonMark] Markdown)
Markdown), `commonmark` (CommonMark Markdown), `rst` - `context` ([ConTeXt])
(reStructuredText), `html4` (XHTML 1.0 Transitional), `html` or - `docbook` or `docbook4` ([DocBook] 4)
`html5` (HTML5/XHTML [polyglot markup]), `latex` (LaTeX), `beamer` - `docbook5` (DocBook 5)
(LaTeX beamer slide show), `context` (ConTeXt), `man` (groff man), - `docx` ([Word docx])
`mediawiki` (MediaWiki markup), `dokuwiki` (DokuWiki markup), - `dokuwiki` ([DokuWiki markup])
`zimwiki` (ZimWiki markup), `textile` (Textile), `org` (Emacs Org - `epub` or `epub3` ([EPUB] v3 book)
mode), `texinfo` (GNU Texinfo), `opml` (OPML), `docbook` or - `epub2` (EPUB v2)
`docbook4` (DocBook 4), `docbook5` (DocBook 5), `jats` (JATS XML), - `fb2` ([FictionBook2] e-book)
`opendocument` (OpenDocument), `odt` (OpenOffice text document), - `gfm` ([GitHub-Flavored Markdown]),
`docx` (Word docx), `haddock` (Haddock markup), `rtf` (rich text or `markdown_github`, which provides deprecated and less accurate
format), `epub2` (EPUB v2 book), `epub` or `epub3` (EPUB v3), support for Github-Flavored Markdown; please use `gfm` instead,
`fb2` (FictionBook2 e-book), `asciidoc` (AsciiDoc), `icml` unless you use extensions that do not work with `gfm`.
(InDesign ICML), `tei` (TEI Simple), `slidy` (Slidy HTML and - `haddock` ([Haddock markup])
JavaScript slide show), `slideous` (Slideous HTML and JavaScript - `html` or `html5` ([HTML], i.e. [HTML5]/XHTML [polyglot markup])
slide show), `dzslides` (DZSlides HTML5 + JavaScript slide show), - `html4` ([XHTML] 1.0 Transitional)
`revealjs` (reveal.js HTML5 + JavaScript slide show), `s5` (S5 - `icml` ([InDesign ICML])
HTML and JavaScript slide show), `pptx` (PowerPoint slide show) or - `jats` ([JATS] XML)
the path of a custom lua writer (see [Custom writers], - `json` (JSON version of native AST)
below). (`markdown_github` provides deprecated and less accurate - `latex` ([LaTeX])
support for Github-Flavored Markdown; please use `gfm` instead, - `man` ([groff man])
unless you use extensions that do not work with `gfm`.) Note that - `markdown` ([Pandoc's Markdown])
`odt`, `docx`, and `epub` output will not be directed to *stdout* - `markdown_mmd` ([MultiMarkdown])
unless forced with `-o -`. Extensions can be individually enabled or - `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 disabled by appending `+EXTENSION` or `-EXTENSION` to the format
name. See [Extensions] below, for a list of extensions and their name. See [Extensions] below, for a list of extensions and their
names. See `--list-output-formats` and `--list-extensions`, below. names. See `--list-output-formats` and `--list-extensions`, below.
@ -424,6 +407,56 @@ General options
: Show usage message. : 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 Reader options
-------------- --------------