@@ -1,43 +1,32 @@
1% Installing pandoc
1% Installing pandoc
3−Installing from Source
3+Installing pandoc from Source
4−======================
4+=============================
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].
11−[Cygwin]: http://www.cygwin.com/
6+This method will work on all architectures for which the GHC compiler
12−[GNU `make`]: http://www.gnu.org/software/make/
7+is available.
14Installing GHC
9Installing GHC
15--------------
10--------------
17−To compile Pandoc, you'll need [GHC] version 6.6 or greater and [Cabal]
12+To compile Pandoc, you'll need [GHC] version 6.8 or greater. If you
18−version 1.2 or greater. If you don't have GHC already, you can get it
13+don't have GHC already, you can get it from the [GHC Download] page.
19−from the [GHC Download] page. If you're compiling GHC from source, be
14+If you're compiling GHC from source, be sure to get the `extralibs`
20−sure to get the `extralibs` in addition to the base tarball. GHC comes
15+in addition to the base tarball. Pandoc requires Cabal version 1.2 or
21−with a version of Cabal. Note, however, that the version of Cabal that
16+greater. If your GHC comes with an older version of Cabal, you'll need
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
17+to to [install Cabal] separately. You can check your Cabal version using
24−Cabal version using `ghc-pkg list`.
18+`ghc-pkg list`.
26−If you're running MacOS X, it may be more convenient to install GHC
20+If you're running MacOS X, you can also install GHC using [MacPorts] or [Fink].
27−using [MacPorts] or [Fink].
29If you're on a [debian]-based linux system (such as [Ubuntu]), you can get
22If you're on a [debian]-based linux system (such as [Ubuntu]), you can get
30GHC and the required libraries using `apt-get`:
23GHC and the required libraries using `apt-get`:
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
34−Otherwise, you should already have all the libraries you need except for
27+Pandoc will use the [utf8-string] library if it is installed; otherwise, it
35−`utf8-string`. Download the [utf8-string] tarball from HackageDB, extract it, and
28+will use its own internal module for UTF-8 I/O. The utf8-string library is
36−switch to that directory. Then:
29+not a required dependency, but it may improve performance slightly.
38− runghc Setup.lhs configure
39− runghc Setup.lhs build
40− sudo runghc Setup.lhs install
42[GHC]: http://www.haskell.org/ghc/
31[GHC]: http://www.haskell.org/ghc/
43[GHC Download]: http://www.haskell.org/ghc/download.html
32[GHC Download]: http://www.haskell.org/ghc/download.html
@@ -52,15 +41,23 @@ switch to that directory. Then:
52Getting the source
41Getting the source
53------------------
42------------------
55−Download the source tarball from pandoc's [pandoc's google code site].
44+Download the source tarball from [pandoc's google code site].
56Extract the contents into a subdirectory:
45Extract the contents into a subdirectory:
58− tar xvzf pandoc-0.xy.tar.gz
47+ tar xvzf pandoc-x.y.tar.gz
60[pandoc's google code site]: http://pandoc.googlecode.com
49[pandoc's google code site]: http://pandoc.googlecode.com
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].
55+[install pandoc using Make]: #installing-pandoc-using-make
56+[install pandoc using Cabal]: #installing-pandoc-using-cabal
57+[build options]: #build-options
62−Installing Pandoc
59+Installing Pandoc using Make
63−-----------------
60+----------------------------
651. Change to the directory containing the Pandoc distribution.
621. Change to the directory containing the Pandoc distribution.
@@ -109,20 +106,26 @@ Installing Pandoc
110 Note that building the library documentation requires [haddock].
107 Note that building the library documentation requires [haddock].
109+6. If you decide you don't want pandoc on your system, each of the
110+ installation steps described above can be reversed:
114+ PREFIX=~ make uninstall-exec
116+ sudo make uninstall-all
112[haddock]: http://www.haskell.org/haddock/
118[haddock]: http://www.haskell.org/haddock/
114Installing pandoc using Cabal
120Installing pandoc using Cabal
115-----------------------------
121-----------------------------
117−Pandoc can also be installed using the standard Haskell packaging tool,
123+Change to the directory containing the pandoc source, and type:
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:
122 runhaskell Setup.hs configure
125 runhaskell Setup.hs configure
123 runhaskell Setup.hs build
126 runhaskell Setup.hs build
124 runhaskell Setup.hs haddock # optional, to build library documentation
127 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
127This will install the pandoc executable and the Haskell libraries,
130This will install the pandoc executable and the Haskell libraries,
128but not the shell scripts, man pages, or other documentation.
131but not the shell scripts, man pages, or other documentation.
@@ -134,19 +137,17 @@ flag):
134 runhaskell Setup.hs configure -f-library # just the executable
137 runhaskell Setup.hs configure -f-library # just the executable
135 runhaskell Setup.hs configure -f-executable # just the libraries
138 runhaskell Setup.hs configure -f-executable # just the libraries
137−Note: If you are using GHC 6.6.*, you will need to start by
140+You can also specify the directory tree into which pandoc will be
138−replacing `pandoc.cabal` with a version suitable for GHC 6.6:
141+installed using the `--prefix=` option to `configure`. For more details,
142+see the [Cabal User's Guide].
140− cp pandoc.cabal pandoc.cabal.orig
144+[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
141− cp pandoc.cabal.ghc66 pandoc.cabal
143Optional syntax highlighting support
146Optional syntax highlighting support
144------------------------------------
147------------------------------------
146Pandoc can optionally be compiled with support for syntax highlighting of
149Pandoc can optionally be compiled with support for syntax highlighting of
147delimited code blocks. This feature requires the [`highlighting-kate` library].
150delimited code blocks. This feature requires the [`highlighting-kate` library].
148−It also requires Cabal version 1.2 or greater.
150If you are using Cabal to compile pandoc, specify the `highlighting` flag in
151If you are using Cabal to compile pandoc, specify the `highlighting` flag in
151the configure step:
152the configure step:
@@ -161,17 +162,6 @@ If you have already built pandoc, you may need to do a `make clean` or
162[`highlighting-kate` library]: http://johnmacfarlane.net/highlighting-kate
163[`highlighting-kate` library]: http://johnmacfarlane.net/highlighting-kate
167−Each of the installation steps described above can be reversed:
171− PREFIX=~ make uninstall-exec
173− sudo make uninstall-all
175Other targets
165Other targets
176-------------
166-------------
@@ -180,11 +170,7 @@ but are documented here for packagers and developers:
181### Building and installing
171### Building and installing
183−* `configure`: Performs the needed preprocessing to create a proper
173+* `configure`:
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`.
188 - Stores values of relevant environment variables in `vars` for
174 - Stores values of relevant environment variables in `vars` for
189 persistence.
175 persistence.
190 - Runs Cabal's "configure" command.
176 - Runs Cabal's "configure" command.
@@ -204,7 +190,7 @@ but are documented here for packagers and developers:
205* `test`: Runs Pandoc's test suite. (All tests should pass.)
191* `test`: Runs Pandoc's test suite. (All tests should pass.)
206* `test-markdown`: Runs the Markdown regression test suite, using
192* `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.)
209### Cleaning
195### Cleaning
@@ -245,14 +231,12 @@ Extract the files from the archive, and put `pandoc.exe` somewhere
245in your PATH.
231in your PATH.
247Note that the Windows binary distribution does not include the shell
233Note that the Windows binary distribution does not include the shell
248−scripts `markdown2pdf`, `html2markdown`, or `hsmarkdown`. If you need
234+scripts `markdown2pdf`, `html2markdown`, or `hsmarkdown`.
249−these, compile from source.
251Installing pandoc on Debian
236Installing pandoc on Debian
252===========================
237===========================
254−Pandoc is now in the debian unstable archive, and can be installed
239+Pandoc is now in the debian archives, and can be installed using `apt-get` (as root):
255−using `apt-get` (as root):
257 apt-get install pandoc # the program, shell scripts, and docs
241 apt-get install pandoc # the program, shell scripts, and docs
258 apt-get install libghc6-pandoc-dev # the libraries
242 apt-get install libghc6-pandoc-dev # the libraries