@@ -2,6 +2,14 @@
2% John MacFarlane
2% John MacFarlane
3% March 20, 2010
3% March 20, 2010
8+pandoc [*options*] [*input-file*]...
5Pandoc is a [Haskell] library for converting from one markup format to
13Pandoc is a [Haskell] library for converting from one markup format to
6another, and a command-line tool that uses this library. It can read
14another, and a command-line tool that uses this library. It can read
7[markdown] and (subsets of) [Textile], [reStructuredText], [HTML],
15[markdown] and (subsets of) [Textile], [reStructuredText], [HTML],
@@ -13,9 +21,10 @@ and [LaTeX]; and it can write plain text, [markdown], [reStructuredText],
13Pandoc's enhanced version of markdown includes syntax for footnotes,
21Pandoc's enhanced version of markdown includes syntax for footnotes,
14tables, flexible ordered lists, definition lists, delimited code blocks,
22tables, flexible ordered lists, definition lists, delimited code blocks,
15superscript, subscript, strikeout, title blocks, automatic tables of
23superscript, subscript, strikeout, title blocks, automatic tables of
16−contents, embedded LaTeX math, and markdown inside HTML block elements.
24+contents, embedded LaTeX math, citations, and markdown inside HTML block
17−(These enhancements can be disabled if a drop-in replacement for
25+elements. (These enhancements, described below under [Pandoc's markdown
18−`Markdown.pl` is desired.)
26+vs. standard markdown](#pandocs-markdown-vs-standard-markdown),
27+can be disabled using the `--strict` option.)
20In contrast to most existing tools for converting markdown to HTML, which
29In contrast to most existing tools for converting markdown to HTML, which
21use regex substitutions, Pandoc has a modular design: it consists of a
30use 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
24this native representation into a target format. Thus, adding an input
33this native representation into a target format. Thus, adding an input
25or output format requires only adding a reader or writer.
34or output format requires only adding a reader or writer.
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.
35Using Pandoc
36Using 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:
43− pandoc -o hello.html hello.txt
45−[^1]: The exceptions are for `odt` and `epub`. Since these are
46− a binary output formats, an output file must be specified explicitly.
48−Note that you can specify multiple input files on the command line.
49−`pandoc` will concatenate them all (with blank lines between them)
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:
54−(The `-s` option here tells `pandoc` to produce a standalone HTML file,
45+ pandoc -o output.html input.txt
55−with a proper header, rather than a fragment. For more details on this
56−and many other command-line options, see below.)
58−Instead of a filename, you can specify an absolute URI. In this
47+Instead of a file, an absolute URI may be given. In this case
59−case pandoc will attempt to download the content via HTTP:
48+pandoc will fetch the content using HTTP:
61 pandoc -f html -t markdown http://www.fsf.org
50 pandoc -f html -t markdown http://www.fsf.org
52+If multiple input files are given, `pandoc` will concatenate them all (with
53+blank lines between them) before parsing.
63The format of the input and output can be specified explicitly using
55The format of the input and output can be specified explicitly using
64command-line options. The input format can be specified using the
56command-line options. The input format can be specified using the
65`-r/--read` or `-f/--from` options, the output format using the
57`-r/--read` or `-f/--from` options, the output format using the
@@ -72,48 +64,31 @@ To convert `hello.html` from html to markdown:
73 pandoc -f html -t markdown hello.html
65 pandoc -f html -t markdown hello.html
75−Supported output formats include `markdown`, `latex`, `context`
67+Supported output formats are listed below under the `-t/--to` option.
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).
84−Supported input formats include `markdown`, `textile`, `html`,
68+Supported input formats are listed below under the `-f/--from` option. Note
85−`latex`, and `rst`. Note that the `rst` reader only parses a subset of
69+that the `rst` reader only parses a subset of reStructuredText syntax. For
86−reStructuredText syntax. For example, it doesn't handle tables, option
70+example, it doesn't handle tables, option lists, or footnotes. But for simple
87−lists, or footnotes. But for simple documents it should be adequate.
71+documents it should be adequate. The `textile`, `latex`, and `html` readers
88−The `textile`, `latex`, and `html` readers are also limited in what they
72+are also limited in what they can do.
90−
74+If the input or output format is not specified explicitly, `pandoc`
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
75+will attempt to guess it from the extensions of
93the input and output filenames. Thus, for example,
76the input and output filenames. Thus, for example,
95 pandoc -o hello.tex hello.txt
78 pandoc -o hello.tex hello.txt
97will convert `hello.txt` from markdown to LaTeX. If no output file
80will 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
99extension is unknown, the output format will default to HTML.
82extension 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
101if the input files' extensions are unknown, the input format will
84if the input files' extensions are unknown, the input format will
102be assumed to be markdown unless explicitly specified.
85be assumed to be markdown unless explicitly specified.
104−Character encodings
87+Pandoc uses the UTF-8 character encoding for both input and output.
105−-------------------
88+If your local character encoding is not UTF-8, you
89+should pipe input and output through `iconv`:
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,
112− iconv -t utf-8 source.txt | pandoc | iconv -f utf-8 > output.html
91+ iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
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`.
@@ -135,7 +110,7 @@ name can be specified explicitly using the `-o` option:
136 markdown2pdf -o book.pdf chap1 chap2
111 markdown2pdf -o book.pdf chap1 chap2
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*.
139All of `pandoc`'s options will work with `markdown2pdf` as well.
114All of `pandoc`'s options will work with `markdown2pdf` as well.
141`markdown2pdf` assumes that `pdflatex` is in the path. It also
116`markdown2pdf` assumes that `pdflatex` is in the path. It also
@@ -163,8 +138,8 @@ problems with its simulation of symbolic links.
163[TeX Live]: http://www.tug.org/texlive/
138[TeX Live]: http://www.tug.org/texlive/
164[MacTeX]: http://www.tug.org/mactex/
139[MacTeX]: http://www.tug.org/mactex/
166−Command-line options
141+Options
167−====================
142+=======
169`-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT*
144`-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT*
170: Specify input format. *FORMAT* can be
145: Specify input format. *FORMAT* can be
@@ -408,7 +383,7 @@ Command-line options
408: Print the default template for an output *FORMAT*. (See `-t`
383: Print the default template for an output *FORMAT*. (See `-t`
409 for a list of possible *FORMAT*s.)
384 for a list of possible *FORMAT*s.)
411−`-T` *STRING*, `--title-prefix=*STRING*
386+`-T` *STRING*, `--title-prefix=`*STRING*
412: Specify *STRING* as a prefix at the beginning of the title
387: Specify *STRING* as a prefix at the beginning of the title
413 that appears in the HTML header (but not in the title as it
388 that appears in the HTML header (but not in the title as it
414 appears at the beginning of the HTML body). Implies
389 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
1194line by accident (perhaps through line wrapping). Consider, for
1169line by accident (perhaps through line wrapping). Consider, for
1197− I like several of their flavors of ice cream: #22, for example, and
1172+ I like several of their flavors of ice cream:
1198− #5.
1173+ #22, for example, and #5.
@@ -1484,6 +1459,16 @@ ordinary HTML (without bird tracks).
1484writes HTML with the Haskell code in bird tracks, so it can be copied
1459writes HTML with the Haskell code in bird tracks, so it can be copied
1485and pasted as literate Haskell source.
1460and pasted as literate Haskell source.
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.
1488[markdown]: http://daringfireball.net/projects/markdown/
1473[markdown]: http://daringfireball.net/projects/markdown/
1489[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
1474[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html