Improve grammar, text flow in new configuration docs.

5 files changed, 160 insertions, 107 deletions

diff --git a/share/doc/src/api/server/common.rst b/share/doc/src/api/server/common.rst
index 690c55d8f..22e312d5c 100644
--- a/share/doc/src/api/server/common.rst
+++ b/share/doc/src/api/server/common.rst
@@ -959,9 +959,9 @@ structure is as follows:
 The UUID type is determined by the :ref:`UUID algorithm <config/uuids/algorithm>`
 setting in the CouchDB configuration.
 
-The UUID type could be changed in anytime through
-:ref:`Config API <api/config/section/key>`. For example, changing the UUID
-type to ``random`` use next HTTP request:
+The UUID type may be changed at any time through the
+:ref:`Configuration API <api/config/section/key>`. For example, the UUID type
+could be changed to ``random`` by sending this HTTP request:
 
 .. code-block:: http
 
@@ -971,7 +971,7 @@ type to ``random`` use next HTTP request:
 
     "random"
 
-When obtaining a list of UUIDs you'll see the changes:
+You can verify the change by obtaining a list of UUIDs:
 
 .. code-block:: javascript
 
diff --git a/share/doc/src/config/auth.rst b/share/doc/src/config/auth.rst
index 410ae4695..279e12419 100644
--- a/share/doc/src/config/auth.rst
+++ b/share/doc/src/config/auth.rst
@@ -108,7 +108,9 @@ work factor for ``PBKDF2``, and the algorithm itself at
 ``allow_persistent_cookies`` :: Persistent cookies
 --------------------------------------------------
 
-Makes cookies persistent if ``true``::
+Makes cookies persistent if ``true``.
+
+::
 
   [couch_httpd_auth]
   allow_persistent_cookies = false
@@ -119,7 +121,9 @@ Makes cookies persistent if ``true``::
 ``auth_cache_size`` :: Authentication cache
 -------------------------------------------
 
-Number of :ref:`userctx_object` to cache in memory to reduce disk lookups::
+Number of :ref:`userctx_object` to cache in memory, to reduce disk lookups.
+
+::
 
   [couch_httpd_auth]
   auth_cache_size = 50
@@ -130,14 +134,15 @@ Number of :ref:`userctx_object` to cache in memory to reduce disk lookups::
 ``authentication_db`` :: Users database
 ---------------------------------------
 
-Specifies the name of the system database for storing CouchDB users::
+Specifies the name of the system database for storing CouchDB users.
+
+::
 
   [couch_httpd_auth]
   authentication_db = _users
 
-.. warning:: If there was any reasons to change this name for you, don't forget
-   to remove/cleanup old database since it wouldn't be protected by CouchDB
-   anymore.
+.. warning:: If you change the database name, do not forget to remove or clean
+   up the old database, since it will no longer be protected by CouchDB.
 
 
 .. _config/couch_httpd_auth/authentication_redirect:
@@ -146,7 +151,9 @@ Specifies the name of the system database for storing CouchDB users::
 ---------------------------------------------------------------------------
 
 Specifies the location for redirection on successful authentication if a
-``text/html`` response is accepted by the client (via ``Accept`` header)::
+``text/html`` response is accepted by the client (via an ``Accept`` header).
+
+::
 
   [couch_httpd_auth]
   authentication_redirect = /_utils/session.html
@@ -159,8 +166,11 @@ Specifies the location for redirection on successful authentication if a
 
 .. versionadded:: 1.3
 
-The umbenr of iterations for password hashing by the PBKDF2 algorithm. A higher 
-number provides better hash durability, but with cost of performance on each request that requires authentication::
+The number of iterations for password hashing by the PBKDF2 algorithm. A higher 
+number provides better hash durability, but comes at a cost in performance for
+each request that requires authentication.
+
+::
 
   [couch_httpd_auth]
   iterations = 10000
@@ -171,8 +181,11 @@ number provides better hash durability, but with cost of performance on each req
 ``proxy_use_secret`` :: Force proxy auth use secret token
 ---------------------------------------------------------
 
