rewrote and improved core documentation for clarity, utility and compatibility with Markdown

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

1 files changed, 88 insertions, 199 deletions

diff --git a/README b/README
index 9cbcd95d..cdbf44a8 100644
--- a/README
+++ b/README
@@ -1,343 +1,232 @@
-Apache CouchDB Readme
-=====================
+# Readme #
 
-Documentation
--------------
+## Building From Subversion ##
 
-Visit the wiki <http://www.couchdbwiki.com/> for more documentation.
-
-Building From Subversion
-------------------------
-
-Dependencies
-~~~~~~~~~~~~
+### Dependencies ###
 
 To build Apache CouchDB from checkout you need some of the following installed:
 
- * GNU Automake (>=1.6.3) <http://www.gnu.org/software/automake/> (required)
- * GNU Autoconf (>=2.59) <http://www.gnu.org/software/autoconf/> (required)
- * GNU Libtool <http://www.gnu.org/software/libtool/> (required)
- * svn2cl <http://ch.tudelft.nl/~arthur/svn2cl/> (optional)
- * xsltproc <http://xmlsoft.org/XSLT/xsltproc2.html> (optional)
- * help2man <http://www.gnu.org/software/help2man/> (optional)
+ * [GNU Automake](http://www.gnu.org/software/automake/) (>=1.6.3) (required)
+ * [GNU Autoconf](http://www.gnu.org/software/autoconf/) (>=2.59) (required)
+ * [GNU Libtool](http://www.gnu.org/software/libtool/) (required)
+ * [svn2cl](http://ch.tudelft.nl/~arthur/svn2cl/) (optional)
+ * [xsltproc](http://xmlsoft.org/XSLT/xsltproc2.html) (optional)
+ * [help2man](http://www.gnu.org/software/help2man/) (optional)
 
 If you are running a Debian GNU/Linux system (or a derivative such as Ubuntu
-GNU/Linux) you can install these dependencies using the `apt-get' command:
+GNU/Linux) you can install these dependencies using the `apt-get` command:
 
---------------------------------------------------------------------------------
-apt-get install automake autoconf libtool subversion-tools help2man
---------------------------------------------------------------------------------
+    apt-get install automake autoconf libtool subversion-tools help2man
 
-If you are running OS X and have MacPorts <http://www.macports.org/> installed
-you can install some of these dependencies by using the `port' command:
+If you are running OS X and have [MacPorts](http://www.macports.org/) installed
+you can install some of these dependencies by using the `port` command:
 
---------------------------------------------------------------------------------
-port install automake autoconf libtool help2man
---------------------------------------------------------------------------------
+    port install automake autoconf libtool help2man
 
 Note: OS X users should already have Automake, Autoconf and Libtool installed.
 
 Note: MacPorts users will need to install svn2cl by hand.
 
-Bootstrapping
-~~~~~~~~~~~~~
+### Bootstrapping ###
 
 Note: You must repeat this step every time you update your Subversion checkout.
 
 Bootstrap the pristine source by running the following command:
 
---------------------------------------------------------------------------------
-./bootstrap
---------------------------------------------------------------------------------
+    ./bootstrap
 
-You can use the `-C' option to generate a dummy `ChangeLog' file.
+You can use the `-C` option to generate a dummy `ChangeLog` file.
 
-Installation And First Run
---------------------------
+## Installation And First Run ##
 
 You will need the following installed:
 
- * Erlang OTP <http://erlang.org/> (required)
- * ICU <http://icu.sourceforge.net/> (required)
- * Mozilla SpiderMonkey <http://www.mozilla.org/js/spidermonkey/> (required)
- * GNU Make <http://www.gnu.org/software/make/> (required)
- * GNU Compiler Collection <http://gcc.gnu.org/> (required)
+ * [Erlang OTP](http://erlang.org/) (required)
+ * [ICU](http://icu.sourceforge.net/) (required)
+ * [Mozilla SpiderMonkey](http://www.mozilla.org/js/spidermonkey/) (required)
+ * [GNU Make](http://www.gnu.org/software/make/) (required)
+ * [GNU Compiler Collection](http://gcc.gnu.org/) (required)
 
-UNIX-like Operating Systems (inc. OS X)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### UNIX-like Operating Systems (inc. OS X) ###
 
-Dependencies
-^^^^^^^^^^^^
+#### Dependencies ####
 
-Debian-based (inc. Ubuntu) Systems
-++++++++++++++++++++++++++++++++++
+##### Debian-based (inc. Ubuntu) Systems #####
 
 If you are running a Debian GNU/Linux system (or a derivative such as Ubuntu
-GNU/Linux) you can install the dependencies using the `apt-get' command:
+GNU/Linux) you can install the dependencies using the `apt-get` command:
 
---------------------------------------------------------------------------------
-apt-get install build-essential erlang libicu36 libicu36-dev libmozjs-dev
---------------------------------------------------------------------------------
+    apt-get install build-essential erlang libicu36 libicu36-dev libmozjs-dev
 
-If you get an error regarding the `libicu36' or `libicu36-dev' be sure to check
-the version used by your distribution (using `apt-cache search libicu') and
+If you get an error regarding the `libicu36` or `libicu36-dev` be sure to check
+the version used by your distribution (using `apt-cache search libicu`) and
 install those packages instead.
 
-OS X
-++++
+##### OS X #####
 
 To install GNU Make and the GNU Compiler Collection on OS X you should install
 the Xcode Tools metapackage by running the following command:
 
---------------------------------------------------------------------------------
-open /Applications/Installers/Xcode\ Tools/XcodeTools.mpkg
---------------------------------------------------------------------------------
+    open /Applications/Installers/Xcode\ Tools/XcodeTools.mpkg
 
-We recommend that you satisfy the other dependancies by installing MacPorts
-<http://www.macports.org/> and running the following command:
+We recommend that you satisfy the other dependancies by installing
+[MacPorts](http://www.macports.org/) and running the following command:
 
---------------------------------------------------------------------------------
-port install icu erlang spidermonkey
---------------------------------------------------------------------------------
+    port install icu erlang spidermonkey
 
 Note: Don't forget to open a new terminal after you have installed MacPorts
-as it updates your PATH and you will not be able to run the `port' command
+as it updates your PATH and you will not be able to run the `port` command
 without the effects of this change.
 
-To update your `locate' database you may want to run the following command:
+To update your `locate` database you may want to run the following command:
 
---------------------------------------------------------------------------------
-sudo /usr/libexec/locate.updatedb
---------------------------------------------------------------------------------
+    sudo /usr/libexec/locate.updatedb
 
-Installing
-^^^^^^^^^^
+#### Installing ####
 
 Once you have satisfied dependencies you should run the following command:
 
---------------------------------------------------------------------------------
-./configure
---------------------------------------------------------------------------------
+    ./configure
 
-Note: Apache CouchDB is installed into `/usr/local' by default. If you want to
+Note: Apache CouchDB is installed into `/usr/local` by default. If you want to
 change where Apache CouchDB is installed (or where to find Erlang) be sure to
-read the output from running the `./configure --help' command.
+read the output from running the `./configure --help` command.
 
-Note: All the examples assume you have installed into `/usr/local'.
+Note: All the examples assume you have installed into `/usr/local`.
 
 If everything was successful you should see the following message:
 
---------------------------------------------------------------------------------
-You have configured Apache CouchDB. Time to relax.
---------------------------------------------------------------------------------
+    You have configured Apache CouchDB. Time to relax.
 
 Relax.
 
 To install Apache CouchDB you should then run the following command:
 
---------------------------------------------------------------------------------
-make && sudo make install
---------------------------------------------------------------------------------
+    make && sudo make install
 
 If you do not wish to be prompted to overwrite any existing Apache CouchDB
 configuration files you should run the following command:
 
---------------------------------------------------------------------------------
-sudo make && yes | sudo make install
---------------------------------------------------------------------------------
+    sudo make && yes | sudo make install
 
-Note: Use of the `sudo' command is only required if you are installing into a
+Note: Use of the `sudo` command is only required if you are installing into a
 system owned directory. You do not need to do this if you are installing
 elsewhere, such as your home directory.
 
-More options can be found by reading the `INSTALL' file.
+More options can be found by reading the `INSTALL` file.
 
-Security Considerations
-^^^^^^^^^^^^^^^^^^^^^^^
+#### Security Considerations ####
 
 It is not advisable to run Apache CouchDB as the superuser. We strongly
 recommend that you create a specific user to run Apache CouchDB and own the
 data/log directories.
 
-You can use whatever tool your system provides to create a new `couchdb' user.
+You can use whatever tool your system provides to create a new `couchdb` user.
 
 On many UNIX-like systems you can run the following command:
 
---------------------------------------------------------------------------------
-adduser couchdb
---------------------------------------------------------------------------------
+    adduser couchdb
 
 OS X provides the standard Accounts option from the System Preferences
 application or you can optionally use the Workgroup Manager application which
-can be downloaded as part of the Server Admin Tools
-<http://www.apple.com/support/downloads/serveradmintools1047.html>.
+can be downloaded as part of the [Server Admin Tools](
+http://www.apple.com/support/downloads/serveradmintools1047.html).
 
-You should set the home directory of the `couchdb' user to
-`/usr/local/var/lib/couchdb' which is the Apache CouchDB database directory.
+You should set the home directory of the `couchdb` user to
+`/usr/local/var/lib/couchdb` which is the Apache CouchDB database directory.
 
 Make sure to change the ownership of the Apache CouchDB data directories by
 running the following commands:
 
---------------------------------------------------------------------------------
-chown -R couchdb /usr/local/var/lib/couchdb
-chown -R couchdb /usr/local/var/log/couchdb
---------------------------------------------------------------------------------
+    chown -R couchdb /usr/local/var/lib/couchdb
+    chown -R couchdb /usr/local/var/log/couchdb
 
-Running Manually
-^^^^^^^^^^^^^^^^
+#### Running Manually ####
 
 To start the Apache CouchDB server you should run the following command:
 
---------------------------------------------------------------------------------
-sudo -u couchdb couchdb
---------------------------------------------------------------------------------
+    sudo -u couchdb couchdb
 
-This uses the `sudo' command to run the `couchdb' command as the `couchdb' user.
+This uses the `sudo` command to run the `couchdb` command as the `couchdb` user.
 
 When Apache CouchDB starts it should eventually display the following message:
 
---------------------------------------------------------------------------------
-Apache CouchDB has started. Time to relax.
---------------------------------------------------------------------------------
+    Apache CouchDB has started. Time to relax.
 
 Relax.
 
 To check that everything has worked point your web browser to
-<http://localhost:5984/_utils/index.html> and run the test suite.
+http://localhost:5984/_utils/index.html and run the test suite.
 
-OS X
-++++
+##### OS X #####
 
 If you get error when running Apache CouchDB that look like the following:
 
---------------------------------------------------------------------------------
-dyld: Library not loaded: libicuuc.38.dy
---------------------------------------------------------------------------------
+    dyld: Library not loaded: libicuuc.38.dy
 
-You should make sure that your `~/.profile' file contains the following line:
+You should make sure that your `~/.profile` file contains the following line:
 
---------------------------------------------------------------------------------
-export DYLD_LIBRARY_PATH=/opt/local/lib:$DYLD_LIBRARY_PATH
---------------------------------------------------------------------------------
+    export DYLD_LIBRARY_PATH=/opt/local/lib:$DYLD_LIBRARY_PATH
 
 This should have been added for you by MacPorts but may be missing.
 
-Running as a Daemon
-^^^^^^^^^^^^^^^^^^^
+#### Running as a Daemon ####
 
-Note: These instructions assume you have created the `couchdb' user. See the
+Note: These instructions assume you have created the `couchdb` user. See the
 specific system information included below to learn how to reconfigure this.
 
-Note: If any of these methods report a failure you can run the `couchdb'
+Note: If any of these methods report a failure you can run the `couchdb`
 command manually to see the error messages it is displaying.
 
-The `/usr/local/etc/logrotate.d/couchdb' file is provided as a logrotate
+The `/usr/local/etc/logrotate.d/couchdb` file is provided as a logrotate
 configuration that you can use to rotate Apache CouchDB's logs.
 
-SysV/BSD-style Systems
-++++++++++++++++++++++
+##### SysV/BSD-style Systems #####
 
-Depending on your system the `couchdb' init script will be installed into a
-direcory called `init.d' (for SysV-style systems) or `rc.d' (for BSD-style
-systems). These examples use the `[init.d|rc.d]' notation to indicate this.
+Depending on your system the `couchdb` init script will be installed into a
+direcory called `init.d` (for SysV-style systems) or `rc.d` (for BSD-style
+systems). These examples use the `[init.d|rc.d]` notation to indicate this.
 
 You can control the Apache CouchDB daemon by running the following command:
 
---------------------------------------------------------------------------------
-/usr/local/etc/[init.d|rc.d]/couchdb [start|stop|restart|force-reload|status]
---------------------------------------------------------------------------------
+    /usr/local/etc/[init.d|rc.d]/couchdb [start|stop|restart|force-reload|status]
 
 If you wish to configure how the init script works, such as which user to run
-Apache CouchDB as, you must edit the `/usr/local/etc/default/couchdb' file as
+Apache CouchDB as, you must edit the `/usr/local/etc/default/couchdb` file as
 appropriate. If you are running the init script as a non-superuser you need to
-remove the line with the `COUCHDB_USER' setting.
+remove the line with the `COUCHDB_USER` setting.
 
 If you wish the ApacheCouchDB daemon to run as a system service you need to copy
-the `/usr/local/etc/[init.d|rc.d]/couchdb' script into your system wide
-`/etc/[init.d|rc.d]' directory and update your system configuration as
+the `/usr/local/etc/[init.d|rc.d]/couchdb` script into your system wide
+`/etc/[init.d|rc.d]` directory and update your system configuration as
 appropriate.  Consult your system documentation for more information.
 
 If you are running a Debian GNU/Linux system (or a derivative such as Ubuntu
 GNU/Linux) you can configure your system using the following command:
 
---------------------------------------------------------------------------------
-sudo update-rc.d couchdb defaults
---------------------------------------------------------------------------------
+    sudo update-rc.d couchdb defaults
 
-OS X
-++++
+##### OS X #####
 
-You can use the `launchctl' command to control the Apache CouchDB daemon.
+You can use the `launchctl` command to control the Apache CouchDB daemon.
 
 To load the launchd configuration you must run the following command:
 
---------------------------------------------------------------------------------
-sudo launchctl load /usr/local/Library/LaunchDaemons/org.apache.couchdb
---------------------------------------------------------------------------------
+    sudo launchctl load /usr/local/Library/LaunchDaemons/org.apache.couchdb
 
 You can stop the Apache CouchDB daemon by running the following command:
 
---------------------------------------------------------------------------------
-sudo launchctl unload /usr/local/Library/LaunchDaemons/org.apache.couchdb
---------------------------------------------------------------------------------
+    sudo launchctl unload /usr/local/Library/LaunchDaemons/org.apache.couchdb
 
 If you wish to change the launchd configuration, such as which user to run
 Apache CouchDB as, you must edit the
-`/usr/local/Library/LaunchDaemons/org.apache.couchdb.plist' file as
+`/usr/local/Library/LaunchDaemons/org.apache.couchdb.plist` file as
 appropriate.
 
 If you wish the Apache CouchDB daemon to run as a system service you need to
-copy the `/usr/local/Library/LaunchDaemons/org.apache.couchdb.plist' file into
-your system wide `/Library/LaunchDaemons' directory.
+copy the `/usr/local/Library/LaunchDaemons/org.apache.couchdb.plist` file into
+your system wide `/Library/LaunchDaemons` directory.
 
-Windows
-~~~~~~~
+### Windows ###
 
 Windows documentation is incomplete. Please submit suggestions.
-
-Development and Distribution
-----------------------------
-
-Reconfiguring the Build System
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you have edited any of the files used by the build system, such as the
-`Makefile.am' files, you will need to reconfigure your source.
-
-To reconfigure the source run the following command from the root directory:
-
---------------------------------------------------------------------------------
-autoreconf && ./confgure
---------------------------------------------------------------------------------
-
-Checking In Changes
-~~~~~~~~~~~~~~~~~~~
-
-If your source directory has been configured or built you will need to clean
-the generated files before checking into the repository by running the
-following command:
-
---------------------------------------------------------------------------------
-make local-clean
---------------------------------------------------------------------------------
-
-If everything was successful you should now have a pristine checkout.
-
-Preparing For Distribution
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To build the source for distribution you should then run the following command:
-
---------------------------------------------------------------------------------
-./configure && make distcheck
---------------------------------------------------------------------------------
-
-If everything was successful you should see a `zip' file and/or a `tar.gz' file
-sitting in the root directory ready for distribution.
-
-Release Checklist
-~~~~~~~~~~~~~~~~~
-
- 1. Update this file with important information.
- 2. Update the `NEWS' file with change information.
- 3. Update the `acinclude.m4' file with version information.