Merge remote-tracking branch 'github/pr/27'

src/api/server/authn.rst

@@ -19,8 +19,8 @@ Authentication
 Interfaces for obtaining session and authorization data.
 
 .. note::
-    We're also strongly recommend you to :ref:`setup SSL <config/ssl>` to
-    improve all authentication methods security.
+    We also strongly recommend you :ref:`set up SSL <config/ssl>` to
+    improve all authentication methods' security.
 
 .. _api/auth/basic:
 
@@ -30,7 +30,7 @@ Basic Authentication
 `Basic authentication`_ (:rfc:`2617`) is a quick and simple way to authenticate
 with CouchDB. The main drawback is the need to send user credentials with each
 request which may be insecure and could hurt operation performance (since
-CouchDB must compute password hash with every request):
+CouchDB must compute the password hash with every request):
 
 **Request**:
 
@@ -72,10 +72,10 @@ Cookie Authentication
 For cookie authentication (:rfc:`2109`) CouchDB generates a token that the
 client can use for the next few requests to CouchDB. Tokens are valid until
 a timeout. When CouchDB sees a valid token in a subsequent request, it will
-authenticate user by this token without requesting the password again. By
+authenticate the user by this token without requesting the password again. By
 default, cookies are valid for 10 minutes, but it's :config:option:`adjustable
 <couch_httpd_auth/timeout>`. Also it's possible to make cookies
-:config:option:`persistent <couch_httpd_auth/allow_persistent_cookies>`
+:config:option:`persistent <couch_httpd_auth/allow_persistent_cookies>`.
 
 To obtain the first token and thus authenticate a user for the first time, the
 `username` and `password` must be sent to the :ref:`_session API

src/config/http-handlers.rst

@@ -56,7 +56,7 @@ Global HTTP Handlers
 
         .. note::
             Sometimes you don't want to disclose database names for everyone,
-            but you also don't like/want/able to setup any proxies in front of
+            but you also don't like/want/able to set up any proxies in front of
             CouchDB. Removing this handler disables ``_all_dbs`` resource and
             there will be no way to get list of available databases.
 
@@ -123,7 +123,7 @@ Global HTTP Handlers
             [httpd_global_handlers]
             _utils = {couch_httpd_misc_handlers, handle_utils_dir_req, "/usr/share/couchdb/www"}
 
-        In similar way, you may setup custom handler to let CouchDB serve any
+        In similar way, you may set up custom handler to let CouchDB serve any
         static files.
 
     .. config:option:: _uuids

src/config/http.rst

@@ -57,7 +57,7 @@ HTTP Server Options
             [httpd]
             bind_address = 127.0.0.1
 
-        To let CouchDB listen any available IP address, just setup ``0.0.0.0``
+        To let CouchDB listen any available IP address, just set up ``0.0.0.0``
         value::
 
             [httpd]
@@ -229,7 +229,7 @@ Secure Socket Level Options
 .. config:section:: ssl :: Secure Socket Level Options
 
     CouchDB supports SSL natively. All your secure connection needs can now be
-    served without needing to setup and maintain a separate proxy server that
+    served without needing to set up and maintain a separate proxy server that
     handles SSL.
 
     SSL setup can be tricky, but the configuration in CouchDB was designed to
@@ -263,7 +263,7 @@ Secure Socket Level Options
         [daemons]
         httpsd = {couch_httpd, start_link, [https]}
 
-    Next, under ``[ssl]`` section setup newly generated certificates::
+    Next, under the ``[ssl]`` section set up the newly generated certificates::
 
         [ssl]
         cert_file = /etc/couchdb/cert/couchdb.pem
@@ -499,7 +499,7 @@ Cross-Origin Resource Sharing
         - `Same origin policy for URIs <https://developer.mozilla.org/en-US/docs/Same-origin_policy_for_file:_URIs>`_
         - `HTTP Access Control <https://developer.mozilla.org/En/HTTP_access_control>`_
         - `Server-side Access Control <https://developer.mozilla.org/En/Server-Side_Access_Control>`_
-        - `Javascript same origin policy <https://developer.mozilla.org/en-US/docs/Same_origin_policy_for_JavaScript>`_
+        - `JavaScript same origin policy <https://developer.mozilla.org/en-US/docs/Same_origin_policy_for_JavaScript>`_
 
         Client-side CORS support and usage:
 

