documentation improvements

git-svn-id: https://svn.apache.org/repos/asf/couchdb/trunk@922586 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 94 insertions, 84 deletions

diff --git a/INSTALL.Windows b/INSTALL.Windows
index ad1787aa..5c4a9587 100644
--- a/INSTALL.Windows
+++ b/INSTALL.Windows
@@ -1,138 +1,148 @@
-Installing on Microsoft Windows
-===============================
+Apache CouchDB README.Windows
+==============================
 
-Windows
-~~~~~~~
+For a high-level guide to Microsoft Windows.
 
-The Windows build process is very similar to the Erlang build process.
+Dependencies
+------------
 
-Build Tools
-^^^^^^^^^^^
+You will need the following installed:
 
-To build on Windows, you will need the following installed:
+ * Erlang OTP (>=R12B5)       (http://erlang.org/)
+ * ICU                        (http://icu.sourceforge.net/)
+ * OpenSSL                    (http://www.openssl.org/)
+ * Mozilla SpiderMonkey (1.8) (http://www.mozilla.org/js/spidermonkey/)
+ * libcurl                    (http://curl.haxx.se/libcurl/)
+ * Cygwin                     (http://www.cygwin.com/)
+ * Visual Studio 2008         (http://msdn.microsoft.com/en-gb/vstudio/default.aspx)
 
- * Erlang OTP (>=R12B5)        (http://erlang.org/)
- * ICU                         (http://icu.sourceforge.net/)
- * OpenSSL                     (http://www.openssl.org/)
- * Mozilla SpiderMonkey (=1.8) (http://www.mozilla.org/js/spidermonkey/)
- * libcurl                     (http://curl.haxx.se/libcurl/)
- * Cygwin                      (http://www.cygwin.com/)
- * Visual Studio 2008          (http://msdn.microsoft.com/en-gb/vstudio/default.aspx)
+General Notes
+-------------
 
-Please note:
+ * When installing Erlang, you must build it from source.
 
- * When installing Erlang, you must build it from source. The CouchDB build
-   makes use of a number of the Erlang build scripts.
+   The CouchDB build makes use of a number of the Erlang build scripts.
 
  * When installing ICU, select the binaries built with Visual Studio 2008.
 
  * When installing Cygwin, be sure to select all the `development` tools.
 
- * When installing libcurl, be sure to install by hand as the Cygwin binaries
-   are built with an incompatible compiler and will not work with Erlang.
+ * When installing libcurl, be sure to install by hand.
 
-Setting Up
-^^^^^^^^^^
+   The Cygwin binaries are incompatible and will not work with Erlang.
 
-Before starting any Cygwin terminals, run the following command:
+Setting Up Cygwin
+-----------------
+
+Before starting any Cygwin terminals, run:
 
     set CYGWIN=nontsec
 
-To set up your environment, run the following command:
+To set up your environment, run:
 
     [VS_BIN]/vcvars32.bat
 
 Replace [VS_BIN] with the path to your Visual Studio `bin` directory.
 
-After you have done this, `link.exe` and `cl.exe` should be on your path and
-correspond to the Microsoft linker and compiler, respectively.
+You must check that:
 
-To set up your environment, run the following command:
+    * The `which link` command points to the Microsoft linker.
 
-    eval `./otp_build env_win32`
+    * The `which cl` command points to the Microsoft compiler.
+
+If you do not do this, the ones found in `/usr/bin` may be used instead.
 
-Do this even if you have already built Erlang because the CouchDB build system
-needs the environment variables set up by this script.
+Building Erlang
+---------------
 
-To set up your path, run the following command:
+You must include OpenSSL.
 
-    export PATH=$ERL_TOP/release/win32/erts-5.7.2/bin:$PATH
+However, you can skip the GUI tools by running:
+
+   echo "skipping gs" > lib/gs/SKIP
+
+   echo "skipping ic" > lib/ic/SKIP
+
+Follow the rest of the Erlang instructions as described.
+
+After running:
+
+   ./otp_build release -a
+
+You should run:
+
+   ./release/win32/Install.exe
 
-Everything should be set up properly now.
+This will set up the release/win32/bin directory correctly.
 
-Building
-^^^^^^^^
+To set up your environment for building CouchDB, run:
 
-We start by bootstrapping:
+    eval `./otp_build env_win32`
+
+To set up the `ERL_TOP` environment variable, run:
+
+    export ERL_TOP=[ERL_TOP]
+
+Replace `[ERL_TOP]` with the Erlang source directory name.
+
+Remember to use `/cygdrive/c/` instead of `c:/` as the directory prefix.
+
+To set up your path, run:
 
-  $ cd $COUCHDB_TOP
-  $ ./bootstrap
-  You have bootstrapped Apache CouchDB, time to relax.
+    export PATH=$ERL_TOP/release/win32/erts-5.7.2/bin:$PATH
 
-  Run `./configure' to configure the source before you install.
-  $
+If everything was successful, you should be ready to build CouchDB.
 
 Relax.
 
-Now we need to run a complicated configure command-line.
+Building CouchDB
+----------------
+
+Once you have satisfied the dependencies you should run:
 
-  $ ./configure \
-      --with-js-include=/cygdrive/c/path_to_seamonkey_include \
-      --with-js-lib=/cygdrive/c/path_to_seamonkey_lib \
-      --with-win32-icu-binaries=/cygdrive/c/path_to_icu_binaries_root \
-      --with-erlang=$ERL_TOP/release/win32/usr/include \
-      --with-win32-curl=/cygdrive/c/path/to/curl/root/directory \
-      --with-openssl-bin-dir=/cygdrive/c/openssl/bin \
-      --with-msvc-redist-dir=/cygdrive/c/dir/with/vcredist_platform_executable \
-      --prefix=$ERL_TOP/release/win32
+    ./configure \
+        --with-js-include=/cygdrive/c/path_to_seamonkey_include \
+        --with-js-lib=/cygdrive/c/path_to_seamonkey_lib \
+        --with-win32-icu-binaries=/cygdrive/c/path_to_icu_binaries_root \
+        --with-erlang=$ERL_TOP/release/win32/usr/include \
+        --with-win32-curl=/cygdrive/c/path/to/curl/root/directory \
+        --with-openssl-bin-dir=/cygdrive/c/openssl/bin \
+        --with-msvc-redist-dir=/cygdrive/c/dir/with/vcredist_platform_executable \
+        --prefix=$ERL_TOP/release/win32
 
-Relax, then relax some more, then get a beer and relax some more; the
-above command may take many many minutes to complete...
+This command could take a while to complete.
 
-Note that all paths must be in cygwin format (ie, using '/cygdrive/c/dir/...'
-rather than 'c:/dir'.)  Those starting with $ERL_TOP can be entered
-literally, assuming ERL_TOP is set as described above.
+If everything was successful you should see the following message:
 
-Notes:
-  When building the installer, the necessary openssl binaries are pulled from
-  the directory pointed to --with-openssl-bin-dir.
+    You have configured Apache CouchDB, time to relax.
 
-Now we can build it and "install" it into the $ERL_TOP/release/win32 (or
-wherever you set --prefix to above) directory:
+Relax.
 
- $ make install
+To install CouchDB you should run:
 
-Relax on your new couch:
+    make install
 
-  The $ERL_TOP/release/win32 directory is now ready to .zip up, be packaged
-  by an installer, etc.  To test it in-place, execute:
+If everything was successful you should see the following message:
 
-  $ $ERL_TOP/release/win32/bin/couchdb.bat
+    You have installed Apache CouchDB, time to relax.
 
-  and everything should work fine.
+Relax.
 
-To create an installer, execute:
+First Run
+---------
 
-  $ make dist
+You can start the CouchDB server by running:
 
-and look for etc/windows/setup-couch*.exe.  Note - only do this after
-a clean build, not after testing in-place - otherwise your test database and
-log files will be shipped!
+    $ERL_TOP/release/win32/bin/couchdb.bat
 
-Notes
-^^^^^
+When CouchDB starts it should eventually display the following message:
 
-Building Erlang
-+++++++++++++++
+    Apache CouchDB has started, time to relax.
 
- * Follow the instructions as described. You do need openssl, but don't need
-   the GUI tools. You can skip them with the following command:
+Relax.
 
-    echo "skipping gs" > lib/gs/SKIP
-    echo "skipping ic" > lib/ic/SKIP
+To check that everything has worked, point your web browser to:
 
- * Ensure `which link` points at the Microsoft linker. If you do not do this,
-   the one in /usr/bin may be found instead.
+    http://127.0.0.1:5984/_utils/index.html
 
- * After executing `./otp_build release -a`, be sure to execute Install.exe in
-   the release/win32 directory to setup the release/win32/bin dir correctly.
+From here you should run the test suite.