-When this option is ``true`` the :ref:`secret <config/couch_httpd_auth/secret>` 
-is required for :ref:`api/auth/proxy`::
+When this option is set to ``true``, the
+:ref:`secret <config/couch_httpd_auth/secret>` option is required for
+:ref:`api/auth/proxy`.
+
+::
 
   [couch_httpd_auth]
   proxy_use_secret = false
@@ -185,9 +198,10 @@ is required for :ref:`api/auth/proxy`::
 
 .. versionadded:: 1.4
 
-Comma-separated list of field names that will be available to view for any user
-document in :ref:`authentication_db <config/couch_httpd_auth/authentication_db>`
-If unset or not specified, authenticated users may retrieve only their own docs.
+A comma-separated list of field names in user documents (in
+:ref:`authentication_db <config/couch_httpd_auth/authentication_db>`) that can
+be read by any user. If unset or not specified, authenticated users can only
+retrieve their own document.
 
 ::
 
@@ -204,11 +218,13 @@ If unset or not specified, authenticated users may retrieve only their own docs.
 
 .. _config/couch_httpd_auth/require_valid_user:
 
-``require_valid_user`` :: Force users authentication
-----------------------------------------------------
+``require_valid_user`` :: Force user authentication
+---------------------------------------------------
+
+When this option is set to ``true``, no requests are allowed from anonymous
+users. Everyone must be authenticated.
 
-When this option ``true`` no requests allowed from anonymous users. Everyone
-must be authenticated::
+::
 
   [couch_httpd_auth]
   require_valid_user = false
@@ -219,7 +235,9 @@ must be authenticated::
 ``secret`` :: Proxy Auth secret token
 -------------------------------------
 
-The secret token used for :ref:`api/auth/proxy` method::
+The secret token used for :ref:`api/auth/proxy` method.
+
+::
 
   [couch_httpd_auth]
   secret = 92de07df7e7a3fe14808cef90a7cc0d91
@@ -230,7 +248,9 @@ The secret token used for :ref:`api/auth/proxy` method::
 ``timeout`` :: Session timeout
 ------------------------------
 
-Number of seconds since the last request before session will be expired::
+Number of seconds since the last request before sessions will be expired.
+
+::
 
   [couch_httpd_auth]
   timeout = 600
@@ -239,13 +259,15 @@ Number of seconds since the last request before session will be expired::
 
 .. _config/couch_httpd_auth/users_db_public:
 
-``users_db_public`` :: Publish users info
------------------------------------------
+``users_db_public`` :: Publish user documents
+---------------------------------------------
 
 .. versionadded:: 1.4
 
 Allow all users to view user documents. By default, only admins may browse
-all users documents while users may browse only their own document::
+all users documents, while users may browse only their own document.
+
+::
 
   [couch_httpd_auth]
   users_db_public = false
@@ -256,8 +278,10 @@ all users documents while users may browse only their own document::
 ``x_auth_roles`` :: Proxy Auth roles header
 -------------------------------------------
 
-HTTP header name (``X-Auth-CouchDB-Roles`` by default) that contains the list of
-user's roles separated by a comma. Used for :ref:`api/auth/proxy`::
+The HTTP header name (``X-Auth-CouchDB-Roles`` by default) that contains the
+list of a user's roles, separated by a comma. Used for :ref:`api/auth/proxy`.
+
+::
 
   [couch_httpd_auth]
   x_auth_roles = X-Auth-CouchDB-Roles
@@ -268,13 +292,16 @@ user's roles separated by a comma. Used for :ref:`api/auth/proxy`::
 ``x_auth_token`` :: Proxy Auth token header
 -------------------------------------------
 
-HTTP header name (``X-Auth-CouchDB-Token`` by default) with token to
-authenticate the authorization. This token is an `HMAC-SHA1` created from
-:ref:`secret key <config/couch_httpd_auth/secret>` and
+The HTTP header name (``X-Auth-CouchDB-Token`` by default) containing the
+token used to authenticate the authorization. This token is an `HMAC-SHA1`
+created from :ref:`secret key <config/couch_httpd_auth/secret>` and
 :ref:`username <config/couch_httpd_auth/x_auth_username>`. The secret key
