pandoc/INSTALL

% 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

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 configure   # add --user if you have installed prerequisites
                                 # locally using cabal-install
    runhaskell Setup build
    runhaskell Setup haddock     # optional, to build library documentation
    runhaskell Setup test        # optional, to run test suite
    runhaskell Setup install     # this one as root or sudo, or add --user

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 configure -f-library      # just the executable
    runhaskell Setup 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 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 clean` first.

[`highlighting-kate` library]: http://johnmacfarlane.net/highlighting-kate

Optional citeproc support
-------------------------

Pandoc can optionally be compiled with support for bibliographic citations
using Andrea Rossato's [`citeproc-hs` library].  This allows you
to specify citations in markdown using an intuitive syntax (for example,
`[jones2005@p. 3; smith2006]`). These are automatically changed into
appropriately styled citations in the output, and a bibliography is
added.  The bibliography data and style information are taken from XML
files that must be specified on the command line. (Note:  `citeproc-hs`
support is experimental, and the interface may change in the future.)

If you are using Cabal to compile pandoc, specify the `citeproc` flag in
the configure step:

    runhaskell Setup configure -fciteproc

If you are using the Makefile:

    CABALOPTS=-fciteproc make

If you have already built pandoc, you may need to do a `make clean` or
`runhaskell Setup clean` first.

[`citeproc-hs` library]: http://code.haskell.org/citeproc-hs/

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.

Note that the version of pandoc in MacPorts may not be the most recent.
To get the most recent version, you can use `cabal-install`:

    sudo port install hs-cabal
    cabal install pandoc --user  # optionally: -fciteproc -fhighlighting

This will install the `pandoc` executable into `~/.cabal/bin`.  This method
will not install the wrapper scripts or man pages; if you want those, follow
the instructions above for compiling from source.

Installing the Windows binary
=============================

Simply download the Windows installer [pandoc's google code site]
and run it.  It will install `pandoc.exe` and ensure that it is
in your system 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.

Note that the version of pandoc in Debian may not be the most recent.

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
===============================

There are two `pandoc` packages in the Arch AUR repositories,
`pandoc` (contributed by Abhishek Dasgupta) and `haskell-pandoc`
(contributed by Dons Stewart).  `haskell-pandoc` is more up-to-date,
but does not install the man pages or wrapper scripts.

    pacman -Sy pandoc
    pacman -Sy haskell-pandoc