@@ -1,16 +1,16 @@
2% John MacFarlane
2% John MacFarlane
3% October 30, 2006
3% October 30, 2006
5−`pandoc` is a [Haskell] library for converting from one markup format
5+Pandoc is a [Haskell] library for converting from one markup format
6to another, and a command-line tool that uses this library. It can read
6to another, and a command-line tool that uses this library. It can read
7[markdown] and (subsets of) [reStructuredText], [HTML], and [LaTeX],
7[markdown] and (subsets of) [reStructuredText], [HTML], and [LaTeX],
8and it can write [markdown], [reStructuredText], [HTML], [LaTeX], [RTF],
8and it can write [markdown], [reStructuredText], [HTML], [LaTeX], [RTF],
9−and [S5] HTML slide shows. `pandoc`'s version of markdown contains some
9+and [S5] HTML slide shows. Pandoc's version of markdown contains some
10enhancements, like footnotes and embedded LaTeX.
10enhancements, like footnotes and embedded LaTeX.
12In contrast to existing tools for converting markdown to HTML, which
12In contrast to existing tools for converting markdown to HTML, which
13−use regex substitutions, `pandoc` has a modular design: it consists of a
13+use regex substitutions, Pandoc has a modular design: it consists of a
14set of readers, which parse text in a given format and produce a native
14set of readers, which parse text in a given format and produce a native
15representation of the document, and a set of writers, which convert
15representation of the document, and a set of writers, which convert
16this native representation into a target format. Thus, adding an input
16this native representation into a target format. Thus, adding an input
@@ -32,64 +32,7 @@ system, the debian package, and the robust wrapper scripts.
33[GPL]: http://www.gnu.org/copyleft/gpl.html
33[GPL]: http://www.gnu.org/copyleft/gpl.html
39−To compile `pandoc`, you'll need [GHC] version 6.4 or greater.
41−If you don't have GHC already, you can get it from the
44−[GHC]: http://www.haskell.org/ghc/
45−[GHC Download]: http://www.haskell.org/ghc/download.html
47−You'll also need standard build tools: GNU `make`, `sed`, `bash`, and `perl`.
48−These are standard on unix systems (including MacOS X). If you're
49−using Windows, you can install [Cygwin].
51−[Cygwin]: http://www.cygwin.com/
53−## Installing `pandoc`
55−1. Change to the directory containing the `pandoc` distribution.
61−3. See if it worked (optional, but recommended):
69− Note: This installs `pandoc`, together with its wrappers and
70− documentation, into the `/usr/local` directory, which requires root
71− privileges. If you don't have root privileges or would prefer to
72− install `pandoc` and the associated shell scripts into your `~/bin`
73− directory, type this instead:
75− PREFIX=~ make install-exec
77−5. Install everthing, including Haskell libraries and library documentation
84−Each of the installation steps described above can be reversed:
88− PREFIX=~ make uninstall-exec
92−# Using `pandoc`
35+# Using Pandoc
94If you run `pandoc` without arguments, it will accept input from
37If you run `pandoc` without arguments, it will accept input from
95STDIN. If you run it with file names as arguments, it will take input
38STDIN. If you run it with file names as arguments, it will take input
@@ -140,7 +83,7 @@ before parsing:
140with a proper header, rather than a fragment. For more details on this
83with a proper header, rather than a fragment. For more details on this
141and many other command-line options, see below.)
84and many other command-line options, see below.)
143−## Character encoding
86+# Character encodings
145Unfortunately, due to limitations in GHC, `pandoc` does not automatically
88Unfortunately, due to limitations in GHC, `pandoc` does not automatically
146detect the system's local character encoding. Hence, all input and
89detect the system's local character encoding. Hence, all input and
@@ -159,7 +102,7 @@ convert it to HTML, putting the output in `output.html`.
159The shell scripts (described below) automatically convert the source
102The shell scripts (described below) automatically convert the source
160from the local encoding to UTF-8 before running them through `pandoc`.
103from the local encoding to UTF-8 before running them through `pandoc`.
162−## The shell scripts
105+# The shell scripts
164For convenience, five shell scripts have been included that make it
107For convenience, five shell scripts have been included that make it
165easy to run `pandoc` without remembering all the command-line options.
108easy to run `pandoc` without remembering all the command-line options.
@@ -268,17 +211,17 @@ is for lists to be displayed all at once.
268`-N` or `--number-sections` causes sections to be numbered in LaTeX
211`-N` or `--number-sections` causes sections to be numbered in LaTeX
269output. By default, sections are not numbered.
212output. By default, sections are not numbered.
271−# `pandoc`'s markdown vs. standard markdown
214+# Pandoc's markdown vs. standard markdown
273−In parsing markdown, `pandoc` departs from and extends [standard markdown]
216+In parsing markdown, Pandoc departs from and extends [standard markdown]
274−in a few respects. (To run `pandoc` on the official
217+in a few respects. (To run Pandoc on the official
275markdown test suite, type `make test-markdown`.)
218markdown test suite, type `make test-markdown`.)
277[standard markdown]: http://daringfireball.net/projects/markdown/syntax
220[standard markdown]: http://daringfireball.net/projects/markdown/syntax
281−`pandoc` behaves differently from standard markdown on some "edge
224+Pandoc behaves differently from standard markdown on some "edge
282cases" involving lists. Consider this source:
225cases" involving lists. Consider this source:
@@ -289,10 +232,10 @@ cases" involving lists. Consider this source:
292−`pandoc` transforms this into a "compact list" (with no `<p>` tags
235+Pandoc transforms this into a "compact list" (with no `<p>` tags
293around "First", "Second", or "Third"), while markdown puts `<p>`
236around "First", "Second", or "Third"), while markdown puts `<p>`
294tags around "Second" and "Third" (but not "First"), because of
237tags around "Second" and "Third" (but not "First"), because of
295−the blank space around "Third". `pandoc` follows a simple rule:
238+the blank space around "Third". Pandoc follows a simple rule:
296if the text is followed by a blank line, it is treated as a
239if the text is followed by a blank line, it is treated as a
297paragraph. Since "Second" is followed by a list, and not a blank
240paragraph. Since "Second" is followed by a list, and not a blank
298line, it isn't treated as a paragraph. The fact that the list
241line, it isn't treated as a paragraph. The fact that the list
@@ -305,13 +248,13 @@ in
306 [foo]: "bar "embedded" baz"
249 [foo]: "bar "embedded" baz"
308−`pandoc` requires all quotes within titles to be escaped:
251+Pandoc requires all quotes within titles to be escaped:
310 [foo]: "bar \"embedded\" baz"
253 [foo]: "bar \"embedded\" baz"
312## Reference links
255## Reference links
314−`pandoc` allows implicit reference links in either of two styles:
257+Pandoc allows implicit reference links in either of two styles:
316 1. Here's my [link]
259 1. Here's my [link]
317 2. Here's my [link][]
260 2. Here's my [link][]
@@ -325,7 +268,7 @@ appear as `[link]` if there's no reference for `link`. If you want
326## Footnotes
269## Footnotes
328−`pandoc`'s markdown allows footnotes, using the following syntax:
271+Pandoc's markdown allows footnotes, using the following syntax:
330 here is a footnote reference,^(1) and another.^(longnote)
273 here is a footnote reference,^(1) and another.^(longnote)
@@ -347,10 +290,10 @@ Footnote references may not contain spaces, tabs, or newlines.
348## Embedded HTML
291## Embedded HTML
350−`pandoc` treats embedded HTML in markdown a bit differently than
293+Pandoc treats embedded HTML in markdown a bit differently than
351Markdown 1.0. While Markdown 1.0 leaves HTML blocks exactly as they
294Markdown 1.0. While Markdown 1.0 leaves HTML blocks exactly as they
352−are, `pandoc` treats text between HTML tags as markdown. Thus, for
295+are, Pandoc treats text between HTML tags as markdown. Thus, for
353−example, `pandoc` will turn
296+example, Pandoc will turn
@@ -413,7 +356,7 @@ HTML title.
414## Box-style blockquotes
357## Box-style blockquotes
416−`pandoc` supports emacs-style boxquote block quotes, in addition to
359+Pandoc supports emacs-style boxquote block quotes, in addition to
417standard markdown (email-style) boxquotes:
360standard markdown (email-style) boxquotes:
@@ -467,9 +410,9 @@ it and specify it on the command line as follows:
468 pandoc --header=MyHeaderFile
411 pandoc --header=MyHeaderFile
470−# Producing S5 with `pandoc`
413+# Producing S5 with Pandoc
472−Producing an [S5] slide show with `pandoc` is easy. A title page is
415+Producing an [S5] slide show with Pandoc is easy. A title page is
473constructed automatically from the document's title block (see above).
416constructed automatically from the document's title block (see above).
474Each section (with a level-one header) produces a single slide. (Note
417Each section (with a level-one header) produces a single slide. (Note
475that if the section is too big, the slide will not fit on the page; S5
418that if the section is too big, the slide will not fit on the page; S5