-should be the same in the client and CouchDB node. This token is optional
-if value of :ref:`proxy_use_secret <config/couch_httpd_auth/proxy_use_secret>`
-option isn't ``true``. Used for :ref:`api/auth/proxy`::
+should be the same on the client and the CouchDB node. This token is optional
+if the value of the
+:ref:`proxy_use_secret <config/couch_httpd_auth/proxy_use_secret>`
+option is not ``true``. Used for :ref:`api/auth/proxy`.
+
+::
 
   [couch_httpd_auth]
   x_auth_roles = X-Auth-CouchDB-Token
@@ -285,8 +312,10 @@ option isn't ``true``. Used for :ref:`api/auth/proxy`::
 ``x_auth_username`` :: Proxy Auth username header
 -------------------------------------------------
 
-HTTP header name (``X-Auth-CouchDB-UserName`` by default) containing the
-username. Used for :ref:`api/auth/proxy`::
+The HTTP header name (``X-Auth-CouchDB-UserName`` by default) containing the
+username. Used for :ref:`api/auth/proxy`.
+
+::
 
   [couch_httpd_auth]
   x_auth_username = X-Auth-CouchDB-UserName
@@ -305,11 +334,10 @@ username. Used for :ref:`api/auth/proxy`::
 Store credentials within config
 -------------------------------
 
-To let users be authenticated by :ref:`api/auth/oauth` (:rfc:`5849`) method
-there is need to setup three special sections in :ref:`configuration <config>`
-file:
+To let users be authenticated by :ref:`api/auth/oauth` (:rfc:`5849`), three
+special sections must be set up in the :ref:`configuration <config>` file:
 
-1. Consumer secret:
+1. The Consumer secret:
 
 ::
 
@@ -323,7 +351,7 @@ file:
   [oauth_token_secrets]
   token1 = tokensekr1t
 
-3. Tokens to users mapping:
+3. A mapping from tokens to users:
 
 ::
 
@@ -339,8 +367,8 @@ Store OAuth credentials within auth database
 
 .. versionadded:: 1.2
 
-CouchDB is able to store OAuth credentials within users documents instead of
-config file by using next option::
+CouchDB is able to store OAuth credentials within user documents instead of
+config file by using this option::
 
   [couch_httpd_oauth]
   use_users_db = true
@@ -348,7 +376,7 @@ config file by using next option::
 If set to ``true``, OAuth token and consumer secrets will be looked up in the
 :ref:`authentication database <config/couch_httpd_auth/authentication_db>`.
 These secrets are stored in a top level field named ``"oauth"`` in user
-documents. Example:
+documents, as below.
 
 .. code-block:: javascript
 
diff --git a/share/doc/src/config/couchdb.rst b/share/doc/src/config/couchdb.rst
index 053f7e9f3..c1bd182ba 100644
--- a/share/doc/src/config/couchdb.rst
+++ b/share/doc/src/config/couchdb.rst
@@ -26,9 +26,12 @@ Base Configuration
 ``attachment_stream_buffer_size`` :: Attachment streaming buffer
 ----------------------------------------------------------------
 
-Higher values may give better read performance due to less read operations
-and/or more OS page cache hits, but they can also increase overall response
-time for writes when there are many attachment write requests in parallel::
+Higher values may result in better read performance due to fewer read
+operations and/or more OS page cache hits. However, they can also increase
+overall response time for writes when there are many attachment write
+requests in parallel.
+
+::
 
   [couchdb]
   attachment_stream_buffer_size = 4096
@@ -39,9 +42,11 @@ time for writes when there are many attachment write requests in parallel::
 ``database_dir`` :: Databases location directory
 ------------------------------------------------
 
