git.iko.soy/typeable/pandoc
on master help sign in
Added INSTALL.md, incorporating INSTALL + installing page from website.
commitbb20f919c324c549b4c0574a987ddf665692e669 authorJohn MacFarlane <jgm@berkeley.edu> dateTue 25 Oct 2016, 16:36 (10 years ago) parentb4fbe22
4 files changed+342−265
compare with master
unifiedsplit
.gitignore−1 INSTALL−263 INSTALL.md+341 pandoc.cabal+1−1
.gitignore−1
@@ -2,7 +2,6 @@
22dist/*
33MANUAL.*
44!MANUAL.txt
5−INSTALL.*
65.configure-stamp
76.cabal-sandbox
87cabal.sandbox.config
INSTALLdeleted−263
@@ -1,263 +0,0 @@
1−% Installing pandoc
2−
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 are also binary installers for Windows and Mac OS X.
7−
8−If you are installing the development version from github, see also:
9−https://github.com/jgm/pandoc/wiki/Installing-the-development-version-of-pandoc
10−
11−Please note that pandoc only supports [GHC] versions 7.8 and
12−above. The easiest way to get GHC is by installing the [Haskell platform]
13−
14−How to get the source
15−---------------------
16−
17−Source tarballs can be found at
18−<https://hackage.haskell.org/package/pandoc>. The tarball
19−for a particular version `VERSION` can be found at
20−
21− https://hackage.haskell.org/package/pandoc-VERSION/pandoc-VERSION.tar.gz
22−
23−**Do not use the automatically generated tarball that can be
24−downloaded from pandoc's GitHub releases page.** It does not
25−include some essential template files, which come from a GitHub
26−submodule.
27−
28−If you want the latest development code, you can fetch it
29−by cloning the repository:
30−
31− git clone https://github.com/jgm/pandoc
32− cd pandoc
33− git submodule update --init # to fetch the templates
34−
35−Note: there may be times when the development code is broken
36−or depends on other libraries which must be installed
37−separately. Unless you really know what you're doing, install
38−the last released version.
39−
40−Quick install with stack
41−------------------------
42−
43−1. Install [stack](http://docs.haskellstack.org/en/stable/install_and_upgrade.html).
44−
45−2. If you used git to get the pandoc source (as opposed to unpacking
46− a release tarball), do
47−
48− git submodule update --init
49−
50−3. In the pandoc source directory,
51−
52− stack install
53−
54− You may be prompted to run `stack setup`, which will automatically
55− download the ghc compiler if needed.
56−
57−
58−Quick install with cabal
59−------------------------
60−
61−1. Install the [Haskell platform]. This will give you [GHC] and
62− the [cabal-install] build tool.
63−
64−2. Update your package database:
65−
66− cabal update
67−
68−3. Use `cabal` to install pandoc and its dependencies:
69−
70− cabal install pandoc
71−
72− This procedure will install the released version of pandoc,
73− which will be downloaded automatically from HackageDB.
74−
75− If this step fails, and you are using an older version
76− of the Haskell Platform, e.g. on Debian stable, you may need to
77− upgrade your version of cabal:
78−
79− cabal install cabal-install
80− ~/.cabal/bin/cabal update
81− ~/.cabal/bin/cabal install pandoc
82−
83− If you want to install a modified or development version
84− of pandoc instead, switch to the source directory and do
85− as above, but without the 'pandoc':
86−
87− cabal install
88−
89− Note: If you obtained the source from the git repository (rather
90− than a release tarball), you'll need to do
91−
92− git submodule update --init
93−
94− to fetch the contents of `data/templates` before `cabal install`.
95−
96−4. Make sure the `$CABALDIR/bin` directory is in your path. You should
97− now be able to run `pandoc`:
98−
99− pandoc --help
100−
101− [Not sure where `$CABALDIR` is?](http://www.haskell.org/haskellwiki/Cabal-Install#The_cabal-install_configuration_file)
102−
103−5. If you want to process citations with pandoc, you will also need to
104− install a separate package, `pandoc-citeproc`. This can be installed
105− using cabal:
106−
107− cabal install pandoc-citeproc
108−
109− By default `pandoc-citeproc` uses the "i;unicode-casemap" method
110− to sort bibliography entries (RFC 5051). If you would like to
111− use the locale-sensitive unicode collation algorithm instead,
112− specify the `unicode_collation` flag:
113−
114− cabal install pandoc-citeproc -funicode_collation
115−
116− Note that this requires the `text-icu` library, which in turn
117− depends on the C library `icu4c`. Installation directions
118− vary by platform. Here is how it might work on OSX with homebrew:
119−
120− brew install icu4c
121− cabal install --extra-lib-dirs=/usr/local/Cellar/icu4c/51.1/lib \
122− --extra-include-dirs=/usr/local/Cellar/icu4c/51.1/include \
123− -funicode_collation text-icu pandoc-citeproc
124−
125−The `pandoc.1` man page will be installed automatically. cabal shows
126−you where it is installed: you may need to set your `MANPATH`
127−accordingly. If `MANUAL.txt` has been modified, the man page can be
128−rebuilt: `make man/pandoc.1`.
129−
130−The `pandoc-citeproc.1` man page will also be installed automatically.
131−
132−[GHC]: http://www.haskell.org/ghc/
133−[Haskell platform]: http://hackage.haskell.org/platform/
134−[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
135−
136−Custom install
137−--------------
138−
139−This is a step-by-step procedure that offers maximal control
140−over the build and installation. Most users should use the
141−quick install, but this information may be of use to packagers.
142−For more details, see the [Cabal User's Guide]. These instructions
143−assume that the pandoc source directory is your working directory.
144−
145−1. Install dependencies: in addition to the [Haskell platform],
146− you will need a number of additional libraries. You can install
147− them all with
148−
149− cabal update
150− cabal install --only-dependencies
151−
152−2. Configure:
153−
154− cabal configure --prefix=DIR --bindir=DIR --libdir=DIR \
155− --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \
156− --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \
157− --mandir=DIR --flags=FLAGSPEC
158−
159− All of the options have sensible defaults that can be overridden
160− as needed.
161−
162− `FLAGSPEC` is a list of Cabal configuration flags, optionally
163− preceded by a `-` (to force the flag to `false`), and separated
164− by spaces. Pandoc's flags include:
165−
166− - `embed_data_files`: embed all data files into the binary (default no).
167− This is helpful if you want to create a relocatable binary.
168− Note: if this option is selected, you need to install the
169− `hsb2hs` preprocessor: `cabal install hsb2hs` (version 0.3.1 or
170− higher is required).
171−
172− - `https`: enable support for downloading resources over https
173− (using the `http-client` and `http-client-tls` libraries).
174−
175−3. Build:
176−
177− cabal build
178−
179−4. Build API documentation:
180−
181− cabal haddock --html-location=URL --hyperlink-source
182−
183−5. Copy the files:
184−
185− cabal copy --destdir=PATH
186−
187− The default destdir is `/`.
188−
189−6. Register pandoc as a GHC package:
190−
191− cabal register
192−
193− Package managers may want to use the `--gen-script` option to
194− generate a script that can be run to register the package at
195− install time.
196−
197−Creating a relocatable binary
198−-----------------------------
199−
200−It is possible to compile pandoc such that the data files
201−pandoc uses are embedded in the binary. The resulting binary
202−can be run from any directory and is completely self-contained.
203−
204− cabal install hsb2hs # a required build tool
205− cabal install --flags="embed_data_files" citeproc-hs
206− cabal configure --flags="embed_data_files"
207− cabal build
208−
209−You can find the pandoc executable in `dist/build/pandoc`. Copy this wherever
210−you please.
211−
212−Or alternatively with `stack`:
213−
214− stack install pandoc --flag pandoc:embed_data_files
215−
216−[zip-archive]: http://hackage.haskell.org/package/zip-archive
217−[highlighting-kate]: http://hackage.haskell.org/package/highlighting-kate
218−[blaze-html]: http://hackage.haskell.org/package/blaze-html
219−[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
220−
221−Running tests
222−-------------
223−
224−Pandoc comes with an automated test suite integrated to cabal.
225−To build the tests:
226−
227− cabal configure --enable-tests && cabal build
228−
229−To run the tests:
230−
231− cabal test
232−
233−To run particular tests (pattern-matching on their names), use
234−the `-t` option:
235−
236− cabal test --test-options='-t markdown'
237−
238−If you add a new feature to pandoc, please add tests as well, following
239−the pattern of the existing tests. The test suite code is in
240−`tests/test-pandoc.hs`. If you are adding a new reader or writer, it is
241−probably easiest to add some data files to the `tests` directory, and
242−modify `tests/Tests/Old.hs`. Otherwise, it is better to modify the module
243−under the `tests/Tests` hierarchy corresponding to the pandoc module you
244−are changing.
245−
246−Running benchmarks
247−------------------
248−
249−To build the benchmarks:
250−
251− cabal configure --enable-benchmarks && cabal build
252−
253−To run the benchmarks:
254−
255− cabal bench
256−
257−To use a smaller sample size so the benchmarks run faster:
258−
259− cabal bench --benchmark-options='-s 20'
260−
261−To run just the markdown benchmarks:
262−
263− cabal bench --benchmark-options='markdown'
INSTALL.mdnew file+341
@@ -0,0 +1,341 @@
1+# Installing pandoc
2+
3+## Windows
4+
5+ - There is a package installer at pandoc's [download page].
6+
7+ - For PDF output, you'll also need to install LaTeX.
8+ We recommend [MiKTeX](http://miktex.org/).
9+
10+## Mac OS X
11+
12+ - There is a package installer at pandoc's [download page].
13+ If you later want to uninstall the package, you can do so
14+ by downloading [this script][uninstaller]
15+ and running it with `perl uninstall-pandoc.pl`.
16+
17+ - You can also install pandoc using
18+ [homebrew](http://brew.sh): `brew install pandoc`.
19+
20+ - For PDF output, you'll also need LaTeX. Because a full [MacTeX]
21+ installation takes more than a gigabyte of disk space, we recommend
22+ installing [BasicTeX](http://www.tug.org/mactex/morepackages.html)
23+ (64M) and using the `tlmgr` tool to install additional packages
24+ as needed. If you get errors warning of fonts not found, try
25+
26+ tlmgr install collection-fontsrecommended
27+
28+## Linux
29+
30+ - First, try your package manager.
31+ Pandoc is in the [Debian], [Ubuntu], [Slackware],
32+ [Arch], [Fedora], [NiXOS], [openSUSE], and [gentoo] repositories.
33+ Note, however, that versions in the repositories are often
34+ old.
35+
36+ - For 64-bit [Debian] and [Ubuntu], we provide a debian package
37+ on the [download page].
38+
39+ sudo dpkg -i $DEB
40+
41+ where `$DEB` is the path to the downloaded deb, will
42+ will install the `pandoc` and `pandoc-citeproc` executables
43+ and man pages. If you use an RPM-based distro, you may be
44+ able to install this deb using `alien`, or try
45+
46+ ar p $DEB data.tar.gz | sudo tar xvz --strip-components 2 -C /usr/local
47+
48+ - If you'd rather install pandoc in your home directory, say
49+ in `$HOME/.local`, then you can extract the files manually
50+ from the deb:
51+
52+ ar p $DEB data.tar.gz | tar xvz --strip-components 2 -C $HOME/.local/
53+
54+ where, again, `$DEB` is the path to the downloaded deb.
55+
56+ - If the version in your repository is too old and you cannot
57+ use the deb we provide, you can install from source, using the
58+ instructions below under [Installing from source].
59+ Note that most distros have the Haskell platform in their
60+ package repositories. For example, on Debian/Ubuntu,
61+ you can install it with `apt-get install haskell-platform`.
62+
63+ - For PDF output, you'll need LaTeX. We recommend installing
64+ [TeX Live](http://www.tug.org/texlive/) via your package
65+ manager. (On Debian/Ubuntu, `apt-get install texlive`.)
66+
67+## BSD
68+
69+ - Pandoc is in the [NetBSD] and [FreeBSD ports] repositories.
70+
71+## Compiling from source
72+
73+If for some reason a binary package is not available for your
74+platform, or if you want to hack on pandoc or use a non-released
75+version, you can install from source.
76+
77+### Getting the pandoc source code
78+
79+Source tarballs can be found at
80+<https://hackage.haskell.org/package/pandoc>. For example, to
81+fetch the source for version 1.17.0.3:
82+
83+ wget https://hackage.haskell.org/package/pandoc-1.17.0.3/pandoc-1.17.0.3.tar.gz
84+ tar xvzf pandoc-1.17.0.3.tar.gz
85+ cd pandoc-1.17.0.3
86+
87+Or you can fetch the development code by cloning the repository:
88+
89+ git clone https://github.com/jgm/pandoc
90+ cd pandoc
91+ git submodule update --init # to fetch the templates
92+
93+Note: there may be times when the development code is broken
94+or depends on other libraries which must be installed
95+separately. Unless you really know what you're doing, install
96+the last released version.
97+
98+### Quick stack method
99+
100+The easiest way to build pandoc from source is to use [stack]:
101+
102+1. Install [stack].
103+
104+2. Change to the pandoc source directory and issue the following commands:
105+
106+ stack setup
107+ stack install --test
108+
109+ `stack setup` will automatically download the ghc compiler
110+ if you don't have it. `stack install` will install the
111+ `pandoc` executable into `~/.local/bin`, which you should
112+ add to your `PATH`. This process will take a while, and
113+ will consume a considerable amount of disk space.
114+
115+### Quick cabal method
116+
117+1. Install the [Haskell platform]. This will give you [GHC] and
118+ the [cabal-install] build tool. Note that pandoc requires
119+ GHC >= 7.8.
120+
121+2. Update your package database:
122+
123+ cabal update
124+
125+3. Use `cabal` to install pandoc and its dependencies:
126+
127+ cabal install pandoc --enable-tests
128+
129+ This procedure will install the released version of pandoc,
130+ which will be downloaded automatically from HackageDB.
131+
132+ If you want to install a modified or development version
133+ of pandoc instead, switch to the source directory and do
134+ as above, but without the 'pandoc':
135+
136+ cabal install
137+
138+ Note: If you obtained the source from the git repository (rather
139+ than a release tarball), you'll need to do
140+
141+ git submodule update --init
142+
143+ to fetch the contents of `data/templates` before `cabal install`.
144+
145+4. Make sure the `$CABALDIR/bin` directory is in your path. You should
146+ now be able to run `pandoc`:
147+
148+ pandoc --help
149+
150+ [Not sure where `$CABALDIR` is?](http://www.haskell.org/haskellwiki/Cabal-Install#The_cabal-install_configuration_file)
151+
152+5. If you want to process citations with pandoc, you will also need to
153+ install a separate package, `pandoc-citeproc`. This can be installed
154+ using cabal:
155+
156+ cabal install pandoc-citeproc
157+
158+ By default `pandoc-citeproc` uses the "i;unicode-casemap" method
159+ to sort bibliography entries (RFC 5051). If you would like to
160+ use the locale-sensitive unicode collation algorithm instead,
161+ specify the `unicode_collation` flag:
162+
163+ cabal install pandoc-citeproc -funicode_collation
164+
165+ Note that this requires the `text-icu` library, which in turn
166+ depends on the C library `icu4c`. Installation directions
167+ vary by platform. Here is how it might work on OSX with homebrew:
168+
169+ brew install icu4c
170+ cabal install --extra-lib-dirs=/usr/local/Cellar/icu4c/51.1/lib \
171+ --extra-include-dirs=/usr/local/Cellar/icu4c/51.1/include \
172+ -funicode_collation text-icu pandoc-citeproc
173+
174+6. The `pandoc.1` man page will be installed automatically. cabal shows
175+ you where it is installed: you may need to set your `MANPATH`
176+ accordingly. If `MANUAL.txt` has been modified, the man page can be
177+ rebuilt: `make man/pandoc.1`.
178+
179+ The `pandoc-citeproc.1` man page will also be installed automatically.
180+
181+[GHC]: http://www.haskell.org/ghc/
182+[Haskell platform]: http://hackage.haskell.org/platform/
183+[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
184+
185+### Custom cabal method
186+
187+This is a step-by-step procedure that offers maximal control
188+over the build and installation. Most users should use the
189+quick install, but this information may be of use to packagers.
190+For more details, see the [Cabal User's Guide]. These instructions
191+assume that the pandoc source directory is your working directory.
192+
193+1. Install dependencies: in addition to the [Haskell platform],
194+ you will need a number of additional libraries. You can install
195+ them all with
196+
197+ cabal update
198+ cabal install --only-dependencies
199+
200+2. Configure:
201+
202+ cabal configure --prefix=DIR --bindir=DIR --libdir=DIR \
203+ --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \
204+ --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \
205+ --mandir=DIR --flags=FLAGSPEC --enable-tests
206+
207+ All of the options have sensible defaults that can be overridden
208+ as needed.
209+
210+ `FLAGSPEC` is a list of Cabal configuration flags, optionally
211+ preceded by a `-` (to force the flag to `false`), and separated
212+ by spaces. Pandoc's flags include:
213+
214+ - `embed_data_files`: embed all data files into the binary (default no).
215+ This is helpful if you want to create a relocatable binary.
216+ Note: if this option is selected, you need to install the
217+ `hsb2hs` preprocessor: `cabal install hsb2hs` (version 0.3.1 or
218+ higher is required).
219+
220+ - `https`: enable support for downloading resources over https
221+ (using the `http-client` and `http-client-tls` libraries).
222+
223+3. Build:
224+
225+ cabal build
226+ cabal test
227+
228+4. Build API documentation:
229+
230+ cabal haddock --html-location=URL --hyperlink-source
231+
232+5. Copy the files:
233+
234+ cabal copy --destdir=PATH
235+
236+ The default destdir is `/`.
237+
238+6. Register pandoc as a GHC package:
239+
240+ cabal register
241+
242+ Package managers may want to use the `--gen-script` option to
243+ generate a script that can be run to register the package at
244+ install time.
245+
246+### Creating a relocatable binary
247+
248+It is possible to compile pandoc such that the data files
249+pandoc uses are embedded in the binary. The resulting binary
250+can be run from any directory and is completely self-contained.
251+With cabal, add `-fembed_data_files` to the `cabal configure`
252+or `cabal install` commands.
253+
254+With stack, use `--flag pandoc:embed_data_files`.
255+
256+
257+
258+### Running tests
259+
260+Pandoc comes with an automated test suite.
261+To run with cabal, `cabal test`; to run with stack, `stack
262+test`.
263+
264+To run particular tests (pattern-matching on their names), use
265+the `-t` option:
266+
267+ cabal test --test-options='-t markdown'
268+
269+If you add a new feature to pandoc, please add tests as well, following
270+the pattern of the existing tests. The test suite code is in
271+`tests/test-pandoc.hs`. If you are adding a new reader or writer, it is
272+probably easiest to add some data files to the `tests` directory, and
273+modify `tests/Tests/Old.hs`. Otherwise, it is better to modify the module
274+under the `tests/Tests` hierarchy corresponding to the pandoc module you
275+are changing.
276+
277+### Running benchmarks
278+
279+To build and run the benchmarks:
280+
281+ cabal configure --enable-benchmarks && cabal build
282+ cabal bench
283+
284+or with stack:
285+
286+ stack bench
287+
288+To use a smaller sample size so the benchmarks run faster:
289+
290+ cabal bench --benchmark-options='-s 20'
291+
292+To run just the markdown benchmarks:
293+
294+ cabal bench --benchmark-options='markdown'
295+
296+### Building the whole pandoc ecosystem
297+
298+Sometimes pandoc's development code depends on unreleased versions
299+of dependent libraries. You'll need to build these as well. A
300+maximal build method would be
301+
302+ mkdir pandoc-build
303+ cd pandoc-build
304+ git clone https://github.com/jgm/pandoc-types
305+ git clone https://github.com/jgm/texmath
306+ git clone https://github.com/jgm/pandoc-citeproc
307+ git clone https://github.com/jgm/pandoc
308+ git clone https://github.com/jgm/cmark-hs
309+ git clone https://github.com/jgm/zip-archive
310+ cd pandoc
311+ git submodule update --init
312+ stack install --test --install-ghc --stack-yaml stack.full.yaml
313+
314+To pull in the latest changes, after you've done this and there have been
315+changes in the repositories: Visit each repository in pandoc-build
316+(pandoc-types, texmath, pandoc-citeproc, pandoc, zip-archive, cmark-hs) and do
317+`git pull`. In the pandoc repo, also do `git submodule update` and `stack
318+install --test --stack-yaml stack.full.yaml`.
319+
320+
321+[Arch]: https://www.archlinux.org/packages/community/x86_64/pandoc/
322+[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
323+[Debian]: http://packages.debian.org/lenny/pandoc
324+[Fedora]: https://apps.fedoraproject.org/packages/pandoc
325+[FreeBSD ports]: http://www.freshports.org/textproc/pandoc/
326+[GHC]: http://www.haskell.org/ghc/
327+[GPL]: http://www.gnu.org/copyleft/gpl.html
328+[Haskell platform]: http://hackage.haskell.org/platform/
329+[MacPorts]: http://trac.macports.org/browser/trunk/dports/textproc/pandoc/Portfile
330+[MacTeX]: https://tug.org/mactex/
331+[NetBSD]: http://pkgsrc.se/wip/pandoc
332+[NixOS]: http://nixos.org/nixos/
333+[Slackware]: http://www.linuxpackages.net/search_view.php?by=name&name=pandoc&ver=
334+[Ubuntu]: http://www.ubuntu.com
335+[download page]: https://github.com/jgm/pandoc/releases/latest
336+[gentoo]: http://packages.gentoo.org/package/app-text/pandoc
337+[haskell repository]: https://wiki.archlinux.org/index.php/Haskell_Package_Guidelines#.5Bhaskell.5D
338+[openSUSE]: https://software.opensuse.org/package/pandoc
339+[source tarball]: http://hackage.haskell.org/package/pandoc
340+[stack]: http://docs.haskellstack.org/en/stable/install_and_upgrade.html
341+[uninstaller]: https://raw.githubusercontent.com/jgm/pandoc/master/osx/uninstall-pandoc.pl
pandoc.cabal+1−1
@@ -108,7 +108,7 @@ Data-Files:
108108 MANUAL.txt, COPYRIGHT
109109Extra-Source-Files:
110110 -- documentation
111− INSTALL, BUGS, README.md, CONTRIBUTING.md, changelog
111+ INSTALL.md, BUGS, README.md, CONTRIBUTING.md, changelog
112112 man/pandoc.1
113113 -- stack build plan
114114 stack.yaml