src/config/intro.rst

@@ -112,7 +112,7 @@ For example::
 
 Each configuration file line may contains `section` definition, `parameter`
 specification, empty (space and newline characters only) or `commented` line.
-You can setup `inline` commentaries for `sections` or `parameters`.
+You can set up `inline` commentaries for `sections` or `parameters`.
 
 The `section` defines group of parameters that are belongs to some specific
 CouchDB subsystem. For instance, :section:`httpd` section holds not only HTTP

src/config/query-servers.rst

@@ -43,7 +43,7 @@ Query Servers Definition
       query servers in wild. This value is also used for `ddoc` field
       ``language`` to determine which query server processes the functions.
 
-      Note, that you may setup multiple query servers for the same programming
+      Note, that you may set up multiple query servers for the same programming
       language, but you have to name them different (like `python-dev` etc.).
 
     - ``PATH``: is a system path to the executable binary program that runs the

src/couchapp/ddocs.rst

@@ -66,17 +66,16 @@ of a document with a `type` of "post". Note that :func:`emit` may be called many
 times for a single document, so the same document may be available by several
 different keys.
 
-Also keep in mind that each document is *sealed* to prevent situation when one
-map function changes document state and the other one received a modified
-version.
+Also keep in mind that each document is *sealed* to prevent the situation where
+one map function changes document state and another receives a modified version.
 
 For efficiency reasons, documents are passed to a group of map functions -
 each document is processed by group of map functions from all views of
 related design document. This means that if you trigger index update for one
 view in ddoc, all others will get updated too.
 
-Since `1.1.0` release `map` function supports
-:ref:`CommonJS <commonjs>` modules and access to :func:`require` function.
+Since version `1.1.0`, `map` supports :ref:`CommonJS <commonjs>` modules and
+the :func:`require` function.
 
 .. _reducefun:
 
@@ -85,42 +84,42 @@ Reduce and rereduce functions
 
 .. function:: redfun(keys, values[, rereduce])
 
-    :param keys: Array of pairs docid-key for related map function result.
+    :param keys: Array of pairs of docid-key for related map function results.
                  Always ``null`` if rereduce is running (has ``true`` value).
     :param values: Array of map function result values.
     :param rereduce: Boolean sign of rereduce run.
 
     :return: Reduces `values`
 
 Reduce functions takes two required arguments of keys and values lists - the
-result of the related map function - and optional third one which indicates if
-`rereduce` mode is active or not. `Rereduce` is using for additional reduce
+result of the related map function - and an optional third value which indicates
+if `rereduce` mode is active or not. `Rereduce` is used for additional reduce
 values list, so when it is ``true`` there is no information about related `keys`
 (first argument is ``null``).
 
-Note, that if produced result by `reduce` function is longer than initial
+Note that if the result of a `reduce` function is longer than the initial
 values list then a Query Server error will be raised. However, this behavior
-could be disabled by setting ``reduce_limit`` config option to ``false``:
+can be disabled by setting ``reduce_limit`` config option to ``false``:
 
 .. code-block:: ini
 
     [query_server_config]
     reduce_limit = false
 
-While disabling ``reduce_limit`` might be useful for debug proposes, remember,
-that main task of reduce functions is to *reduce* mapped result, not to make it
-even bigger. Generally, your reduce function should converge rapidly to a single
-value - which could be an array or similar object.
+While disabling ``reduce_limit`` might be useful for debug proposes, remember
+that the main task of reduce functions is to *reduce* the mapped result, not to
+make it bigger. Generally, your reduce function should converge rapidly to a
+single value - which could be an array or similar object.
 
 .. _reducefun/builtin:
 
 Builtin reduce functions
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 Additionally, CouchDB has three built-in reduce functions. These are implemented
-in Erlang and runs inside CouchDB, so they are much faster than the equivalent
+in Erlang and run inside CouchDB, so they are much faster than the equivalent
 JavaScript functions: ``_sum``, ``_count`` and ``_stats``. Their equivalents in
-JavaScript below:
+JavaScript:
 
 .. code-block:: javascript
 