-Specifies location of CouchDB databases files (``*.couch`` named). This location
-should be writable and readable for user that runs CouchDB service (``couchdb``
-by default)::
+Specifies location of CouchDB database files (``*.couch`` named). This location
+should be writable and readable for the user the CouchDB service runs as
+(``couchdb`` by default).
+
+::
 
   [couchdb]
   database_dir = /var/lib/couchdb
@@ -74,15 +79,15 @@ losing durability - it's strongly not recommended to do such in production::
 ``file_compression`` :: Compression method for documents
 -----------------------------------------------------------
 
-.. versionchanged:: 1.2 Added `Google Snappy`_ compression algorithm
+.. versionchanged:: 1.2 Added `Google Snappy`_ compression algorithm.
 
 Method used to compress everything that is appended to database and view index
 files, except for attachments (see the :ref:`[attachments] <config/attachments>`
 section). Available methods are:
 
 * ``none``: no compression
-* ``snappy``: use Google Snappy, a very fast compressor/decompressor.
-* ``deflate_N``: use zlib's deflate, ``N`` is the compression level which ranges
+* ``snappy``: use Google Snappy, a very fast compressor/decompressor
+* ``deflate_N``: use zlib's deflate; ``N`` is the compression level which ranges
   from 1 (fastest, lowest compression ratio) to 9 (slowest, highest compression
   ratio)
 
@@ -99,9 +104,11 @@ section). Available methods are:
 ``fsync_options`` :: Fsync options
 ----------------------------------
 
-Specifies when to make `fsync` calls. `fsync` makes sure that any file system 
-buffers kept by the operating system are written to disk. Normally, you have no
-need to edit this parameter::
+Specifies when to make `fsync` calls. `fsync` makes sure that the contents of
+any file system buffers kept by the operating system are flushed to disk.
+There is generally no need to modify this parameter.
+
+::
 
   [couchdb]
   fsync_options = [before_header, after_header, on_file_open]
@@ -112,11 +119,13 @@ need to edit this parameter::
 ``max_dbs_open`` :: Limit of simultaneously opened databases
 ------------------------------------------------------------
 
-This option places an upper bound on the number of databases that can be open at
-one time. CouchDB reference counts database accesses internally and will close
-idle databases when it must. Sometimes it is necessary to keep more than the
+This option places an upper bound on the number of databases that can be open
+at once. CouchDB reference counts database accesses internally and will close
+idle databases as needed. Sometimes it is necessary to keep more than the
 default open at once, such as in deployments where many databases will be
-continuously replicating::
+replicating continuously.
+
+::
 
   [couchdb]
   max_dbs_open = 100
@@ -129,11 +138,13 @@ continuously replicating::
 
 .. versionchanged:: 1.3 This option now actually works.
 
-Defines limit of size in bytes that document may has in JSON form. Doesn't
-applies for attachments since they are been transferred as stream of chunks.
-Do not set this value too small since you want be able to modify config options,
-database security and other options until you restore this value by edit config
-file::
+Defines a maximum size for JSON documents, in bytes. This limit does not
+apply to attachments, since they are transferred as a stream of chunks. If you
+set this to a small value, you might be unable to modify configuration options,
+database security and other larger documents until a larger value is restored
+by editing the configuration file.
+
+::
 
   [couchdb]
   max_document_size = 4294967296 ; 4 GB
@@ -144,10 +155,12 @@ file::
 ``os_process_timeout`` :: External processes time limit
 -------------------------------------------------------
 
-Number of microseconds that external processes such as `query server` and
-`externals` may process CouchDB commands before return any result. Keeping
-this value smaller you'll be ensured that your services works fast, but you may
-tweak it depending on your needs::
+If an external process, such as a query server or external process, runs for
+this amount of microseconds without returning any results, it will be
+terminated. Keeping this value smaller ensures you get expedient errors, but
+you may want to tweak it for your specific needs.
+
+::
 
   [couchdb]
   os_process_timeout = 5000 ; 5 sec
