1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
|
% Installing pandoc
Installing pandoc from Source
=============================
This method will work on all architectures for which the GHC compiler
is available.
Installing GHC
--------------
To compile Pandoc, you'll need [GHC] version 6.8 or greater. If you
don't have GHC already, you can get it from the [GHC Download] page.
If you're compiling GHC from source, be sure to get the `extralibs`
in addition to the base tarball. Pandoc requires Cabal version 1.2 or
greater. If your GHC comes with an older version of Cabal, you'll need
to to [install Cabal] separately. You can check your Cabal version using
`ghc-pkg list`.
If you're running MacOS X, you can also install GHC using [MacPorts] or [Fink].
If you're on a [debian]-based linux system (such as [Ubuntu]), you can get
GHC and some required libraries using `apt-get`:
sudo apt-get install ghc6 libghc6-xhtml-dev libghc6-mtl-dev libghc6-network-dev
[GHC]: http://www.haskell.org/ghc/
[GHC Download]: http://www.haskell.org/ghc/download.html
[Cabal]: http://www.haskell.org/cabal/
[install Cabal]: http://www.haskell.org/cabal/download.html
[MacPorts]: http://macports.org
[Fink]: http://finkproject.org
[Ubuntu]: http://www.ubuntu.com
[debian]: http://www.debian.org/
Installing prerequisites
------------------------
Pandoc needs the `utf8-string` and `zip-archive` to compile.
Check your packaging system to see if they are included.
If not, you will need to compile them from source.
On \*nix systems, the easiest way to do this is to install
the [cabal-install] tool. See the section [Quick Installation
on Unix] for instructions. If you use [MacPorts], you can
just install the `hs-cabal` port.
[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
[Quick Installation on Unix]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall#QuickInstallationonUnix
Once you've got `cabal-install` installed, you can install the
needed libraries by doing
cabal install utf8-string
cabal install zip-archive
Alternatively, you can install these libraries using the [standard
Cabal method], but you will have to install their dependencies manually.
[standard Cabal method]: http://haskell.org/haskellwiki/Cabal/How_to_install_a_Cabal_package
Getting the source
------------------
Download the source tarball from [pandoc's google code site].
Extract the contents into a subdirectory:
tar xvzf pandoc-x.y.tar.gz
[pandoc's google code site]: http://pandoc.googlecode.com
Now choose one of the following methods for compiling and installing
pandoc. If you are on a linux or unix-based system, you can [install
pandoc using Make]. If not, you should [install pandoc using Cabal].
[install pandoc using Make]: #installing-pandoc-using-make
[install pandoc using Cabal]: #installing-pandoc-using-cabal
[build options]: #build-options
Installing Pandoc using Make
----------------------------
1. Change to the directory containing the Pandoc distribution.
2. Compile:
make
If you get "Unknown modifier" errors, it is probably because `make`
on your system is not [GNU `make`]. Try using `gmake` instead.
If you get a message saying that the `zip-archive` or `utf8-string`
libraries cannot be found, and you have installed these using
`cabal-install`, it is probably because by default `cabal-install`
installs libraries to the user's directory rather than globally.
Try again with
CABALOPTS=--user make
3. See if it worked (optional, but recommended):
make test
Note: if you see errors like the following, they're due to differences
between different versions of the xhtml library, and can safely be
disregarded:
2c2
< <html xmlns="http://www.w3.org/1999/xhtml"
---
> <html
4. Install:
sudo make install
Note: This installs `pandoc`, together with its wrappers and
documentation, into the `/usr/local` directory. If you'd rather
install `pandoc` somewhere else--say, in `/opt/local`--you can
set the `PREFIX` environment variable:
PREFIX=/opt/local sudo make install
If you don't have root privileges or would prefer to install
`pandoc` and the associated wrappers into your `~/bin` directory,
type this instead:
PREFIX=~ make install-exec
5. Build and install the Haskell libraries and library
documentation (optional--for Haskell programmers only):
make build-all
sudo make install-all
Note that building the library documentation requires [haddock].
6. If you decide you don't want pandoc on your system, each of the
installation steps described above can be reversed:
sudo make uninstall
PREFIX=~ make uninstall-exec
sudo make uninstall-all
[haddock]: http://www.haskell.org/haddock/
Installing pandoc using Cabal
-----------------------------
Change to the directory containing the pandoc source, and type:
runhaskell Setup.hs configure # add --user if you have installed
# prerequisites locally with cabal-install
runhaskell Setup.hs build
runhaskell Setup.hs haddock # optional, to build library documentation
runhaskell Setup.hs install # this one as root or sudo
This will install the pandoc executable and the Haskell libraries,
but not the shell scripts, man pages, or other documentation.
You may just want the executable, or just the libraries. This
can be controlled with configuration flags (the `-` negates the
flag):
runhaskell Setup.hs configure -f-library # just the executable
runhaskell Setup.hs configure -f-executable # just the libraries
You can also specify the directory tree into which pandoc will be
installed using the `--prefix=` option to `configure`. For more details,
see the [Cabal User's Guide].
[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
Optional syntax highlighting support
------------------------------------
Pandoc can optionally be compiled with support for syntax highlighting of
delimited code blocks. This feature requires the [`highlighting-kate` library].
If you are using Cabal to compile pandoc, specify the `highlighting` flag in
the configure step:
runhaskell Setup.hs configure -fhighlighting
If you are using the Makefile:
CABALOPTS=-fhighlighting make
If you have already built pandoc, you may need to do a `make clean` or
`runhaskell Setup.hs clean` first.
[`highlighting-kate` library]: http://johnmacfarlane.net/highlighting-kate
Other targets
-------------
The following 'make' targets should not be needed by the average user,
but are documented here for packagers and developers:
### Building and installing
* `configure`:
- Stores values of relevant environment variables in `vars` for
persistence.
- Runs Cabal's "configure" command.
* `build-exec`: Builds `pandoc` executable (using Cabal's "build"
command).
* `build-doc`: Builds program documentation (e.g. `README.html`).
* `build-lib-doc`: Builds Haddock documentation for Pandoc libraries.
* `install-doc`, `uninstall-doc`: Installs/uninstalls user documentation
and man pages.
* `install-lib-doc`, `uninstall-lib-doc`: Installs/uninstalls library
documentation and man pages.
* `install-exec`, `uninstall-exec`: Installs/uninstalls programs
(`pandoc` and wrappers).
### Testing
* `test`: Runs Pandoc's test suite. (All tests should pass.)
* `test-markdown`: Runs the Markdown regression test suite, using
`pandoc --strict`. (One test will fail.)
### Cleaning
* `clean`: Restores directory to pre-build state, removing generated files.
* `distclean`: Like clean, but also cleans up files created by `make deb`.
### Packaging
* `tarball`: Creates a source tarball for distribution.
* `macport`: Creates MacPorts Portfile in `macports` directory.
* `freebsd`: Creates freebsd Makefile and distinfo in `freebsd` directory.
* `win-pkg`: Creates a Windows binary package (presupposes `pandoc.exe`,
which must be created by building Pandoc on a Windows machine).
* `website`: Creates Pandoc's website in `web/pandoc` directory.
Installing pandoc using MacPorts
================================
This is an alternative to compiling from source on MacOS X.
[MacPorts] is a system for building and maintaining \*nix software
on MacOS X computers. If you don't already have MacPorts, follow
[these instructions for installing
it](http://trac.macosforge.org/projects/macports/wiki/InstallingMacPorts).
Once you've installed MacPorts, you can install pandoc by typing:
sudo port sync # to get the most recent ports
sudo port install pandoc
Since pandoc depends on GHC, the process may take a long time.
Installing the Windows binary
=============================
Simply download the zip file from [pandoc's google code site].
Extract the files from the archive, and put `pandoc.exe` somewhere
in your PATH.
Note that the Windows binary distribution does not include the shell
scripts `markdown2pdf`, `html2markdown`, or `hsmarkdown`.
Installing pandoc on Debian
===========================
Pandoc is now in the debian archives, and can be installed using `apt-get` (as root):
apt-get install pandoc # the program, shell scripts, and docs
apt-get install libghc6-pandoc-dev # the libraries
apt-get install pandoc-doc # library documentation
Thanks to Recai Oktaş for setting up the debian packages.
Installing pandoc on FreeBSD
============================
Pandoc is in the FreeBSD ports repository (`textproc/pandoc`) and can be
installed in the normal way:
cd /usr/ports/textproc/pandoc
make install clean # as root
Alternatively, you can use `pkg_add`:
pkg_add -r pandoc
Note that the version of pandoc in FreeBSD's official repository may be
somewhat older than the most recent version.
Installing pandoc on Arch linux
===============================
Abhishek Dasgupta has created a binary package for `pandoc` in the
Arch linux repository. Arch users can install `pandoc` by typing
pacman -Sy pandoc
|
