Improved INSTALL instructions.

1 files changed, 43 insertions, 23 deletions

diff --git a/INSTALL b/INSTALL
index 8abb14b71..8bcea83c2 100644
--- a/INSTALL
+++ b/INSTALL
@@ -9,9 +9,17 @@ Quick install
 -------------
 
 1.  Install the [Haskell platform].  This will give you [GHC] and
-the [cabal-install] build tool.
+    the [cabal-install] build tool, as well as `alex` and `happy`.
+    If you do not use the Haskell platform, you'll need to install
+    `alex` and `happy` separately:
 
-2.  Use `cabal` to install pandoc and its dependencies:
+        cabal install alex happy
+
+2.  Update your package database:
+
+        cabal update
+
+3.  Use `cabal` to install pandoc and its dependencies:
 
         cabal install pandoc
 
@@ -23,15 +31,22 @@ the [cabal-install] build tool.
 
         cabal install
 
-3.  Make sure the `$CABALDIR/bin` directory is in your path.  You should
-now be able to run `pandoc`:
+    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)
 
-4.  Make sure the `$CABALDIR/share/man/man1` directory is in your `MANPATH`.
-You should now be able to access the `pandoc` man page:
+5.  Make sure the `$CABALDIR/share/man/man1` directory is in your `MANPATH`.
+    You should now be able to access the `pandoc` man page:
 
         man pandoc
 
@@ -45,14 +60,19 @@ 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].
+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 [zip-archive], [blaze-html], and [highlighting-kate].
+    you will need a number of additional libraries.  You can install
+    them all with
+
+        cabal update
+        cabal install --only-dependencies
 
 2.  Configure:
 
-        runghc Setup.hs configure --prefix=DIR --bindir=DIR --libdir=DIR \
+        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
@@ -64,26 +84,34 @@ you will need [zip-archive], [blaze-html], and [highlighting-kate].
     preceded by a `-` (to force the flag to `false`), and separated
     by spaces.  Pandoc's flags include:
 
-    - `blaze_html_0_5`: Use blaze-html >= 0.5 (default yes)
-    - `embed_data_files`: embed all data files into the binary (default no)
+    - `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
+
+    - `http-conduit`:  use the `http-conduit` library to fetch external
+      resources (default yes -- without this, pandoc cannot make SSL
+      connections)
 
 3.  Build:
 
-        runghc Setup.hs build
+        cabal build
 
 4.  Build API documentation:
 
-        runghc Setup.hs haddock --html-location=URL --hyperlink-source
+        cabal haddock --html-location=URL --hyperlink-source
 
 5.  Copy the files:
 
-        runghc Setup.hs copy --destdir=PATH
+        cabal copy --destdir=PATH
 
     The default destdir is `/`.
 
 6.  Register pandoc as a GHC package:
 
-        runghc Setup.hs register
+        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
@@ -109,7 +137,6 @@ you please.
 [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
 -------------
 
@@ -118,13 +145,6 @@ To build the tests:
 
     cabal configure --enable-tests && cabal build
 
-Note: If you obtained the source via git, you should first do
-
-    git submodule update --init data/templates
-
-to populate the templates subdirectory.  (You can skip this step
-if you obtained the source from a release tarball.)
-
 To run the tests:
 
     cabal test