@@ -4,13 +4,18 @@
5Pandoc is a [Haskell] library for converting from one markup format to
5Pandoc is a [Haskell] library for converting from one markup format to
6another, and a command-line tool that uses this library. It can read
6another, and a command-line tool that uses this library. It can read
7−[markdown] and (subsets of) [reStructuredText], [HTML], and [LaTeX], and
7+[markdown] and (subsets of) [reStructuredText], [HTML], and [LaTeX]; and
8it can write [markdown], [reStructuredText], [HTML], [LaTeX], [ConTeXt],
8it can write [markdown], [reStructuredText], [HTML], [LaTeX], [ConTeXt],
9−[RTF], [DocBook XML], [OpenDocument XML], [GNU Texinfo], [MediaWiki markup],
9+[RTF], [DocBook XML], [OpenDocument XML], [ODT], [GNU Texinfo],
10−[groff man] pages, and [S5] HTML slide shows. Pandoc's version of
10+[MediaWiki markup], [groff man] pages, and [S5] HTML slide shows.
11−markdown contains some enhancements, like footnotes and embedded LaTeX.
11+Pandoc's enhanced version of markdown includes syntax for footnotes,
12−
12+tables, flexible ordered lists, definition lists, delimited code blocks,
13+superscript, subscript, strikeout, title blocks, automatic tables of
14+contents, embedded LaTeX math, and markdown inside HTML block elements.
15+(These enhancements can be disabled if a drop-in replacement for
16+`Markdown.pl` is desired.)
13−In contrast to existing tools for converting markdown to HTML, which
18+In contrast to most existing tools for converting markdown to HTML, which
14use regex substitutions, Pandoc has a modular design: it consists of a
19use regex substitutions, Pandoc has a modular design: it consists of a
15set of readers, which parse text in a given format and produce a native
20set of readers, which parse text in a given format and produce a native
16representation of the document, and a set of writers, which convert
21representation of the document, and a set of writers, which convert
@@ -26,6 +31,7 @@ or output format requires only adding a reader or writer.
26[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
31[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
27[DocBook XML]: http://www.docbook.org/
32[DocBook XML]: http://www.docbook.org/
28[OpenDocument XML]: http://opendocument.xml.org/
33[OpenDocument XML]: http://opendocument.xml.org/
34+[ODT]: http://en.wikipedia.org/wiki/OpenDocument
29[MediaWiki markup]: http://www.mediawiki.org/wiki/Help:Formatting
35[MediaWiki markup]: http://www.mediawiki.org/wiki/Help:Formatting
30[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html
36[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html
31[Haskell]: http://www.haskell.org/
37[Haskell]: http://www.haskell.org/
@@ -43,12 +49,16 @@ Using Pandoc
43============
49============
45If you run `pandoc` without arguments, it will accept input from
51If you run `pandoc` without arguments, it will accept input from
46−STDIN. If you run it with file names as arguments, it will take input
52+stdin. If you run it with file names as arguments, it will take input
47−from those files. By default, `pandoc` writes its output to STDOUT.
53+from those files. By default, `pandoc` writes its output to stdout.[^1]
48If you want to write to a file, use the `-o` option:
54If you want to write to a file, use the `-o` option:
50 pandoc -o hello.html hello.txt
56 pandoc -o hello.html hello.txt
58+[^1]: The exception is for non-text output formats, such as `odt`.
59+ For output in `odt` format, an output file must be specified
52Note that you can specify multiple input files on the command line.
62Note that you can specify multiple input files on the command line.
53`pandoc` will concatenate them all (with blank lines between them)
63`pandoc` will concatenate them all (with blank lines between them)
54before parsing:
64before parsing:
@@ -73,17 +83,19 @@ To convert `hello.html` from html to markdown:
74Supported output formats include `markdown`, `latex`, `context`
84Supported output formats include `markdown`, `latex`, `context`
75(ConTeXt), `html`, `rtf` (rich text format), `rst` (reStructuredText),
85(ConTeXt), `html`, `rtf` (rich text format), `rst` (reStructuredText),
76−`docbook` (DocBook XML), `opendocument` (OpenDocument XML), `texinfo`,
86+`docbook` (DocBook XML), `opendocument` (OpenDocument XML), `odt`
87+(OpenOffice text document), `texinfo`, (GNU Texinfo), `mediawiki`
77−`mediawiki` (MediaWiki markup), `man` (groff man), and `s5` (which
88+(MediaWiki markup), `man` (groff man), and `s5` (which produces an
78−produces an HTML file that acts like powerpoint). Supported input
89+HTML file that acts like powerpoint).
79−formats include `markdown`, `html`, `latex`, and `rst`. Note that the
91+Supported input formats include `markdown`, `html`, `latex`, and `rst`.
80−`rst` reader only parses a subset of reStructuredText syntax. For
92+Note that the `rst` reader only parses a subset of reStructuredText
81−example, it doesn't handle tables, option lists, or footnotes. But for
93+syntax. For example, it doesn't handle tables, option lists, or
82−simple documents it should be adequate. The `latex` and `html` readers
94+footnotes. But for simple documents it should be adequate. The `latex`
83−are also limited in what they can do. Because the `html` reader is picky
95+and `html` readers are also limited in what they can do. Because the
84−about the HTML it parses, it is recommended that you pipe HTML through
96+`html` reader is picky about the HTML it parses, it is recommended that
85−[HTML Tidy] before sending it to `pandoc`, or use the `html2markdown`
97+you pipe HTML through [HTML Tidy] before sending it to `pandoc`, or use
86−script described below.
98+the `html2markdown` script described below.
88If you don't specify a reader or writer explicitly, `pandoc` will
100If you don't specify a reader or writer explicitly, `pandoc` will
89try to determine the input and output format from the extensions of
101try to determine the input and output format from the extensions of
@@ -92,9 +104,9 @@ the input and output filenames. Thus, for example,
92 pandoc -o hello.tex hello.txt
104 pandoc -o hello.tex hello.txt
94will convert `hello.txt` from markdown to LaTeX. If no output file
106will convert `hello.txt` from markdown to LaTeX. If no output file
95−is specified (so that output goes to STDOUT), or if the output file's
107+is specified (so that output goes to stdout), or if the output file's
96extension is unknown, the output format will default to HTML.
108extension is unknown, the output format will default to HTML.
97−If no input file is specified (so that input comes from STDIN), or
109+If no input file is specified (so that input comes from stdin), or
98if the input files' extensions are unknown, the input format will
110if the input files' extensions are unknown, the input format will
99be assumed to be markdown unless explicitly specified.
111be assumed to be markdown unless explicitly specified.
@@ -138,7 +150,7 @@ shell, but they may be used in Windows under Cygwin.)
139 markdown2pdf -o book.pdf chap1 chap2
151 markdown2pdf -o book.pdf chap1 chap2
141− If no input file is specified, input will be taken from STDIN.
153+ If no input file is specified, input will be taken from stdin.
142 All of `pandoc`'s options will work with `markdown2pdf` as well.
154 All of `pandoc`'s options will work with `markdown2pdf` as well.
144 `markdown2pdf` assumes that `pdflatex` is in the path. It also
156 `markdown2pdf` assumes that `pdflatex` is in the path. It also
@@ -161,7 +173,7 @@ shell, but they may be used in Windows under Cygwin.)
162 The `-e` or `--encoding` option specifies the character encoding
174 The `-e` or `--encoding` option specifies the character encoding
163 of the HTML input. If this option is not specified, and input
175 of the HTML input. If this option is not specified, and input
164− is not from STDIN, `html2markdown` will attempt to determine the
176+ is not from stdin, `html2markdown` will attempt to determine the
165 page's character encoding from the "Content-type" meta tag.
177 page's character encoding from the "Content-type" meta tag.
166 If this is not present, UTF-8 is assumed.
178 If this is not present, UTF-8 is assumed.
@@ -222,7 +234,9 @@ For further documentation, see the `pandoc(1)` man page.
223`-o` or `--output` *filename*
235`-o` or `--output` *filename*
224: sends output to *filename*. If this option is not specified,
236: sends output to *filename*. If this option is not specified,
225− or if its argument is `-`, output will be sent to STDOUT.
237+ or if its argument is `-`, output will be sent to stdout.
238+ (Exception: if the output format is `odt`, output to stdout
227`-p` or `--preserve-tabs`
241`-p` or `--preserve-tabs`
228: causes tabs in the source text to be preserved, rather than converted
242: causes tabs in the source text to be preserved, rather than converted
@@ -349,9 +363,9 @@ For further documentation, see the `pandoc(1)` man page.
349`--dump-args`
363`--dump-args`
350: is intended to make it easier to create wrapper scripts that use
364: is intended to make it easier to create wrapper scripts that use
351 Pandoc. It causes Pandoc to dump information about the arguments
365 Pandoc. It causes Pandoc to dump information about the arguments
352− with which it was called to STDOUT, then exit. The first line
366+ with which it was called to stdout, then exit. The first line
353 printed is the name of the output file specified using the `-o`
367 printed is the name of the output file specified using the `-o`
354− or `--output` option, or `-` if output would go to STDOUT. The
368+ or `--output` option, or `-` if output would go to stdout. The
355 remaining lines, if any, list command-line arguments. These will
369 remaining lines, if any, list command-line arguments. These will
356 include the names of input files and any special options passed
370 include the names of input files and any special options passed
357 after ` -- ` on the command line. So, for example,
371 after ` -- ` on the command line. So, for example,
@@ -359,7 +373,7 @@ For further documentation, see the `pandoc(1)` man page.
359: pandoc --dump-args -o foo.html -s foo.txt \
373: pandoc --dump-args -o foo.html -s foo.txt \
360 appendix.txt -- -e latin1
374 appendix.txt -- -e latin1
362−: will cause the following to be printed to STDOUT:
376+: will cause the following to be printed to stdout:
364: foo.html foo.txt appendix.txt -e latin1
378: foo.html foo.txt appendix.txt -e latin1
@@ -652,7 +666,7 @@ Simple tables look like this:
653The headers and table rows must each fit on one line. Column
667The headers and table rows must each fit on one line. Column
654alignments are determined by the position of the header text relative
668alignments are determined by the position of the header text relative
655−to the dashed line below it:[^1]
669+to the dashed line below it:[^3]
657 - If the dashed line is flush with the header text on the right side
671 - If the dashed line is flush with the header text on the right side
658 but extends beyond it on the left, the column is right-aligned.
672 but extends beyond it on the left, the column is right-aligned.
@@ -663,9 +677,8 @@ to the dashed line below it:[^1]
663 - If the dashed line is flush with the header text on both sides,
677 - If the dashed line is flush with the header text on both sides,
664 the default alignment is used (in most cases, this will be left).
678 the default alignment is used (in most cases, this will be left).
666−[^1]: This scheme is due to Michel Fortin, who proposed it on the
680+[^3]: This scheme is due to Michel Fortin, who proposed it on the
667− Markdown discussion list:
668− <http://six.pairlist.net/pipermail/markdown-discuss/2005-March/001097.html>.
681+ [Markdown discussion list](http://six.pairlist.net/pipermail/markdown-discuss/2005-March/001097.html).
670The table must end with a blank line. Optionally, a caption may be
683The table must end with a blank line. Optionally, a caption may be
671provided (as illustrated in the example above). A caption is a paragraph
684provided (as illustrated in the example above). A caption is a paragraph