summaryrefslogtreecommitdiff
path: root/INSTALL
blob: 41e3059acda18f4a1e97d9859822d2e09322868c (plain)
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
% Installing pandoc

Installing from Source
======================

This method will work on all architectures, but requires that you first
install the GHC compiler and some build tools: [GNU `make`], `sed`,
`bash`, and `perl`. These are standard on unix systems (including MacOS
X). If you're using Windows, you can install [Cygwin].

[Cygwin]: http://www.cygwin.com/
[GNU `make`]: http://www.gnu.org/software/make/

Installing GHC
--------------

To compile Pandoc, you'll need [GHC] version 6.6 or greater.  If
you don't have GHC already, you can get it from the [GHC Download]
page. If you're running MacOS X, you can also install GHC using
[MacPorts] or [Fink].

[GHC]: http://www.haskell.org/ghc/
[GHC Download]: http://www.haskell.org/ghc/download.html
[MacPorts]: http://macports.org
[Fink]: http://finkproject.org

Getting the source
------------------

Download the source tarball from pandoc's [pandoc's google code site].
Extract the contents into a subdirectory:

    tar xvzf pandoc-0.xy.tar.gz

[pandoc's google code site]: http://pandoc.googlecode.com

Installing Pandoc
-----------------

1.  Change to the directory containing the Pandoc distribution.
    If you are using a version of Cabal < 1.2 (which you probably
    are unless you've upgraded to GHC 6.8), do the following before
    proceeding:

        cp pandoc.cabal pandoc.cabal.orig
        cp pandoc.cabal.ghc66 pandoc.cabal

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.

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].

[haddock]: http://www.haskell.org/haddock/ 

Removing Pandoc
---------------

Each of the installation steps described above can be reversed:

    sudo make uninstall

    PREFIX=~ make uninstall-exec

    sudo make uninstall-all

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`:  Performs the needed preprocessing to create a proper
  Cabal package for Pandoc:
    - Builds `ASCIIMathML.hs`, `DefaultHeaders.hs`, and `S5.hs`
      from templates in `src/templates` and data in `src/ASCIIMathML.js`,
      `src/ui`, and `src/headers`.
    - 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) and creates the wrappers `html2markdown` and `markdown2pdf`
  from templates in `src/wrappers`.
* `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`.  (Three of the tests 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.
* `deb`:  Creates debian packages in `..` directory.
* `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 Cabal
=============================

Pandoc can also be installed using the standard Haskell packaging tool,
[Cabal](http://www.haskell.org/cabal/).  You'll need GHC 6.6 or greater
(see [Installing GHC](#installing-ghc), above). Just download the source
tarball, unpack, and type:

    runhaskell Setup.hs configure
    runhaskell Setup.hs build
    runhaskell Setup.hs install  # this one as root

This will install the pandoc executable and the Haskell libraries,
but not the shell scripts, man pages, or other documentation.

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`.  If you need
these, compile from source.

Installing pandoc on Debian
===========================

Pandoc is now in the debian unstable archive, 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.