@@ -158,10 +171,13 @@ tweak it depending on your needs::
 ``uri_file`` :: Discovery CouchDB help file
 -------------------------------------------
 
-This file contains full `URI`_ that runs CouchDB. It's used to help discover
-CouchDB served port if it was set to ``0`` (e.g. automatically assigned any
-free one). This file should be writable and readable for user that runs CouchDB
-service (``couchdb`` by default)::
+This file contains the full `URI`_ that can be used to access this instance of
+CouchDB. It is used to help discover the port CouchDB is running on (if it was
+set to ``0`` (e.g. automatically assigned any free one). This file should be
+writable and readable for the user that runs the CouchDB service (``couchdb``
+by default).
+
+::
 
   [couchdb]
   uri_file = /var/run/couchdb/couchdb.uri
@@ -174,8 +190,10 @@ service (``couchdb`` by default)::
 ``util_driver_dir`` :: CouchDB binary utility drivers
 -----------------------------------------------------
 
-Specified location of binary drivers (`icu`, `ejson`, etc.). This location and
-his content should be readable for user that runs CouchDB service::
+Specifies location of binary drivers (`icu`, `ejson`, etc.). This location and
+its contents should be readable for the user that runs the CouchDB service.
+
+::
 
   [couchdb]
   util_driver_dir = /usr/lib/couchdb/erlang/lib/couch-1.3.0/priv/lib
@@ -188,7 +206,9 @@ his content should be readable for user that runs CouchDB service::
 
 .. versionadded:: 1.3
 
-Unique identifier of CouchDB server instance::
+Unique identifier for this CouchDB server instance.
+
+::
 
   [couchdb]
   uuid = 0a959b9b8227188afc2ac26ccdf345a6
@@ -200,7 +220,9 @@ Unique identifier of CouchDB server instance::
 -----------------------------------------------------
 
 Specifies location of CouchDB view index files. This location should be writable
-and readable for user that runs CouchDB service (``couchdb`` by default)::
+and readable for the user that runs the CouchDB service (``couchdb`` by default).
+
+::
 
   [couchdb]
   view_index_dir = /var/lib/couchdb
diff --git a/share/doc/src/config/http.rst b/share/doc/src/config/http.rst
index 3c865859f..f22509234 100644
--- a/share/doc/src/config/http.rst
+++ b/share/doc/src/config/http.rst
@@ -653,9 +653,9 @@ behind a proxy, then you don't need to specify a port number in the `vhost` key.
 
 The first line will rewrite the request to display the content of the `example`
 database. This rule works only if the ``Host`` header is ``couchdb.local`` and
-won't work for `CNAMEs`. The second rule on the other hand matches all
-`CNAMEs` to `example` db. So `www.couchdb.local` or `db.couchdb.local` will
-work.
+won't work for `CNAMEs`. The second rule, on the other hand, matches all
+`CNAMEs` to `example` db, so that both `www.couchdb.local` and `db.couchdb.local`
+will work.
 
 
 .. _config/vhosts/rewriting:
diff --git a/share/doc/src/config/misc.rst b/share/doc/src/config/misc.rst
index ffd9041c4..235142d10 100644
--- a/share/doc/src/config/misc.rst
+++ b/share/doc/src/config/misc.rst
@@ -27,7 +27,7 @@ Miscellaneous Parameters
 ---------------------
 
 Defines zlib compression level for the attachments from ``1`` (lowest, fastest)
-to ``9`` (highest, slowest). ``0`` value disables compression::
+to ``9`` (highest, slowest). A value of ``0`` disables compression::
 
   [attachments]
   compression_level = 8
@@ -38,8 +38,8 @@ to ``9`` (highest, slowest). ``0`` value disables compression::
 ``compressible_types``
 ----------------------
 
-While not all attached files could be compressed well, it is possible to let
-CouchDB compress only specific attachments identified by their MIME type::
+Since compression is ineffective for some types of files, it is possible to let
+CouchDB compress only some types of attachments, specified by their MIME type::
 
   [attachments]
   compressible_types = text/*, application/javascript, application/json, application/xml
@@ -81,8 +81,8 @@ intervals (in seconds)::
 
 .. versionchanged:: 1.3 ``utc_id`` algorithm.
 
-CouchDB provides various algorithms to generate UUID value that will be used
-for document `_id` by default::
+CouchDB provides various algorithms to generate the UUID values that are used
+for document `_id`'s by default::
 
   [uuids]
   algorithm = sequential
@@ -109,9 +109,9 @@ Available algorithms:
     }
 
 - ``sequential``: Monotonically increasing ids with random increments.
-  First 26 hex characters are random. Last 6 increment in random amounts until
-  an overflow occurs. On overflow, the random prefix is regenerated and the
-  process starts over:
+  The first 26 hex characters are random, the last 6 increment in random
+  amounts until an overflow occurs. On overflow, the random prefix is
+  regenerated and the process starts over.
 
   .. code-block:: javascript
 
@@ -130,8 +130,8 @@ Available algorithms:
       ]
     }
 
-- ``utc_random``: Time since Jan 1, 1970 UTC with microseconds. First 14
-  characters are the time in hex. Last 18 are random:
+- ``utc_random``: The time since Jan 1, 1970 UTC, in microseconds. The first
+  14 characters are the time in hex. The last 18 are random.
 
   .. code-block:: javascript
 
@@ -150,9 +150,9 @@ Available algorithms:
       ]
     }
 
-- ``utc_id``: Time since Jan 1, 1970 UTC with microseconds,
-  plus ``utc_id_suffix`` string. First 14 characters are the time in hex.
-  :ref:`config/uuids/utc_id_suffix` string value is appended to these:
+- ``utc_id``: The time since Jan 1, 1970 UTC, in microseconds, plus
+  the ``utc_id_suffix`` string. The first 14 characters are the time in hex.
+  The :ref:`config/uuids/utc_id_suffix` string value is appended to these.
 
   .. code-block:: javascript
 
@@ -171,14 +171,15 @@ Available algorithms:
       ]
     }
 
-.. note:: **Impact of UUID choices:**
-   The choice of UUID has a significant impact on the layout of the B-tree,
-   prior to compaction.
+.. note::
 
-   For example, a sequential UUID algorithm during uploading thousands of
-   documents, will avoid the need to rewrite many intermediate B-tree nodes.
+   **Impact of UUID choices:** the choice of UUID has a significant impact on
+   the layout of the B-tree, prior to compaction.
+
+   For example, using a sequential UUID algorithm while uploading a large batch
+   of documents will avoid the need to rewrite many intermediate B-tree nodes.
    A random UUID algorithm may require rewriting intermediate nodes on a regular
-   basis, with a corresponding decrease of throughput, and significant wasted
+   basis, resulting in significantly decreased throughput and wasted disk space
    space due to the append-only B-tree design.
 
    It is generally recommended to set your own UUIDs, or use the sequential
@@ -193,9 +194,11 @@ UTC ID Suffix
 
 .. versionadded:: 1.3
 
-The utc_id_suffix value will be appended to UUIDs generated by the ``utc_id``
-algorithm. Replicating instances should have unique utc_id_suffix values to
-ensure uniqueness of ``utc_id`` ids::
+The ``utc_id_suffix`` value will be appended to UUIDs generated by the
+``utc_id`` algorithm. Replicating instances should have unique
+``utc_id_suffix`` values to ensure uniqueness of ``utc_id`` ids.
+
+::
 
   [uuid]
   utc_id_suffix = my-awesome-suffix
@@ -208,11 +211,11 @@ ensure uniqueness of ``utc_id`` ids::
 
 .. versionadded:: 1.3
 
-For CouchDB distributors there is an option to customise CouchDB's welcome
-message which is returned when requesting ``GET /``.
+CouchDB distributors have the option of customizing CouchDB's welcome
+message. This is returned when requesting ``GET /``.
+
+::
 
   [vendor]
   name = The Apache Software Foundation
   version = 1.3.0
-
-