@@ -171,26 +170,26 @@ JavaScript below:
     **Why don't reduce functions support CommonJS modules?**
 
     While `map` functions have limited access to stored modules through
-    :func:`require` function there is no such feature for `reduce` functions.
-    The reason lies deep inside in the mechanism how `map` and `reduce`
-    functions are processed by the Query Server. Let's take a look on `map`
+    :func:`require`, there is no such feature for `reduce` functions.
+    The reason lies deep inside the way `map` and `reduce`
+    functions are processed by the Query Server. Let's take a look at `map`
     functions first:
 
     #. CouchDB sends all `map` functions for a processed design document to
        Query Server.
     #. Query Server handles them one by one, compiles and puts them onto an
        internal stack.
-    #. After all `map` functions had been processed, CouchDB will send the
-       remaining documents to index one by one.
+    #. After all `map` functions have been processed, CouchDB will send the
+       remaining documents to index, one by one.
     #. Query Server receives the document object and applies it to every
        function from the stack. The emitted results are then joined into a
        single array and sent back to CouchDB.
 
     Now let's see how `reduce` functions are handled:
 
     #. CouchDB sends *as single command* list of available `reduce` functions
-       with result list of key-value pairs that was previously received as
-       result of `map` functions work.
+       with result list of key-value pairs that was previously received as the
+       result of `map` functions' work.
     #. Query Server compiles reduce functions and applies them to key-value
        lists. Reduced result is sent back to CouchDB.
 
@@ -217,7 +216,7 @@ Show functions
     :rtype: object or string
 
 Show functions are used to represent documents in various formats, commonly as
-HTML page with nicer formatting. They can also be used to run server-side
+HTML pages with nice formatting. They can also be used to run server-side
 functions without requiring a pre-existing document.
 
 Basic example of show function could be:
@@ -397,8 +396,8 @@ Update functions
     :returns: Two-element array: the first element is the (updated or new)
       document, which is committed to the database. If the first element
       is ``null`` no document will be committed to the database.
-      If you are updating an existing, it should already have an ``_id``
-      set, and if you are creating a new document, make sure to set its
+      If you are updating an existing document, it should already have an
+      ``_id`` set, and if you are creating a new document, make sure to set its
       ``_id`` to something, either generated based on the input or the
       ``req.uuid`` provided. The second element is the response that will
       be sent back to the caller.
@@ -491,7 +490,7 @@ about "new mails"::
     ],
     "last_seq":27}
 
-Note that the value of ``last_seq`` is 27, but we'd received only two records.
+Note that the value of ``last_seq`` is 27, but we received only two records.
 Seems like any other changes were for documents that haven't passed our filter.
 
 We probably need to filter the changes feed of our mailbox by more than a single
@@ -501,7 +500,7 @@ mails, and so on. Creating a lot of similar functions that actually do similar
 work isn't good idea - so we need a dynamic filter.
 
 You may have noticed that filter functions take a second argument named
-:ref:`request <request_object>` - it allows creating dynamic filters
+:ref:`request <request_object>`. This allows the creation of dynamic filters
 based on query parameters, :ref:`user context <userctx_object>` and more.
 
 The dynamic version of our filter looks like this:
@@ -554,8 +553,8 @@ View filters
 
 View filters are the same as above, with one small difference: they use
 views `map` function instead to `filter` one to process the changes feed. Each
-time when a key-value pair could be emitted, a change is returned. This allows
-to avoid creating filter functions that are mostly does same works as views.
+time a key-value pair could be emitted, a change is returned. This allows us
+to avoid creating filter functions that mostly do the same works as views.
 
 To use them just specify `_view` value for ``filter`` parameter and
 `designdoc/viewname` for ``view`` one::
@@ -752,7 +751,7 @@ modified by a user with the ``_admin`` role:
     }
 
 .. note::
-    The ``return`` statement used only for function, it has no impact on
+    The ``return`` statement is used only for function, it has no impact on
     the validation process.
 
 .. seealso::

src/couchapp/views/intro.rst

@@ -12,9 +12,9 @@
 
 .. _views/intro:
 
-===========================
-Introduction Into The Views
-===========================
+=====================
+Introduction to Views
+=====================
 
 Views are useful for many purposes:
 
@@ -418,8 +418,8 @@ on the ``rereduce`` parameter:
     }
 
 .. note::
