@@ -1,43 +1,32 @@
11% Installing pandoc
22
3−Installing from Source
4−======================
5−
6−This method will work on all architectures, but requires that you first
7−install the GHC compiler and some build tools: [GNU `make`], `sed`,
8−`bash`, and `perl`. These are standard on unix systems (including MacOS
9−X). If you're using Windows, you can install [Cygwin].
3+Installing pandoc from Source
4+=============================
105
11−[Cygwin]: http://www.cygwin.com/
12−[GNU `make`]: http://www.gnu.org/software/make/
6+This method will work on all architectures for which the GHC compiler
7+is available.
138
149Installing GHC
1510--------------
1611
17−To compile Pandoc, you'll need [GHC] version 6.6 or greater and [Cabal]
18−version 1.2 or greater. If you don't have GHC already, you can get it
19−from the [GHC Download] page. If you're compiling GHC from source, be
20−sure to get the `extralibs` in addition to the base tarball. GHC comes
21−with a version of Cabal. Note, however, that the version of Cabal that
22−comes with GHC 6.6 is not recent enough. So if you are using GHC 6.6,
23−you'll probably need to [install Cabal] separately. You can check your
24−Cabal version using `ghc-pkg list`.
12+To compile Pandoc, you'll need [GHC] version 6.8 or greater. If you
13+don't have GHC already, you can get it from the [GHC Download] page.
14+If you're compiling GHC from source, be sure to get the `extralibs`
15+in addition to the base tarball. Pandoc requires Cabal version 1.2 or
16+greater. If your GHC comes with an older version of Cabal, you'll need
17+to to [install Cabal] separately. You can check your Cabal version using
18+`ghc-pkg list`.
2519
26−If you're running MacOS X, it may be more convenient to install GHC
27−using [MacPorts] or [Fink].
20+If you're running MacOS X, you can also install GHC using [MacPorts] or [Fink].
2821
2922If you're on a [debian]-based linux system (such as [Ubuntu]), you can get
3023GHC and the required libraries using `apt-get`:
3124
32− sudo apt-get install ghc6 libghc6-xhtml-dev libghc6-mtl-dev libghc6-network-dev libghc6-utf8-string-dev
25+ sudo apt-get install ghc6 libghc6-xhtml-dev libghc6-mtl-dev libghc6-network-dev
3326
34−Otherwise, you should already have all the libraries you need except for
35−`utf8-string`. Download the [utf8-string] tarball from HackageDB, extract it, and
36−switch to that directory. Then:
37−
38− runghc Setup.lhs configure
39− runghc Setup.lhs build
40− sudo runghc Setup.lhs install
27+Pandoc will use the [utf8-string] library if it is installed; otherwise, it
28+will use its own internal module for UTF-8 I/O. The utf8-string library is
29+not a required dependency, but it may improve performance slightly.
4130
4231[GHC]: http://www.haskell.org/ghc/
4332[GHC Download]: http://www.haskell.org/ghc/download.html
@@ -52,15 +41,23 @@ switch to that directory. Then:
5241Getting the source
5342------------------
5443
55−Download the source tarball from pandoc's [pandoc's google code site].
44+Download the source tarball from [pandoc's google code site].
5645Extract the contents into a subdirectory:
5746
58− tar xvzf pandoc-0.xy.tar.gz
47+ tar xvzf pandoc-x.y.tar.gz
5948
6049[pandoc's google code site]: http://pandoc.googlecode.com
6150
62−Installing Pandoc
63−-----------------
51+Now choose one of the following methods for compiling and installing
52+pandoc. If you are on a linux or unix-based system, you can [install
53+pandoc using Make]. If not, you should [install pandoc using Cabal].
54+
55+[install pandoc using Make]: #installing-pandoc-using-make
56+[install pandoc using Cabal]: #installing-pandoc-using-cabal
57+[build options]: #build-options
58+
59+Installing Pandoc using Make
60+----------------------------
6461
65621. Change to the directory containing the Pandoc distribution.
6663
@@ -109,20 +106,26 @@ Installing Pandoc
109106
110107 Note that building the library documentation requires [haddock].
111108
109+6. If you decide you don't want pandoc on your system, each of the
110+ installation steps described above can be reversed:
111+
112+ sudo make uninstall
113+
114+ PREFIX=~ make uninstall-exec
115+
116+ sudo make uninstall-all
117+
112118[haddock]: http://www.haskell.org/haddock/
113119
114120Installing pandoc using Cabal
115121-----------------------------
116122
117−Pandoc can also be installed using the standard Haskell packaging tool,
118−[Cabal](http://www.haskell.org/cabal/). You'll need GHC 6.6 or greater
119−and Cabal 1.2 or greater (see [Installing GHC](#installing-ghc), above).
120−Just download the source tarball, unpack, and type:
123+Change to the directory containing the pandoc source, and type:
121124
122125 runhaskell Setup.hs configure
123126 runhaskell Setup.hs build
124127 runhaskell Setup.hs haddock # optional, to build library documentation
125− runhaskell Setup.hs install # this one as root
128+ runhaskell Setup.hs install # this one as root or sudo
126129
127130This will install the pandoc executable and the Haskell libraries,
128131but not the shell scripts, man pages, or other documentation.
@@ -134,19 +137,17 @@ flag):
134137 runhaskell Setup.hs configure -f-library # just the executable
135138 runhaskell Setup.hs configure -f-executable # just the libraries
136139
137−Note: If you are using GHC 6.6.*, you will need to start by
138−replacing `pandoc.cabal` with a version suitable for GHC 6.6:
140+You can also specify the directory tree into which pandoc will be
141+installed using the `--prefix=` option to `configure`. For more details,
142+see the [Cabal User's Guide].
139143
140− cp pandoc.cabal pandoc.cabal.orig
141− cp pandoc.cabal.ghc66 pandoc.cabal
144+[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
142145
143146Optional syntax highlighting support
144147------------------------------------
145148
146149Pandoc can optionally be compiled with support for syntax highlighting of
147150delimited code blocks. This feature requires the [`highlighting-kate` library].
148−It also requires Cabal version 1.2 or greater.
149−
150151If you are using Cabal to compile pandoc, specify the `highlighting` flag in
151152the configure step:
152153
@@ -161,17 +162,6 @@ If you have already built pandoc, you may need to do a `make clean` or
161162
162163[`highlighting-kate` library]: http://johnmacfarlane.net/highlighting-kate
163164
164−Removing Pandoc
165−---------------
166−
167−Each of the installation steps described above can be reversed:
168−
169− sudo make uninstall
170−
171− PREFIX=~ make uninstall-exec
172−
173− sudo make uninstall-all
174−
175165Other targets
176166-------------
177167
@@ -180,11 +170,7 @@ but are documented here for packagers and developers:
180170
181171### Building and installing
182172
183−* `configure`: Performs the needed preprocessing to create a proper
184− Cabal package for Pandoc:
185− - Builds `ASCIIMathML.hs`, `DefaultHeaders.hs`, and `S5.hs`
186− from templates in `src/templates` and data in `src/ASCIIMathML.js`,
187− `src/ui`, and `src/headers`.
173+* `configure`:
188174 - Stores values of relevant environment variables in `vars` for
189175 persistence.
190176 - Runs Cabal's "configure" command.
@@ -204,7 +190,7 @@ but are documented here for packagers and developers:
204190
205191* `test`: Runs Pandoc's test suite. (All tests should pass.)
206192* `test-markdown`: Runs the Markdown regression test suite, using
207− `pandoc --strict`. (Three of the tests will fail.)
193+ `pandoc --strict`. (One test will fail.)
208194
209195### Cleaning
210196
@@ -245,14 +231,12 @@ Extract the files from the archive, and put `pandoc.exe` somewhere
245231in your PATH.
246232
247233Note that the Windows binary distribution does not include the shell
248−scripts `markdown2pdf`, `html2markdown`, or `hsmarkdown`. If you need
249−these, compile from source.
234+scripts `markdown2pdf`, `html2markdown`, or `hsmarkdown`.
250235
251236Installing pandoc on Debian
252237===========================
253238
254−Pandoc is now in the debian unstable archive, and can be installed
255−using `apt-get` (as root):
239+Pandoc is now in the debian archives, and can be installed using `apt-get` (as root):
256240
257241 apt-get install pandoc # the program, shell scripts, and docs
258242 apt-get install libghc6-pandoc-dev # the libraries