@@ -4,13 +4,18 @@
44
55Pandoc is a [Haskell] library for converting from one markup format to
66another, 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
88it can write [markdown], [reStructuredText], [HTML], [LaTeX], [ConTeXt],
9−[RTF], [DocBook XML], [OpenDocument XML], [GNU Texinfo], [MediaWiki markup],
10−[groff man] pages, and [S5] HTML slide shows. Pandoc's version of
11−markdown contains some enhancements, like footnotes and embedded LaTeX.
12−
13−In contrast to existing tools for converting markdown to HTML, which
9+[RTF], [DocBook XML], [OpenDocument XML], [ODT], [GNU Texinfo],
10+[MediaWiki markup], [groff man] pages, and [S5] HTML slide shows.
11+Pandoc's enhanced version of markdown includes syntax for footnotes,
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.)
17+
18+In contrast to most existing tools for converting markdown to HTML, which
1419use regex substitutions, Pandoc has a modular design: it consists of a
1520set of readers, which parse text in a given format and produce a native
1621representation of the document, and a set of writers, which convert
@@ -26,6 +31,7 @@ or output format requires only adding a reader or writer.
2631[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
2732[DocBook XML]: http://www.docbook.org/
2833[OpenDocument XML]: http://opendocument.xml.org/
34+[ODT]: http://en.wikipedia.org/wiki/OpenDocument
2935[MediaWiki markup]: http://www.mediawiki.org/wiki/Help:Formatting
3036[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html
3137[Haskell]: http://www.haskell.org/
@@ -43,12 +49,16 @@ Using Pandoc
4349============
4450
4551If 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
47−from those files. By default, `pandoc` writes its output to STDOUT.
52+stdin. If you run it with file names as arguments, it will take input
53+from those files. By default, `pandoc` writes its output to stdout.[^1]
4854If you want to write to a file, use the `-o` option:
4955
5056 pandoc -o hello.html hello.txt
5157
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
60+ explicitly.
61+
5262Note that you can specify multiple input files on the command line.
5363`pandoc` will concatenate them all (with blank lines between them)
5464before parsing:
@@ -73,17 +83,19 @@ To convert `hello.html` from html to markdown:
7383
7484Supported output formats include `markdown`, `latex`, `context`
7585(ConTeXt), `html`, `rtf` (rich text format), `rst` (reStructuredText),
76−`docbook` (DocBook XML), `opendocument` (OpenDocument XML), `texinfo`,
77−`mediawiki` (MediaWiki markup), `man` (groff man), and `s5` (which
78−produces an HTML file that acts like powerpoint). Supported input
79−formats include `markdown`, `html`, `latex`, and `rst`. Note that the
80−`rst` reader only parses a subset of reStructuredText syntax. For
81−example, it doesn't handle tables, option lists, or footnotes. But for
82−simple documents it should be adequate. The `latex` and `html` readers
83−are also limited in what they can do. Because the `html` reader is picky
84−about the HTML it parses, it is recommended that you pipe HTML through
85−[HTML Tidy] before sending it to `pandoc`, or use the `html2markdown`
86−script described below.
86+`docbook` (DocBook XML), `opendocument` (OpenDocument XML), `odt`
87+(OpenOffice text document), `texinfo`, (GNU Texinfo), `mediawiki`
88+(MediaWiki markup), `man` (groff man), and `s5` (which produces an
89+HTML file that acts like powerpoint).
90+
91+Supported input formats include `markdown`, `html`, `latex`, and `rst`.
92+Note that the `rst` reader only parses a subset of reStructuredText
93+syntax. For example, it doesn't handle tables, option lists, or
94+footnotes. But for simple documents it should be adequate. The `latex`
95+and `html` readers are also limited in what they can do. Because the
96+`html` reader is picky about the HTML it parses, it is recommended that
97+you pipe HTML through [HTML Tidy] before sending it to `pandoc`, or use
98+the `html2markdown` script described below.
8799
88100If you don't specify a reader or writer explicitly, `pandoc` will
89101try to determine the input and output format from the extensions of
@@ -92,9 +104,9 @@ the input and output filenames. Thus, for example,
92104 pandoc -o hello.tex hello.txt
93105
94106will 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
96108extension 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
98110if the input files' extensions are unknown, the input format will
99111be assumed to be markdown unless explicitly specified.
100112
@@ -138,7 +150,7 @@ shell, but they may be used in Windows under Cygwin.)
138150
139151 markdown2pdf -o book.pdf chap1 chap2
140152
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.
142154 All of `pandoc`'s options will work with `markdown2pdf` as well.
143155
144156 `markdown2pdf` assumes that `pdflatex` is in the path. It also
@@ -161,7 +173,7 @@ shell, but they may be used in Windows under Cygwin.)
161173
162174 The `-e` or `--encoding` option specifies the character encoding
163175 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
165177 page's character encoding from the "Content-type" meta tag.
166178 If this is not present, UTF-8 is assumed.
167179
@@ -222,7 +234,9 @@ For further documentation, see the `pandoc(1)` man page.
222234
223235`-o` or `--output` *filename*
224236: 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
239+ is disabled.)
226240
227241`-p` or `--preserve-tabs`
228242: 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.
349363`--dump-args`
350364: is intended to make it easier to create wrapper scripts that use
351365 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
353367 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
355369 remaining lines, if any, list command-line arguments. These will
356370 include the names of input files and any special options passed
357371 after ` -- ` on the command line. So, for example,
@@ -359,7 +373,7 @@ For further documentation, see the `pandoc(1)` man page.
359373: pandoc --dump-args -o foo.html -s foo.txt \
360374 appendix.txt -- -e latin1
361375
362−: will cause the following to be printed to STDOUT:
376+: will cause the following to be printed to stdout:
363377
364378: foo.html foo.txt appendix.txt -e latin1
365379
@@ -652,7 +666,7 @@ Simple tables look like this:
652666
653667The headers and table rows must each fit on one line. Column
654668alignments 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]
656670
657671 - If the dashed line is flush with the header text on the right side
658672 but extends beyond it on the left, the column is right-aligned.
@@ -663,9 +677,8 @@ to the dashed line below it:[^1]
663677 - If the dashed line is flush with the header text on both sides,
664678 the default alignment is used (in most cases, this will be left).
665679
666−[^1]: 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>.
680+[^3]: This scheme is due to Michel Fortin, who proposed it on the
681+ [Markdown discussion list](http://six.pairlist.net/pipermail/markdown-discuss/2005-March/001097.html).
669682
670683The table must end with a blank line. Optionally, a caption may be
671684provided (as illustrated in the example above). A caption is a paragraph