-    JavaScript function about could be effectively replaced by builtin
-    ``_count`` one.
+    The JavaScript function above could be effectively replaced by the builtin
+    ``_count``.
 
 .. figure:: ../../../images/views-intro-01.png
     :align: center
@@ -460,7 +460,7 @@ number ``1`` for each key, as there are no exactly duplicated keys.
 Reduce/Rereduce
 ===============
 
-We briefly talked about the ``rereduce`` parameter to your reduce function.
+We briefly talked about the ``rereduce`` parameter to the reduce function.
 We’ll explain what’s up with it in this section. By now, you should have learned
 that your view result is stored in B-tree index structure for efficiency.
 The existence and use of the ``rereduce`` parameter is tightly coupled to how
@@ -541,7 +541,7 @@ the beginning and the end are the same value). It concludes that it has to use
 the "chinese" element’s value and the other node’s value and run them through
 the reduce function with the ``rereduce`` parameter set to true.
 
-The reduce function effectively calculates 3 + 1 on query time and returns the
+The reduce function effectively calculates 3 + 1 at query time and returns the
 desired result. The next example shows some pseudocode that shows the last
 invocation of the reduce function with actual values:
 
@@ -591,7 +591,7 @@ This translates to Figure 4, “An overflowing reduce index”.
 
 We hope you get the picture. The way the B-tree storage works means that if you
 don’t actually reduce your data in the reduce function, you end up having
-CouchDB copy huge amounts of data around that grow linearly, if not faster
+CouchDB copy huge amounts of data around that grow linearly, if not faster,
 with the number of rows in your view.
 
 CouchDB will be able to compute the final result, but only for views with a few

src/couchapp/views/joins.rst

@@ -163,11 +163,11 @@ Using View Collation
 :Date: 2007-10-05
 :Source: http://www.cmlenz.net/archives/2007/10/couchdb-joins
 
-Just today, there was a discussion on IRC how you'd go about modeling a simple
-blogging system with “post” and “comment” entities, where any blog post might
-have N comments. If you'd be using an SQL database, you'd obviously have two
-tables with foreign keys and you'd be using joins. (At least until you needed
-to add some `denormalization`_).
+Just today, there was a discussion on IRC on how you'd go about modeling a
+simple blogging system with “post” and “comment” entities, where any blog
+post might have N comments. If you'd be using an SQL database, you'd obviously
+have two tables with foreign keys and you'd be using joins. (At least until you
+needed to add some `denormalization`_).
 
 .. _denormalization: http://en.wikipedia.org/wiki/Denormalization
 
@@ -195,7 +195,7 @@ comments inside that document:
 
 .. note::
     Of course the model of an actual blogging system would be more extensive,
-    you'd have tags, timestamps, etc etc. This is just to demonstrate the basics.
+    you'd have tags, timestamps, etc, etc. This is just to demonstrate the basics.
 
 The obvious advantage of this approach is that the data that belongs together
 is stored in one place. Delete the post, and you automatically delete the
@@ -256,7 +256,7 @@ can tell the difference between posts and comments:
     }
 
 The comments themselves are stored in separate documents, which also have a type
-property (this time with the value “comment”), and in addition feature a post
+property (this time with the value “comment”), and additionally feature a post
 property containing the ID of the post document they belong to:
 
 .. code-block:: javascript
@@ -312,7 +312,7 @@ CouchDB server, namely a ``GET`` request to the document. With this second
 approach, we need two requests: a ``GET`` request to the post document, and a
 ``GET`` request to the view that returns all comments for the post.
 
-That is okay, but not quite satisfactory. Just imagine you wanted to added
+That is okay, but not quite satisfactory. Just imagine you wanted to add
 threaded comments: you'd now need an additional fetch per comment. What we'd
 probably want then would be a way to join the blog post and the various comments
 together to be able to retrieve them with a single HTTP request.
@@ -402,8 +402,8 @@ the following:
     }
 
 .. note::
-    The ``...`` placeholder here would contain the complete JSON encoding of the
-    corresponding document
+    The ``...`` placeholders here would contain the complete JSON encoding of the
+    corresponding documents
 
 Now, to get a specific blog post and all associated comments, we'd invoke that
 view with the query string::