diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | INSTALL | 263 | ||||
| -rw-r--r-- | INSTALL.md | 341 | ||||
| -rw-r--r-- | pandoc.cabal | 2 |
4 files changed, 342 insertions, 265 deletions
diff --git a/.gitignore b/.gitignore index 0e2686c83..26be741eb 100644 --- a/.gitignore +++ b/.gitignore @@ -2,7 +2,6 @@ dist/* MANUAL.* !MANUAL.txt -INSTALL.* .configure-stamp .cabal-sandbox cabal.sandbox.config diff --git a/INSTALL b/INSTALL deleted file mode 100644 index 9a582784d..000000000 --- a/INSTALL +++ /dev/null @@ -1,263 +0,0 @@ -% Installing pandoc - -These instructions explain how to install pandoc from source. -Binary packages or ports of pandoc are available for freebsd -and several linux distributions, so check your package manager. -There are also binary installers for Windows and Mac OS X. - -If you are installing the development version from github, see also: -https://github.com/jgm/pandoc/wiki/Installing-the-development-version-of-pandoc - -Please note that pandoc only supports [GHC] versions 7.8 and -above. The easiest way to get GHC is by installing the [Haskell platform] - -How to get the source ---------------------- - -Source tarballs can be found at -<https://hackage.haskell.org/package/pandoc>. The tarball -for a particular version `VERSION` can be found at - - https://hackage.haskell.org/package/pandoc-VERSION/pandoc-VERSION.tar.gz - -**Do not use the automatically generated tarball that can be -downloaded from pandoc's GitHub releases page.** It does not -include some essential template files, which come from a GitHub -submodule. - -If you want the latest development code, you can fetch it -by cloning the repository: - - git clone https://github.com/jgm/pandoc - cd pandoc - git submodule update --init # to fetch the templates - -Note: there may be times when the development code is broken -or depends on other libraries which must be installed -separately. Unless you really know what you're doing, install -the last released version. - -Quick install with stack ------------------------- - -1. Install [stack](http://docs.haskellstack.org/en/stable/install_and_upgrade.html). - -2. If you used git to get the pandoc source (as opposed to unpacking - a release tarball), do - - git submodule update --init - -3. In the pandoc source directory, - - stack install - - You may be prompted to run `stack setup`, which will automatically - download the ghc compiler if needed. - - -Quick install with cabal ------------------------- - -1. Install the [Haskell platform]. This will give you [GHC] and - the [cabal-install] build tool. - -2. Update your package database: - - cabal update - -3. Use `cabal` to install pandoc and its dependencies: - - cabal install pandoc - - This procedure will install the released version of pandoc, - which will be downloaded automatically from HackageDB. - - If this step fails, and you are using an older version - of the Haskell Platform, e.g. on Debian stable, you may need to - upgrade your version of cabal: - - cabal install cabal-install - ~/.cabal/bin/cabal update - ~/.cabal/bin/cabal install pandoc - - If you want to install a modified or development version - of pandoc instead, switch to the source directory and do - as above, but without the 'pandoc': - - cabal install - - Note: If you obtained the source from the git repository (rather - than a release tarball), you'll need to do - - git submodule update --init - - to fetch the contents of `data/templates` before `cabal install`. - -4. Make sure the `$CABALDIR/bin` directory is in your path. You should - now be able to run `pandoc`: - - pandoc --help - - [Not sure where `$CABALDIR` is?](http://www.haskell.org/haskellwiki/Cabal-Install#The_cabal-install_configuration_file) - -5. If you want to process citations with pandoc, you will also need to - install a separate package, `pandoc-citeproc`. This can be installed - using cabal: - - cabal install pandoc-citeproc - - By default `pandoc-citeproc` uses the "i;unicode-casemap" method - to sort bibliography entries (RFC 5051). If you would like to - use the locale-sensitive unicode collation algorithm instead, - specify the `unicode_collation` flag: - - cabal install pandoc-citeproc -funicode_collation - - Note that this requires the `text-icu` library, which in turn - depends on the C library `icu4c`. Installation directions - vary by platform. Here is how it might work on OSX with homebrew: - - brew install icu4c - cabal install --extra-lib-dirs=/usr/local/Cellar/icu4c/51.1/lib \ - --extra-include-dirs=/usr/local/Cellar/icu4c/51.1/include \ - -funicode_collation text-icu pandoc-citeproc - -The `pandoc.1` man page will be installed automatically. cabal shows -you where it is installed: you may need to set your `MANPATH` -accordingly. If `MANUAL.txt` has been modified, the man page can be -rebuilt: `make man/pandoc.1`. - -The `pandoc-citeproc.1` man page will also be installed automatically. - -[GHC]: http://www.haskell.org/ghc/ -[Haskell platform]: http://hackage.haskell.org/platform/ -[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall - -Custom install --------------- - -This is a step-by-step procedure that offers maximal control -over the build and installation. Most users should use the -quick install, but this information may be of use to packagers. -For more details, see the [Cabal User's Guide]. These instructions -assume that the pandoc source directory is your working directory. - -1. Install dependencies: in addition to the [Haskell platform], - you will need a number of additional libraries. You can install - them all with - - cabal update - cabal install --only-dependencies - -2. Configure: - - cabal configure --prefix=DIR --bindir=DIR --libdir=DIR \ - --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \ - --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \ - --mandir=DIR --flags=FLAGSPEC - - All of the options have sensible defaults that can be overridden - as needed. - - `FLAGSPEC` is a list of Cabal configuration flags, optionally - preceded by a `-` (to force the flag to `false`), and separated - by spaces. Pandoc's flags include: - - - `embed_data_files`: embed all data files into the binary (default no). - This is helpful if you want to create a relocatable binary. - Note: if this option is selected, you need to install the - `hsb2hs` preprocessor: `cabal install hsb2hs` (version 0.3.1 or - higher is required). - - - `https`: enable support for downloading resources over https - (using the `http-client` and `http-client-tls` libraries). - -3. Build: - - cabal build - -4. Build API documentation: - - cabal haddock --html-location=URL --hyperlink-source - -5. Copy the files: - - cabal copy --destdir=PATH - - The default destdir is `/`. - -6. Register pandoc as a GHC package: - - cabal register - - Package managers may want to use the `--gen-script` option to - generate a script that can be run to register the package at - install time. - -Creating a relocatable binary ------------------------------ - -It is possible to compile pandoc such that the data files -pandoc uses are embedded in the binary. The resulting binary -can be run from any directory and is completely self-contained. - - cabal install hsb2hs # a required build tool - cabal install --flags="embed_data_files" citeproc-hs - cabal configure --flags="embed_data_files" - cabal build - -You can find the pandoc executable in `dist/build/pandoc`. Copy this wherever -you please. - -Or alternatively with `stack`: - - stack install pandoc --flag pandoc:embed_data_files - -[zip-archive]: http://hackage.haskell.org/package/zip-archive -[highlighting-kate]: http://hackage.haskell.org/package/highlighting-kate -[blaze-html]: http://hackage.haskell.org/package/blaze-html -[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths - -Running tests -------------- - -Pandoc comes with an automated test suite integrated to cabal. -To build the tests: - - cabal configure --enable-tests && cabal build - -To run the tests: - - cabal test - -To run particular tests (pattern-matching on their names), use -the `-t` option: - - cabal test --test-options='-t markdown' - -If you add a new feature to pandoc, please add tests as well, following -the pattern of the existing tests. The test suite code is in -`tests/test-pandoc.hs`. If you are adding a new reader or writer, it is -probably easiest to add some data files to the `tests` directory, and -modify `tests/Tests/Old.hs`. Otherwise, it is better to modify the module -under the `tests/Tests` hierarchy corresponding to the pandoc module you -are changing. - -Running benchmarks ------------------- - -To build the benchmarks: - - cabal configure --enable-benchmarks && cabal build - -To run the benchmarks: - - cabal bench - -To use a smaller sample size so the benchmarks run faster: - - cabal bench --benchmark-options='-s 20' - -To run just the markdown benchmarks: - - cabal bench --benchmark-options='markdown' diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 000000000..d3a853f4c --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,341 @@ +# Installing pandoc + +## Windows + + - There is a package installer at pandoc's [download page]. + + - For PDF output, you'll also need to install LaTeX. + We recommend [MiKTeX](http://miktex.org/). + +## Mac OS X + + - There is a package installer at pandoc's [download page]. + If you later want to uninstall the package, you can do so + by downloading [this script][uninstaller] + and running it with `perl uninstall-pandoc.pl`. + + - You can also install pandoc using + [homebrew](http://brew.sh): `brew install pandoc`. + + - For PDF output, you'll also need LaTeX. Because a full [MacTeX] + installation takes more than a gigabyte of disk space, we recommend + installing [BasicTeX](http://www.tug.org/mactex/morepackages.html) + (64M) and using the `tlmgr` tool to install additional packages + as needed. If you get errors warning of fonts not found, try + + tlmgr install collection-fontsrecommended + +## Linux + + - First, try your package manager. + Pandoc is in the [Debian], [Ubuntu], [Slackware], + [Arch], [Fedora], [NiXOS], [openSUSE], and [gentoo] repositories. + Note, however, that versions in the repositories are often + old. + + - For 64-bit [Debian] and [Ubuntu], we provide a debian package + on the [download page]. + + sudo dpkg -i $DEB + + where `$DEB` is the path to the downloaded deb, will + will install the `pandoc` and `pandoc-citeproc` executables + and man pages. If you use an RPM-based distro, you may be + able to install this deb using `alien`, or try + + ar p $DEB data.tar.gz | sudo tar xvz --strip-components 2 -C /usr/local + + - If you'd rather install pandoc in your home directory, say + in `$HOME/.local`, then you can extract the files manually + from the deb: + + ar p $DEB data.tar.gz | tar xvz --strip-components 2 -C $HOME/.local/ + + where, again, `$DEB` is the path to the downloaded deb. + + - If the version in your repository is too old and you cannot + use the deb we provide, you can install from source, using the + instructions below under [Installing from source]. + Note that most distros have the Haskell platform in their + package repositories. For example, on Debian/Ubuntu, + you can install it with `apt-get install haskell-platform`. + + - For PDF output, you'll need LaTeX. We recommend installing + [TeX Live](http://www.tug.org/texlive/) via your package + manager. (On Debian/Ubuntu, `apt-get install texlive`.) + +## BSD + + - Pandoc is in the [NetBSD] and [FreeBSD ports] repositories. + +## Compiling from source + +If for some reason a binary package is not available for your +platform, or if you want to hack on pandoc or use a non-released +version, you can install from source. + +### Getting the pandoc source code + +Source tarballs can be found at +<https://hackage.haskell.org/package/pandoc>. For example, to +fetch the source for version 1.17.0.3: + + wget https://hackage.haskell.org/package/pandoc-1.17.0.3/pandoc-1.17.0.3.tar.gz + tar xvzf pandoc-1.17.0.3.tar.gz + cd pandoc-1.17.0.3 + +Or you can fetch the development code by cloning the repository: + + git clone https://github.com/jgm/pandoc + cd pandoc + git submodule update --init # to fetch the templates + +Note: there may be times when the development code is broken +or depends on other libraries which must be installed +separately. Unless you really know what you're doing, install +the last released version. + +### Quick stack method + +The easiest way to build pandoc from source is to use [stack]: + +1. Install [stack]. + +2. Change to the pandoc source directory and issue the following commands: + + stack setup + stack install --test + + `stack setup` will automatically download the ghc compiler + if you don't have it. `stack install` will install the + `pandoc` executable into `~/.local/bin`, which you should + add to your `PATH`. This process will take a while, and + will consume a considerable amount of disk space. + +### Quick cabal method + +1. Install the [Haskell platform]. This will give you [GHC] and + the [cabal-install] build tool. Note that pandoc requires + GHC >= 7.8. + +2. Update your package database: + + cabal update + +3. Use `cabal` to install pandoc and its dependencies: + + cabal install pandoc --enable-tests + + This procedure will install the released version of pandoc, + which will be downloaded automatically from HackageDB. + + If you want to install a modified or development version + of pandoc instead, switch to the source directory and do + as above, but without the 'pandoc': + + cabal install + + Note: If you obtained the source from the git repository (rather + than a release tarball), you'll need to do + + git submodule update --init + + to fetch the contents of `data/templates` before `cabal install`. + +4. Make sure the `$CABALDIR/bin` directory is in your path. You should + now be able to run `pandoc`: + + pandoc --help + + [Not sure where `$CABALDIR` is?](http://www.haskell.org/haskellwiki/Cabal-Install#The_cabal-install_configuration_file) + +5. If you want to process citations with pandoc, you will also need to + install a separate package, `pandoc-citeproc`. This can be installed + using cabal: + + cabal install pandoc-citeproc + + By default `pandoc-citeproc` uses the "i;unicode-casemap" method + to sort bibliography entries (RFC 5051). If you would like to + use the locale-sensitive unicode collation algorithm instead, + specify the `unicode_collation` flag: + + cabal install pandoc-citeproc -funicode_collation + + Note that this requires the `text-icu` library, which in turn + depends on the C library `icu4c`. Installation directions + vary by platform. Here is how it might work on OSX with homebrew: + + brew install icu4c + cabal install --extra-lib-dirs=/usr/local/Cellar/icu4c/51.1/lib \ + --extra-include-dirs=/usr/local/Cellar/icu4c/51.1/include \ + -funicode_collation text-icu pandoc-citeproc + +6. The `pandoc.1` man page will be installed automatically. cabal shows + you where it is installed: you may need to set your `MANPATH` + accordingly. If `MANUAL.txt` has been modified, the man page can be + rebuilt: `make man/pandoc.1`. + + The `pandoc-citeproc.1` man page will also be installed automatically. + +[GHC]: http://www.haskell.org/ghc/ +[Haskell platform]: http://hackage.haskell.org/platform/ +[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall + +### Custom cabal method + +This is a step-by-step procedure that offers maximal control +over the build and installation. Most users should use the +quick install, but this information may be of use to packagers. +For more details, see the [Cabal User's Guide]. These instructions +assume that the pandoc source directory is your working directory. + +1. Install dependencies: in addition to the [Haskell platform], + you will need a number of additional libraries. You can install + them all with + + cabal update + cabal install --only-dependencies + +2. Configure: + + cabal configure --prefix=DIR --bindir=DIR --libdir=DIR \ + --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \ + --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \ + --mandir=DIR --flags=FLAGSPEC --enable-tests + + All of the options have sensible defaults that can be overridden + as needed. + + `FLAGSPEC` is a list of Cabal configuration flags, optionally + preceded by a `-` (to force the flag to `false`), and separated + by spaces. Pandoc's flags include: + + - `embed_data_files`: embed all data files into the binary (default no). + This is helpful if you want to create a relocatable binary. + Note: if this option is selected, you need to install the + `hsb2hs` preprocessor: `cabal install hsb2hs` (version 0.3.1 or + higher is required). + + - `https`: enable support for downloading resources over https + (using the `http-client` and `http-client-tls` libraries). + +3. Build: + + cabal build + cabal test + +4. Build API documentation: + + cabal haddock --html-location=URL --hyperlink-source + +5. Copy the files: + + cabal copy --destdir=PATH + + The default destdir is `/`. + +6. Register pandoc as a GHC package: + + cabal register + + Package managers may want to use the `--gen-script` option to + generate a script that can be run to register the package at + install time. + +### Creating a relocatable binary + +It is possible to compile pandoc such that the data files +pandoc uses are embedded in the binary. The resulting binary +can be run from any directory and is completely self-contained. +With cabal, add `-fembed_data_files` to the `cabal configure` +or `cabal install` commands. + +With stack, use `--flag pandoc:embed_data_files`. + + + +### Running tests + +Pandoc comes with an automated test suite. +To run with cabal, `cabal test`; to run with stack, `stack +test`. + +To run particular tests (pattern-matching on their names), use +the `-t` option: + + cabal test --test-options='-t markdown' + +If you add a new feature to pandoc, please add tests as well, following +the pattern of the existing tests. The test suite code is in +`tests/test-pandoc.hs`. If you are adding a new reader or writer, it is +probably easiest to add some data files to the `tests` directory, and +modify `tests/Tests/Old.hs`. Otherwise, it is better to modify the module +under the `tests/Tests` hierarchy corresponding to the pandoc module you +are changing. + +### Running benchmarks + +To build and run the benchmarks: + + cabal configure --enable-benchmarks && cabal build + cabal bench + +or with stack: + + stack bench + +To use a smaller sample size so the benchmarks run faster: + + cabal bench --benchmark-options='-s 20' + +To run just the markdown benchmarks: + + cabal bench --benchmark-options='markdown' + +### Building the whole pandoc ecosystem + +Sometimes pandoc's development code depends on unreleased versions +of dependent libraries. You'll need to build these as well. A +maximal build method would be + + mkdir pandoc-build + cd pandoc-build + git clone https://github.com/jgm/pandoc-types + git clone https://github.com/jgm/texmath + git clone https://github.com/jgm/pandoc-citeproc + git clone https://github.com/jgm/pandoc + git clone https://github.com/jgm/cmark-hs + git clone https://github.com/jgm/zip-archive + cd pandoc + git submodule update --init + stack install --test --install-ghc --stack-yaml stack.full.yaml + +To pull in the latest changes, after you've done this and there have been +changes in the repositories: Visit each repository in pandoc-build +(pandoc-types, texmath, pandoc-citeproc, pandoc, zip-archive, cmark-hs) and do +`git pull`. In the pandoc repo, also do `git submodule update` and `stack +install --test --stack-yaml stack.full.yaml`. + + +[Arch]: https://www.archlinux.org/packages/community/x86_64/pandoc/ +[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths +[Debian]: http://packages.debian.org/lenny/pandoc +[Fedora]: https://apps.fedoraproject.org/packages/pandoc +[FreeBSD ports]: http://www.freshports.org/textproc/pandoc/ +[GHC]: http://www.haskell.org/ghc/ +[GPL]: http://www.gnu.org/copyleft/gpl.html +[Haskell platform]: http://hackage.haskell.org/platform/ +[MacPorts]: http://trac.macports.org/browser/trunk/dports/textproc/pandoc/Portfile +[MacTeX]: https://tug.org/mactex/ +[NetBSD]: http://pkgsrc.se/wip/pandoc +[NixOS]: http://nixos.org/nixos/ +[Slackware]: http://www.linuxpackages.net/search_view.php?by=name&name=pandoc&ver= +[Ubuntu]: http://www.ubuntu.com +[download page]: https://github.com/jgm/pandoc/releases/latest +[gentoo]: http://packages.gentoo.org/package/app-text/pandoc +[haskell repository]: https://wiki.archlinux.org/index.php/Haskell_Package_Guidelines#.5Bhaskell.5D +[openSUSE]: https://software.opensuse.org/package/pandoc +[source tarball]: http://hackage.haskell.org/package/pandoc +[stack]: http://docs.haskellstack.org/en/stable/install_and_upgrade.html +[uninstaller]: https://raw.githubusercontent.com/jgm/pandoc/master/osx/uninstall-pandoc.pl diff --git a/pandoc.cabal b/pandoc.cabal index da9d005ef..d830de133 100644 --- a/pandoc.cabal +++ b/pandoc.cabal @@ -108,7 +108,7 @@ Data-Files: MANUAL.txt, COPYRIGHT Extra-Source-Files: -- documentation - INSTALL, BUGS, README.md, CONTRIBUTING.md, changelog + INSTALL.md, BUGS, README.md, CONTRIBUTING.md, changelog man/pandoc.1 -- stack build plan stack.yaml |