@@ -2,11 +2,19 @@
22% John MacFarlane
33% August 10, 2006
44
5−`pandoc` converts files from one markup format to another. It can
6−read [markdown] and (with some limitations) [reStructuredText], [HTML], and
7−[LaTeX], and it can write [markdown], [reStructuredText], [HTML],
8−[LaTeX], [RTF], and [S5] HTML slide shows. It is written in
9−[Haskell], using the excellent [Parsec] parser combinator library.
5+`pandoc` is a [Haskell] library for converting files from one markup
6+format to another, and a command-line tool that uses this library. It can
7+read [markdown] and (subsets of) [reStructuredText], [HTML], and [LaTeX],
8+and it can write [markdown], [reStructuredText], [HTML], [LaTeX], [RTF],
9+and [S5] HTML slide shows. `pandoc`'s version of markdown contains some
10+enhancements, like footnotes and embedded LaTeX.
11+
12+In contrast to existing tools for converting markdown to HTML, which
13+use regex substitutions, `pandoc` has a modular design: it consists of a
14+set of readers, which parse text in a given format and produce a native
15+representation of the document, and a set of writers, which convert
16+this native representation into a target format. Thus, adding an input
17+or output format requires only adding a reader or writer.
1018
1119[markdown]: http://daringfireball.net/projects/markdown/
1220[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
@@ -15,7 +23,6 @@ read [markdown] and (with some limitations) [reStructuredText], [HTML], and
1523[LaTeX]: http://www.latex-project.org/
1624[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
1725[Haskell]: http://www.haskell.org/
18−[Parsec]: http://www.cs.uu.nl/~daan/download/parsec/parsec.html
1926
2027(c) 2006 John MacFarlane (jgm At berkeley.edu). Released under the
2128[GPL], version 2 or greater. This software carries no warranty of
@@ -27,7 +34,7 @@ any kind. (See LICENSE for full copyright and warranty notices.)
2734
2835## Installing GHC
2936
30−To compile `pandoc`, you'll need [GHC] version 6.4 or greater.
37+To compile `pandoc`, you'll need [GHC] version 6.4 or greater.
3138
3239If you don't have GHC already, you can get it from the
3340[GHC Download] page.
@@ -35,64 +42,57 @@ If you don't have GHC already, you can get it from the
3542[GHC]: http://www.haskell.org/ghc/
3643[GHC Download]: http://www.haskell.org/ghc/download.html
3744
38−Note: As of this writing, there's no MacOS X installer package for
39−GHC 6.4.2 (the latest version). There is an installer for
40−GHC 6.4.1 [here](http://www.haskell.org/ghc/download_ghc_641.html#macosx).
41−It will work just fine on PPC-based Macs. GHC has not yet been ported
42−to Intel Macs: see <http://hackage.haskell.org/trac/ghc/wiki/X86OSXGhc>.
43−
44−You'll also need standard build tools: GNU Make, sed, bash, and perl.
45+You'll also need standard build tools: GNU `make`, `sed`, `bash`, and `perl`.
4546These are standard on unix systems (including MacOS X). If you're
4647using Windows, you can install [Cygwin].
4748
4849[Cygwin]: http://www.cygwin.com/
4950
50−Note: I have tested `pandoc` on MacOS X and Linux systems. I have not
51−tried it on Windows, and I have no idea whether it will work on Windows.
52−
5351## Installing `pandoc`
5452
55531. Change to the directory containing the `pandoc` distribution.
5654
57552. Compile:
5856
59− make
57+ make
6058
61−3. Optional, but recommended:
59+3. See if it worked (optional, but recommended):
6260
63− make test
61+ make test
6462
65−4. If you want to install the `pandoc` program and the relevant wrappers
66− and documents (including this file) into `/usr/local` directory, type:
67−
68− make install
69−
70− If you only want the `pandoc` program and the shell scripts `latex2markdown`,
71− `markdown2latex`, `markdown2pdf`, `markdown2html`, `html2markdown` installed
72− into your `~/bin` directory, type (note the **`-exec`** suffix):
63+4. Install:
7364
74− PREFIX=~ make install-exec
65+ make install
7566
76−5. If you want to install the Pandoc library modules for use in
77− other Haskell programs, type (as root):
67+ Note: This installs `pandoc`, together with its wrappers and
68+ documentation, into the `/usr/local` directory, which requires root
69+ privileges. If you don't have root privileges or would prefer to
70+ install `pandoc` and the associated shell scripts into your `~/bin`
71+ directory, type this instead:
7872
79− make install-lib
80−
81−6. To install the library documentation (into `/usr/local/pandoc-doc`),
82− type:
73+ PREFIX=~ make install-exec
8374
84− make install-lib-doc
85−
86−# Using `pandoc`
75+5. Install Haskell libraries (optional):
76+
77+ make install-lib
78+
79+6. Install library documentation into `/usr/local/pandoc-doc` (optional):
80+
81+ make install-lib-doc
82+
83+## Removing `pandoc`
8784
88−You can run `pandoc` like this:
85+Each of the installation steps described above can be reversed:
8986
90− ./pandoc
87+ make uninstall
9188
92−If you copy the `pandoc` executable to a directory in your path
93−(perhaps using `make install`), you can invoke it without the "./":
89+ PREFIX=~ make uninstall-exec
9490
95− pandoc
91+ make uninstall-lib
92+
93+ make uninstall-lib-doc
94+
95+# Using `pandoc`
9696
9797If you run `pandoc` without arguments, it will accept input from
9898STDIN. If you run it with file names as arguments, it will take input
@@ -104,29 +104,34 @@ list, type
104104The most important options specify the format of the source file and
105105the output. The default reader is markdown; the default writer is
106106HTML. So if you don't specify a reader or writer, `pandoc` will
107−convert markdown to HTML. To convert markdown to LaTeX, you could
108−write:
107+convert markdown to HTML. For example,
109108
110− pandoc -w latex input.txt
109+ pandoc hello.txt
110+
111+will convert `hello.txt` from markdown to HTML. For other conversions,
112+you must specify a reader and/or a writer using the `-r` and `-w`
113+flags. To convert markdown to LaTeX, you would write:
114+
115+ pandoc -w latex hello.txt
111116
112117To convert html to markdown:
113118
114− pandoc -r html -w markdown input.txt
119+ pandoc -r html -w markdown hello.txt
115120
116−Supported writers include markdown, LaTeX, HTML, RTF,
117−reStructuredText, and S5 (which produces an HTML file that acts like
118−powerpoint). Supported readers include markdown, HTML, LaTeX, and
119−reStructuredText. Note that the rst (reStructuredText) reader only
120−parses a subset of rst syntax. For example, it doesn't handle tables,
121−definition lists, option lists, or footnotes. It handles only the
122−constructs expressible in unextended markdown. But for simple
123−documents it should be adequate. The LaTeX and HTML readers are also
124−limited in what they can do.
121+Supported writers include `markdown`, `latex`, `html`, `rtf` (rich text
122+format), `rst` (reStructuredText), and `s5` (which produces an HTML
123+file that acts like powerpoint). Supported readers include `markdown`,
124+`html`, `latex`, and `rst`. Note that the `rst` reader only parses
125+a subset of reStructuredText syntax. For example, it doesn't handle
126+tables, definition lists, option lists, or footnotes. It handles only the
127+constructs expressible in unextended markdown. But for simple documents
128+it should be adequate. The `latex` and `html` readers are also limited
129+in what they can do.
125130
126131`pandoc` writes its output to STDOUT. If you want to write to a file,
127132use redirection:
128133
129− pandoc input.txt > output.html
134+ pandoc hello.txt > hello.html
130135
131136Note that you can specify multiple input files on the command line.
132137`pandoc` will concatenate them all (with blank lines between them)
@@ -134,14 +139,18 @@ before parsing:
134139
135140 pandoc -s chapter1.txt chapter2.txt chapter3.txt references.txt > book.html
136141
142+(The `-s` option here tells `pandoc` to produce a standalone HTML file,
143+with a proper header, rather than a fragment. For more details on this
144+and many other command-line options, see below.)
145+
137146## Character encoding
138147
139−Unfortunately, due to limitations in GHC, `pandoc` does not
140−automatically detect the system's local character encoding. Hence,
141−all input and output is assumed to be in the UTF-8 encoding. If you
142−use accented or foreign characters, you should convert the input file
143−to UTF-8 before processing it with `pandoc`. This can be done by
144−piping the input through [`iconv`]: for example,
148+Unfortunately, due to limitations in GHC, `pandoc` does not automatically
149+detect the system's local character encoding. Hence, all input and
150+output is assumed to be in the UTF-8 encoding. If you use accented or
151+foreign characters, you should convert the input file to UTF-8 before
152+processing it with `pandoc`. This can be done by piping the input through
153+[`iconv`]: for example,
145154
146155 iconv -t utf-8 source.txt | pandoc > output.html
147156
@@ -158,18 +167,18 @@ from the local encoding to UTF-8 before running them through `pandoc`.
158167For convenience, five shell scripts have been included that make it
159168easy to run `pandoc` without remembering all the command-line options.
160169All of the scripts presuppose that `pandoc` is in the path, and
161−`html2markdown` also presupposes that `curl` and `tidy` are in the
162−path.
170+some have additional requirements. (For example, `html2markdown`
171+uses `tidy`, and `markdown2pdf` uses `pdflatex`.)
163172
1641731. `markdown2html` converts markdown to HTML, running `iconv` first to
165174 convert the file to UTF-8. (This can be used as a replacement for
166175 `Markdown.pl`.)
167176
1681772. `html2markdown` can take either a filename or a URL as argument. If
169− it is given a URL, it uses `curl` to fetch the contents of the
170− specified URL, then filters this through `tidy` to straighten up the
171− HTML and convert to UTF-8, and finally passes this HTML to `pandoc` to
172− produce markdown text:
178+ it is given a URL, it uses `curl`, `wget`, or an available text-based
179+ browser to fetch the contents of the specified URL, then filters this
180+ through `tidy` to straighten up the HTML and convert to UTF-8,
181+ and finally passes this HTML to `pandoc` to produce markdown text:
173182
174183 html2markdown http://www.fsf.org
175184
@@ -185,24 +194,23 @@ path.
185194
186195 markdown2latex mytextfile.txt
187196
188−5. `markdown2pdf` converts markdown to PDF, using LaTeX, but removing
189− all the intermediate files created by LaTeX. Example:
197+5. `markdown2pdf` converts markdown to PDF using `pdflatex`. Example:
190198
191199 markdown2pdf mytextfile.txt
192200
193− creates a file `mytextfile.pdf` in the working directory.
201+ creates a file `mytextfile.pdf`.
194202
195203# Command-line options
196204
197−Various command-line options can be used to customize the output.
205+Various command-line options can be used to customize the output.
198206For a complete list, type
199207
200− pandoc --help
208+ pandoc --help
201209
202210`-p` or `--preserve-tabs` causes tabs in the source text to be
203211preserved, rather than converted to spaces (the default).
204212
205−`--tabstop` allows the user to set the tab stop (which defaults to 4).
213+`--tabstop` allows the user to set the tab stop (which defaults to 4).
206214
207215`-R` or `--parse-raw` causes the HTML and LaTeX readers to parse HTML
208216codes and LaTeX environments that it can't translate as raw HTML or
@@ -258,7 +266,7 @@ not work in all browsers, but it works in Firefox. Peter Jipsen's
258266
259267`-i` or `--incremental` causes all lists in S5 output to be displayed
260268incrementally by default (one item at a time). The normal default
261−is for lists to be displayed all at once.
269+is for lists to be displayed all at once.
262270
263271`-N` or `--number-sections` causes sections to be numbered in LaTeX
264272output. By default, sections are not numbered.
@@ -267,7 +275,7 @@ output. By default, sections are not numbered.
267275
268276In parsing markdown, `pandoc` departs from and extends [standard markdown]
269277in a few respects. (To run `pandoc` on the official
270−markdown test suite, type `make markdown_tests`.)
278+markdown test suite, type `make test-markdown`.)
271279
272280[standard markdown]: http://daringfireball.net/projects/markdown/syntax
273281
@@ -328,7 +336,7 @@ appear as `[link]` if there's no reference for `link`. If you want
328336 except in embedded contexts like block quotes or lists.
329337
330338 ^(longnote) Here's the other note. This one contains multiple
331− blocks.
339+ blocks.
332340 ^
333341 ^ Caret characters are used to indicate that the blocks all belong
334342 to a single footnote (as with block quotes).
@@ -363,7 +371,7 @@ into
363371 </tr>
364372 </table>
365373
366−whereas Markdown 1.0 will preserve it as is.
374+whereas Markdown 1.0 will preserve it as is.
367375
368376There is one exception to this rule: text between `<script>` and
369377`</script>` tags is not interpreted as markdown.
@@ -468,7 +476,7 @@ Producing an [S5] slide show with `pandoc` is easy. A title page is
468476constructed automatically from the document's title block (see above).
469477Each section (with a level-one header) produces a single slide. (Note
470478that if the section is too big, the slide will not fit on the page; S5
471−is not smart enough to produce multiple pages.)
479+is not smart enough to produce multiple pages.)
472480
473481Here's the markdown source for a simple slide show, `eating.txt`:
474482