@@ -1,16 +1,16 @@
1−% pandoc
1+% Pandoc
22% John MacFarlane
33% October 30, 2006
44
5−`pandoc` is a [Haskell] library for converting from one markup format
5+Pandoc is a [Haskell] library for converting from one markup format
66to another, and a command-line tool that uses this library. It can read
77[markdown] and (subsets of) [reStructuredText], [HTML], and [LaTeX],
88and 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
1010enhancements, like footnotes and embedded LaTeX.
1111
1212In 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
1414set of readers, which parse text in a given format and produce a native
1515representation of the document, and a set of writers, which convert
1616this native representation into a target format. Thus, adding an input
@@ -32,64 +32,7 @@ system, the debian package, and the robust wrapper scripts.
3232
3333[GPL]: http://www.gnu.org/copyleft/gpl.html
3434
35−# Installation
36−
37−## Installing GHC
38−
39−To compile `pandoc`, you'll need [GHC] version 6.4 or greater.
40−
41−If you don't have GHC already, you can get it from the
42−[GHC Download] page.
43−
44−[GHC]: http://www.haskell.org/ghc/
45−[GHC Download]: http://www.haskell.org/ghc/download.html
46−
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].
50−
51−[Cygwin]: http://www.cygwin.com/
52−
53−## Installing `pandoc`
54−
55−1. Change to the directory containing the `pandoc` distribution.
56−
57−2. Compile:
58−
59− make
60−
61−3. See if it worked (optional, but recommended):
62−
63− make test
64−
65−4. Install:
66−
67− make install
68−
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:
74−
75− PREFIX=~ make install-exec
76−
77−5. Install everthing, including Haskell libraries and library documentation
78− (optional):
79−
80− make install-all
81−
82−## Removing `pandoc`
83−
84−Each of the installation steps described above can be reversed:
85−
86− make uninstall
87−
88− PREFIX=~ make uninstall-exec
89−
90− make uninstall-all
91−
92−# Using `pandoc`
35+# Using Pandoc
9336
9437If you run `pandoc` without arguments, it will accept input from
9538STDIN. If you run it with file names as arguments, it will take input
@@ -140,7 +83,7 @@ before parsing:
14083with a proper header, rather than a fragment. For more details on this
14184and many other command-line options, see below.)
14285
143−## Character encoding
86+# Character encodings
14487
14588Unfortunately, due to limitations in GHC, `pandoc` does not automatically
14689detect the system's local character encoding. Hence, all input and
@@ -159,7 +102,7 @@ convert it to HTML, putting the output in `output.html`.
159102The shell scripts (described below) automatically convert the source
160103from the local encoding to UTF-8 before running them through `pandoc`.
161104
162−## The shell scripts
105+# The shell scripts
163106
164107For convenience, five shell scripts have been included that make it
165108easy to run `pandoc` without remembering all the command-line options.
@@ -268,17 +211,17 @@ is for lists to be displayed all at once.
268211`-N` or `--number-sections` causes sections to be numbered in LaTeX
269212output. By default, sections are not numbered.
270213
271−# `pandoc`'s markdown vs. standard markdown
214+# Pandoc's markdown vs. standard markdown
272215
273−In parsing markdown, `pandoc` departs from and extends [standard markdown]
274−in a few respects. (To run `pandoc` on the official
216+In parsing markdown, Pandoc departs from and extends [standard markdown]
217+in a few respects. (To run Pandoc on the official
275218markdown test suite, type `make test-markdown`.)
276219
277220[standard markdown]: http://daringfireball.net/projects/markdown/syntax
278221
279222## Lists
280223
281−`pandoc` behaves differently from standard markdown on some "edge
224+Pandoc behaves differently from standard markdown on some "edge
282225cases" involving lists. Consider this source:
283226
284227 1. First
@@ -289,10 +232,10 @@ cases" involving lists. Consider this source:
289232
290233 3. Third
291234
292−`pandoc` transforms this into a "compact list" (with no `<p>` tags
235+Pandoc transforms this into a "compact list" (with no `<p>` tags
293236around "First", "Second", or "Third"), while markdown puts `<p>`
294237tags 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:
296239if the text is followed by a blank line, it is treated as a
297240paragraph. Since "Second" is followed by a list, and not a blank
298241line, it isn't treated as a paragraph. The fact that the list
@@ -305,13 +248,13 @@ in
305248
306249 [foo]: "bar "embedded" baz"
307250
308−`pandoc` requires all quotes within titles to be escaped:
251+Pandoc requires all quotes within titles to be escaped:
309252
310253 [foo]: "bar \"embedded\" baz"
311254
312255## Reference links
313256
314−`pandoc` allows implicit reference links in either of two styles:
257+Pandoc allows implicit reference links in either of two styles:
315258
316259 1. Here's my [link]
317260 2. Here's my [link][]
@@ -325,7 +268,7 @@ appear as `[link]` if there's no reference for `link`. If you want
325268
326269## Footnotes
327270
328−`pandoc`'s markdown allows footnotes, using the following syntax:
271+Pandoc's markdown allows footnotes, using the following syntax:
329272
330273 here is a footnote reference,^(1) and another.^(longnote)
331274
@@ -347,10 +290,10 @@ Footnote references may not contain spaces, tabs, or newlines.
347290
348291## Embedded HTML
349292
350−`pandoc` treats embedded HTML in markdown a bit differently than
293+Pandoc treats embedded HTML in markdown a bit differently than
351294Markdown 1.0. While Markdown 1.0 leaves HTML blocks exactly as they
352−are, `pandoc` treats text between HTML tags as markdown. Thus, for
353−example, `pandoc` will turn
295+are, Pandoc treats text between HTML tags as markdown. Thus, for
296+example, Pandoc will turn
354297
355298 <table>
356299 <tr>
@@ -413,7 +356,7 @@ HTML title.
413356
414357## Box-style blockquotes
415358
416−`pandoc` supports emacs-style boxquote block quotes, in addition to
359+Pandoc supports emacs-style boxquote block quotes, in addition to
417360standard markdown (email-style) boxquotes:
418361
419362 ,----
@@ -467,9 +410,9 @@ it and specify it on the command line as follows:
467410
468411 pandoc --header=MyHeaderFile
469412
470−# Producing S5 with `pandoc`
413+# Producing S5 with Pandoc
471414
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
473416constructed automatically from the document's title block (see above).
474417Each section (with a level-one header) produces a single slide. (Note
475418that if the section is too big, the slide will not fit on the page; S5