@@ -2,6 +2,14 @@
22% John MacFarlane
33% March 20, 2010
44
5+Synopsis
6+========
7+
8+pandoc [*options*] [*input-file*]...
9+
10+Description
11+===========
12+
513Pandoc is a [Haskell] library for converting from one markup format to
614another, and a command-line tool that uses this library. It can read
715[markdown] and (subsets of) [Textile], [reStructuredText], [HTML],
@@ -13,9 +21,10 @@ and [LaTeX]; and it can write plain text, [markdown], [reStructuredText],
1321Pandoc's enhanced version of markdown includes syntax for footnotes,
1422tables, flexible ordered lists, definition lists, delimited code blocks,
1523superscript, subscript, strikeout, title blocks, automatic tables of
16−contents, embedded LaTeX math, and markdown inside HTML block elements.
17−(These enhancements can be disabled if a drop-in replacement for
18−`Markdown.pl` is desired.)
24+contents, embedded LaTeX math, citations, and markdown inside HTML block
25+elements. (These enhancements, described below under [Pandoc's markdown
26+vs. standard markdown](#pandocs-markdown-vs-standard-markdown),
27+can be disabled using the `--strict` option.)
1928
2029In contrast to most existing tools for converting markdown to HTML, which
2130use regex substitutions, Pandoc has a modular design: it consists of a
@@ -24,42 +33,25 @@ representation of the document, and a set of writers, which convert
2433this native representation into a target format. Thus, adding an input
2534or output format requires only adding a reader or writer.
2635
27−© 2006-2010 John MacFarlane (jgm at berkeley dot edu). Released under the
28−[GPL], version 2 or greater. This software carries no warranty of
29−any kind. (See COPYRIGHT for full copyright and warranty notices.)
30−Other contributors include Recai Oktaş, Paulo Tanimoto, Peter Wang,
31−Andrea Rossato, Eric Kow, infinity0x, Luke Plant, shreevatsa.public,
32−Puneeth Chaganti, Paul Rivier, rodja.trappe, Bradley Kuhn, thsutton,
33−Nathan Gass, Jonathan Daugherty, Jérémy Bobbio, Justin Bogner.
34−
3536Using Pandoc
36−============
37−
38−If you run `pandoc` without arguments, it will accept input from
39−stdin. If you run it with file names as arguments, it will take input
40−from those files. By default, `pandoc` writes its output to stdout.[^1]
41−If you want to write to a file, use the `-o` option:
42−
43− pandoc -o hello.html hello.txt
44−
45−[^1]: The exceptions are for `odt` and `epub`. Since these are
46− a binary output formats, an output file must be specified explicitly.
47−
48−Note that you can specify multiple input files on the command line.
49−`pandoc` will concatenate them all (with blank lines between them)
50−before parsing:
37+------------
5138
52− pandoc -s ch1.txt ch2.txt refs.txt > book.html
39+If no *input-file* is specified, input is read from *stdin*.
40+Otherwise, the *input-files* are concatenated (with a blank
41+line between each) and used as input. Output goes to *stdout* by
42+default (though output to *stdout* is disabled for the `odt` and
43+`epub` output formats). For output to a file, use the `-o` option:
5344
54−(The `-s` option here tells `pandoc` to produce a standalone HTML file,
55−with a proper header, rather than a fragment. For more details on this
56−and many other command-line options, see below.)
45+ pandoc -o output.html input.txt
5746
58−Instead of a filename, you can specify an absolute URI. In this
59−case pandoc will attempt to download the content via HTTP:
47+Instead of a file, an absolute URI may be given. In this case
48+pandoc will fetch the content using HTTP:
6049
6150 pandoc -f html -t markdown http://www.fsf.org
6251
52+If multiple input files are given, `pandoc` will concatenate them all (with
53+blank lines between them) before parsing.
54+
6355The format of the input and output can be specified explicitly using
6456command-line options. The input format can be specified using the
6557`-r/--read` or `-f/--from` options, the output format using the
@@ -72,48 +64,31 @@ To convert `hello.html` from html to markdown:
7264
7365 pandoc -f html -t markdown hello.html
7466
75−Supported output formats include `markdown`, `latex`, `context`
76−(ConTeXt), `html`, `rtf` (rich text format), `rst`
77−(reStructuredText), `docbook` (DocBook XML), `opendocument`
78−(OpenDocument XML), `odt` (OpenOffice text document), `texinfo`, (GNU
79−Texinfo), `mediawiki` (MediaWiki markup), `textile` (Textile),
80−`epub` (EPUB ebook), `man` (groff man), `org` (Emacs Org-Mode),
81−`slidy` (slidy HTML and javascript slide show), or `s5`
82−(S5 HTML and javascript slide show).
83−
84−Supported input formats include `markdown`, `textile`, `html`,
85−`latex`, and `rst`. Note that the `rst` reader only parses a subset of
86−reStructuredText syntax. For example, it doesn't handle tables, option
87−lists, or footnotes. But for simple documents it should be adequate.
88−The `textile`, `latex`, and `html` readers are also limited in what they
89−can do.
90−
91−If you don't specify a reader or writer explicitly, `pandoc` will
92−try to determine the input and output format from the extensions of
67+Supported output formats are listed below under the `-t/--to` option.
68+Supported input formats are listed below under the `-f/--from` option. Note
69+that the `rst` reader only parses a subset of reStructuredText syntax. For
70+example, it doesn't handle tables, option lists, or footnotes. But for simple
71+documents it should be adequate. The `textile`, `latex`, and `html` readers
72+are also limited in what they can do.
73+
74+If the input or output format is not specified explicitly, `pandoc`
75+will attempt to guess it from the extensions of
9376the input and output filenames. Thus, for example,
9477
9578 pandoc -o hello.tex hello.txt
9679
9780will convert `hello.txt` from markdown to LaTeX. If no output file
98−is specified (so that output goes to stdout), or if the output file's
81+is specified (so that output goes to *stdout*), or if the output file's
9982extension is unknown, the output format will default to HTML.
100−If no input file is specified (so that input comes from stdin), or
83+If no input file is specified (so that input comes from *stdin*), or
10184if the input files' extensions are unknown, the input format will
10285be assumed to be markdown unless explicitly specified.
10386
104−Character encodings
105−-------------------
87+Pandoc uses the UTF-8 character encoding for both input and output.
88+If your local character encoding is not UTF-8, you
89+should pipe input and output through `iconv`:
10690
107−All input is assumed to be in the UTF-8 encoding, and all output
108−is in UTF-8. If your local character encoding is not UTF-8 and you use
109−accented or foreign characters, you should pipe the input and output
110−through [`iconv`]. For example,
111−
112− iconv -t utf-8 source.txt | pandoc | iconv -f utf-8 > output.html
113−
114−will convert `source.txt` from the local encoding to UTF-8, then
115−convert it to HTML, then convert back to the local encoding,
116−putting the output in `output.html`.
91+ iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
11792
11893Wrappers
11994========
@@ -135,7 +110,7 @@ name can be specified explicitly using the `-o` option:
135110
136111 markdown2pdf -o book.pdf chap1 chap2
137112
138−If no input file is specified, input will be taken from stdin.
113+If no input file is specified, input will be taken from *stdin*.
139114All of `pandoc`'s options will work with `markdown2pdf` as well.
140115
141116`markdown2pdf` assumes that `pdflatex` is in the path. It also
@@ -163,8 +138,8 @@ problems with its simulation of symbolic links.
163138[TeX Live]: http://www.tug.org/texlive/
164139[MacTeX]: http://www.tug.org/mactex/
165140
166−Command-line options
167−====================
141+Options
142+=======
168143
169144`-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT*
170145: Specify input format. *FORMAT* can be
@@ -408,7 +383,7 @@ Command-line options
408383: Print the default template for an output *FORMAT*. (See `-t`
409384 for a list of possible *FORMAT*s.)
410385
411−`-T` *STRING*, `--title-prefix=*STRING*
386+`-T` *STRING*, `--title-prefix=`*STRING*
412387: Specify *STRING* as a prefix at the beginning of the title
413388 that appears in the HTML header (but not in the title as it
414389 appears at the beginning of the HTML body). Implies
@@ -1194,8 +1169,8 @@ it is all too easy for a `>` or `#` to end up at the beginning of a
11941169line by accident (perhaps through line wrapping). Consider, for
11951170example:
11961171
1197− I like several of their flavors of ice cream: #22, for example, and
1198− #5.
1172+ I like several of their flavors of ice cream:
1173+ #22, for example, and #5.
11991174
12001175Math
12011176----
@@ -1484,6 +1459,16 @@ ordinary HTML (without bird tracks).
14841459writes HTML with the Haskell code in bird tracks, so it can be copied
14851460and pasted as literate Haskell source.
14861461
1462+Authors
1463+=======
1464+
1465+© 2006-2010 John MacFarlane (jgm at berkeley dot edu). Released under the
1466+[GPL], version 2 or greater. This software carries no warranty of
1467+any kind. (See COPYRIGHT for full copyright and warranty notices.)
1468+Other contributors include Recai Oktaş, Paulo Tanimoto, Peter Wang,
1469+Andrea Rossato, Eric Kow, infinity0x, Luke Plant, shreevatsa.public,
1470+Puneeth Chaganti, Paul Rivier, rodja.trappe, Bradley Kuhn, thsutton,
1471+Nathan Gass, Jonathan Daugherty, Jérémy Bobbio, Justin Bogner.
14871472
14881473[markdown]: http://daringfireball.net/projects/markdown/
14891474[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html