@@ -1,189 +1,105 @@
11% Installing pandoc
22
3−Installing pandoc from Source
4−=============================
3+These instructions explain how to install pandoc from source.
4+Binary packages or ports of pandoc are available for freebsd
5+and several linux distributions, so check your package manager.
6+There is also a Windows installer.
57
6−This method will work on all architectures for which the GHC compiler
7−is available.
8−
9−Installing GHC
10−--------------
11−
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`.
19−
20−If you're running MacOS X, you can also install GHC using [MacPorts] or [Fink].
21−
22−If you're on a [debian]-based linux system (such as [Ubuntu]), you can get
23−GHC and some required libraries using `apt-get`:
24−
25− sudo apt-get install ghc6 libghc6-xhtml-dev libghc6-mtl-dev libghc6-network-dev
26−
27−[GHC]: http://www.haskell.org/ghc/
28−[GHC Download]: http://www.haskell.org/ghc/download.html
29−[Cabal]: http://www.haskell.org/cabal/
30−[install Cabal]: http://www.haskell.org/cabal/download.html
31−[MacPorts]: http://macports.org
32−[Fink]: http://finkproject.org
33−[Ubuntu]: http://www.ubuntu.com
34−[debian]: http://www.debian.org/
35−
36−Installing prerequisites
37−------------------------
38−
39−Pandoc needs the `utf8-string` and `zip-archive` to compile.
40−Check your packaging system to see if they are included.
41−If not, you will need to compile them from source.
42−
43−On \*nix systems, the easiest way to do this is to install
44−the [cabal-install] tool. See the section [Quick Installation
45−on Unix] for instructions. If you use [MacPorts], you can
46−just install the `hs-cabal` port.
47−
48−[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
49−[Quick Installation on Unix]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall#QuickInstallationonUnix
50−
51−Once you've got `cabal-install` installed, you can install the
52−needed libraries by doing
53−
54− cabal install utf8-string
55− cabal install zip-archive
56−
57−Alternatively, you can install these libraries using the [standard
58−Cabal method], but you will have to install their dependencies manually.
59−
60−[standard Cabal method]: http://haskell.org/haskellwiki/Cabal/How_to_install_a_Cabal_package
61−
62−Getting the source
63−------------------
64−
65−Download the source tarball from [pandoc's google code site].
66−Extract the contents into a subdirectory:
67−
68− tar xvzf pandoc-x.y.tar.gz
69−
70−[pandoc's google code site]: http://pandoc.googlecode.com
71−
72−Now choose one of the following methods for compiling and installing
73−pandoc. If you are on a linux or unix-based system, you can [install
74−pandoc using Make]. If not, you should [install pandoc using Cabal].
8+Quick install
9+-------------
7510
76−[install pandoc using Make]: #installing-pandoc-using-make
77−[install pandoc using Cabal]: #installing-pandoc-using-cabal
78−[build options]: #build-options
11+1. Install the [Haskell platform]. This will give you [GHC] and
12+the [cabal-install] build tool.
7913
80−Installing Pandoc using Make
81−----------------------------
14+2. Use `cabal` to install pandoc and its dependencies:
8215
83−1. Change to the directory containing the Pandoc distribution.
16+ cabal install pandoc
8417
85−2. Compile:
18+ If you want support for source code syntax highlighting, set
19+ the `highlighting` flag:
8620
87− make
21+ cabal install -fhighlighting pandoc
8822
89− If you get "Unknown modifier" errors, it is probably because `make`
90− on your system is not [GNU `make`]. Try using `gmake` instead.
23+3. Make sure the `$CABALDIR/bin` directory is in your path. You should
24+now be able to run `pandoc`:
9125
92− If you get a message saying that the `zip-archive` or `utf8-string`
93− libraries cannot be found, and you have installed these using
94− `cabal-install`, it is probably because by default `cabal-install`
95− installs libraries to the user's directory rather than globally.
96− Try again with
26+ pandoc --help
9727
98− CABALOPTS=--user make
28+4. Make sure the `$CABALDIR/share/man/man1` directory is in your `MANPATH`.
29+You should now be able to access the `pandoc` man page:
9930
100−3. See if it worked (optional, but recommended):
31+ man pandoc
10132
102− make test
33+[GHC]: http://www.haskell.org/ghc/
34+[Haskell platform]: http://hackage.haskell.org/platform/
35+[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
10336
104−4. Install:
37+Custom install
38+--------------
10539
106− sudo make install
40+This is a step-by-step procedure that offers maximal control
41+over the build and installation. Most users should use the
42+quick install, but this information may be of use to packagers.
43+For more details, see the [Cabal User's Guide].
10744
108− Note: This installs `pandoc`, together with its wrappers and
109− documentation, into the `/usr/local` directory. If you'd rather
110− install `pandoc` somewhere else--say, in `/opt/local`--you can
111− set the `PREFIX` environment variable:
45+1. Install dependencies: in addition to the [Haskell platform],
46+you will need [zip-archive] and (if you want syntax highlighting)
47+[highlighting-kate].
11248
113− PREFIX=/opt/local sudo make install
49+2. Configure:
11450
115− If you don't have root privileges or would prefer to install
116− `pandoc` and the associated wrappers into your `~/bin` directory,
117− type this instead:
51+ runghc Setup.hs configure --prefix=DIR --bindir=DIR --libdir=DIR \
52+ --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \
53+ --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \
54+ --mandir=DIR --flags=FLAGSPEC
11855
119− PREFIX=~ make install-exec
56+ All of the options have sensible defaults that can be overridden
57+ as needed.
12058
121−5. Build and install the Haskell libraries and library
122− documentation (optional--for Haskell programmers only):
59+ `FLAGSPEC` is a list of Cabal configuration flags, optionally
60+ preceded by a `-` (to force the flag to `false`), and separated
61+ by spaces. Pandoc's flags include:
12362
124− make build-all
125− sudo make install-all
63+ - `library`: build the library (default yes)
64+ - `executable`: build the pandoc executable (default yes)
65+ - `wrappers`: build the wrappers `markdown2pdf` and `hsmarkdown`
66+ (default yes)
67+ - `highlighting`: compile with syntax highlighting support (increases
68+ the size of the executable) (default no)
12669
127− Note that building the library documentation requires [haddock].
70+ So, for example,
12871
129−6. If you decide you don't want pandoc on your system, each of the
130− installation steps described above can be reversed:
72+ --flags="-library highlighting"
13173
132− sudo make uninstall
74+ tells Cabal to build the executable but not the library, and to
75+ compile with syntax highlighting support.
13376
134− PREFIX=~ make uninstall-exec
77+3. Build:
13578
136− sudo make uninstall-all
79+ runghc Setup.hs build
13780
138−[haddock]: http://www.haskell.org/haddock/
81+4. Build API documentation:
13982
140−Installing pandoc using Cabal
141−-----------------------------
83+ runghc Setup.hs haddock --html-location=URL --hyperlink-source
14284
143−Change to the directory containing the pandoc source, and type:
85+5. Copy the files:
14486
145− runhaskell Setup configure # add --user if you have installed prerequisites
146− # locally using cabal-install
147− runhaskell Setup build
148− runhaskell Setup haddock # optional, to build library documentation
149− runhaskell Setup test # optional, to run test suite
150− runhaskell Setup install # this one as root or sudo, or add --user
87+ runghc Setup.hs copy --destdir=PATH
15188
152−This will install the pandoc executable and the Haskell libraries,
153−but not the shell scripts, man pages, or other documentation.
89+ The default destdir is `/`.
15490
155−You may just want the executable, or just the libraries. This
156−can be controlled with configuration flags (the `-` negates the
157−flag):
91+6. Register pandoc as a GHC package:
15892
159− runhaskell Setup configure -f-library # just the executable
160− runhaskell Setup configure -f-executable # just the libraries
93+ runghc Setup.hs register
16194
162−You can also specify the directory tree into which pandoc will be
163−installed using the `--prefix=` option to `configure`. For more details,
164−see the [Cabal User's Guide].
95+ Package managers may want to use the `--gen-script` option to
96+ generate a script that can be run to register the package at
97+ install time.
16598
99+[zip-archive]: http://hackage.haskell.org/package/zip-archive
100+[highlighting-kate]: http://hackage.haskell.org/package/highlighting-kate
166101[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
167102
168−Optional syntax highlighting support
169−------------------------------------
170−
171−Pandoc can optionally be compiled with support for syntax highlighting of
172−delimited code blocks. This feature requires the [`highlighting-kate` library].
173−If you are using Cabal to compile pandoc, specify the `highlighting` flag in
174−the configure step:
175−
176− runhaskell Setup configure -fhighlighting
177−
178−If you are using the Makefile:
179−
180− CABALOPTS=-fhighlighting make
181−
182−If you have already built pandoc, you may need to do a `make clean` or
183−`runhaskell Setup clean` first.
184−
185−[`highlighting-kate` library]: http://johnmacfarlane.net/highlighting-kate
186−
187103Optional citeproc support
188104-------------------------
189105
@@ -199,133 +115,7 @@ support is experimental, and the interface may change in the future.)
199115If you are using Cabal to compile pandoc, specify the `citeproc` flag in
200116the configure step:
201117
202− runhaskell Setup configure -fciteproc
203−
204−If you are using the Makefile:
205−
206− CABALOPTS=-fciteproc make
207−
208−If you have already built pandoc, you may need to do a `make clean` or
209−`runhaskell Setup clean` first.
118+ runhaskell Setup configure --flags="citeproc"
210119
211120[`citeproc-hs` library]: http://code.haskell.org/citeproc-hs/
212121
213−Other targets
214−-------------
215−
216−The following 'make' targets should not be needed by the average user,
217−but are documented here for packagers and developers:
218−
219−### Building and installing
220−
221−* `configure`:
222− - Stores values of relevant environment variables in `vars` for
223− persistence.
224− - Runs Cabal's "configure" command.
225−* `build-exec`: Builds `pandoc` executable (using Cabal's "build"
226− command).
227−* `build-doc`: Builds program documentation (e.g. `README.html`).
228−* `build-lib-doc`: Builds Haddock documentation for Pandoc libraries.
229−* `install-doc`, `uninstall-doc`: Installs/uninstalls user documentation
230− and man pages.
231−* `install-lib-doc`, `uninstall-lib-doc`: Installs/uninstalls library
232− documentation and man pages.
233−* `install-exec`, `uninstall-exec`: Installs/uninstalls programs
234− (`pandoc` and wrappers).
235−
236−### Testing
237−
238−* `test`: Runs Pandoc's test suite. (All tests should pass.)
239−* `test-markdown`: Runs the Markdown regression test suite, using
240− `pandoc --strict`. (One test will fail.)
241−
242−### Cleaning
243−
244−* `clean`: Restores directory to pre-build state, removing generated files.
245−* `distclean`: Like clean, but also cleans up files created by `make deb`.
246−
247−### Packaging
248−
249−* `tarball`: Creates a source tarball for distribution.
250−* `macport`: Creates MacPorts Portfile in `macports` directory.
251−* `freebsd`: Creates freebsd Makefile and distinfo in `freebsd` directory.
252−* `win-pkg`: Creates a Windows binary package (presupposes `pandoc.exe`,
253− which must be created by building Pandoc on a Windows machine).
254−* `website`: Creates Pandoc's website in `web/pandoc` directory.
255−
256−Installing pandoc using MacPorts
257−================================
258−
259−This is an alternative to compiling from source on MacOS X.
260−[MacPorts] is a system for building and maintaining \*nix software
261−on MacOS X computers. If you don't already have MacPorts, follow
262−[these instructions for installing
263−it](http://trac.macosforge.org/projects/macports/wiki/InstallingMacPorts).
264−
265−Once you've installed MacPorts, you can install pandoc by typing:
266−
267− sudo port sync # to get the most recent ports
268− sudo port install pandoc
269−
270−Since pandoc depends on GHC, the process may take a long time.
271−
272−Note that the version of pandoc in MacPorts may not be the most recent.
273−To get the most recent version, you can use `cabal-install`:
274−
275− sudo port install hs-cabal
276− cabal install pandoc --user # optionally: -fciteproc -fhighlighting
277−
278−This will install the `pandoc` executable into `~/.cabal/bin`. This method
279−will not install the wrapper scripts or man pages; if you want those, follow
280−the instructions above for compiling from source.
281−
282−Installing the Windows binary
283−=============================
284−
285−Simply download the Windows installer [pandoc's google code site]
286−and run it. It will install `pandoc.exe` and ensure that it is
287−in your system PATH.
288−
289−Note that the Windows binary distribution does not include the shell
290−scripts `markdown2pdf`, `html2markdown`, or `hsmarkdown`.
291−
292−Installing pandoc on Debian
293−===========================
294−
295−Pandoc is now in the debian archives, and can be installed using `apt-get` (as root):
296−
297− apt-get install pandoc # the program, shell scripts, and docs
298− apt-get install libghc6-pandoc-dev # the libraries
299− apt-get install pandoc-doc # library documentation
300−
301−Thanks to Recai Oktaş for setting up the debian packages.
302−
303−Note that the version of pandoc in Debian may not be the most recent.
304−
305−Installing pandoc on FreeBSD
306−============================
307−
308−Pandoc is in the FreeBSD ports repository (`textproc/pandoc`) and can be
309−installed in the normal way:
310−
311− cd /usr/ports/textproc/pandoc
312− make install clean # as root
313−
314−Alternatively, you can use `pkg_add`:
315−
316− pkg_add -r pandoc
317−
318−Note that the version of pandoc in FreeBSD's official repository may be
319−somewhat older than the most recent version.
320−
321−Installing pandoc on Arch linux
322−===============================
323−
324−There are two `pandoc` packages in the Arch AUR repositories,
325−`pandoc` (contributed by Abhishek Dasgupta) and `haskell-pandoc`
326−(contributed by Dons Stewart). `haskell-pandoc` is more up-to-date,
327−but does not install the man pages or wrapper scripts.
328−
329− pacman -Sy pandoc
330− pacman -Sy haskell-pandoc
331−