You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by ja...@apache.org on 2013/08/21 11:57:53 UTC
[1/2] git commit: updated refs/heads/1781-reorganize-and-improve-docs
to d3c0a82
Updated Branches:
refs/heads/1781-reorganize-and-improve-docs cb7844722 -> d3c0a82a1
change some language from mailing-list post to doc
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/f63013fd
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/f63013fd
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/f63013fd
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: f63013fd99318566eb4365b5d34139de0e97fb16
Parents: cb78447
Author: Jan Lehnardt <ja...@apache.org>
Authored: Wed Aug 21 08:31:01 2013 +0200
Committer: Jan Lehnardt <ja...@apache.org>
Committed: Wed Aug 21 08:31:01 2013 +0200
----------------------------------------------------------------------
share/doc/src/api/basics.rst | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/f63013fd/share/doc/src/api/basics.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/basics.rst b/share/doc/src/api/basics.rst
index dbd486a..dd64257 100644
--- a/share/doc/src/api/basics.rst
+++ b/share/doc/src/api/basics.rst
@@ -340,7 +340,7 @@ is exactly what almost all other languages use as well.
.. _IEEE 754: https://en.wikipedia.org/wiki/IEEE_754-2008
-What CouchDB does a bit differently than other languages is that it
+What Erlang does a bit differently than other languages is that it
does not attempt to pretty print the resulting output to use the
shortest number of characters. For instance, this is why we have this
relationship:
@@ -353,7 +353,7 @@ relationship:
What can be confusing here is that internally those two formats
decode into the same IEEE-754 representation. And more importantly, it
will decode into a fairly close representation when passed through all
-major parsers that I know about.
+major parsers that we know about.
While we've only been discussing cases where the textual
representation changes, another important case is when an input value
@@ -361,8 +361,8 @@ is contains more precision than can actually represented in a double.
(You could argue that this case is actually "losing" data if you don't
accept that numbers are stored in doubles).
-Here's a log for a couple of the more common JSON libraries I happen
-to have on my machine:
+Here's a log for a couple of the more common JSON libraries that happen
+to be on the author's machine:
Spidermonkey::
@@ -482,11 +482,11 @@ string or by using integer types (although integer types can still
bite you if you use a platform that has a different integer
representation than normal, ie, JavaScript).
-Also, if anyone is really interested in changing this behavior, I'm
+Also, if anyone is really interested in changing this behavior, we're
all ears for contributions to `jiffy`_ (which is theoretically going to
-replace ejson when I get around to updating the build system). The
-places I've looked for inspiration are TCL and Python. If you know a
-decent implementation of this float printing algorithm give me a
+replace ejson when we get around to updating the build system). The
+places we've looked for inspiration are TCL and Python. If you know a
+decent implementation of this float printing algorithm give us a
holler.
.. _jiffy: https://github.com/davisp/jiffy
[2/2] git commit: updated refs/heads/1781-reorganize-and-improve-docs
to d3c0a82
Posted by ja...@apache.org.
various language improvements
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/d3c0a82a
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/d3c0a82a
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/d3c0a82a
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: d3c0a82a199f7407f1e214b3d7c7d2742f96f738
Parents: f63013f
Author: Jan Lehnardt <ja...@apache.org>
Authored: Wed Aug 21 09:59:23 2013 +0200
Committer: Jan Lehnardt <ja...@apache.org>
Committed: Wed Aug 21 11:53:49 2013 +0200
----------------------------------------------------------------------
share/doc/ext/github.pyc | Bin 0 -> 1379 bytes
share/doc/src/api/database/bulk-docs.rst | 5 +-
share/doc/src/api/server/authn.rst | 34 ++++-----
share/doc/src/config/auth.rst | 20 +++--
share/doc/src/config/compaction.rst | 24 +++---
share/doc/src/config/couchdb.rst | 6 +-
share/doc/src/config/externals.rst | 2 +-
share/doc/src/config/http-handlers.rst | 17 +++--
share/doc/src/config/http.rst | 26 +++----
share/doc/src/config/intro.rst | 16 ++--
share/doc/src/config/misc.rst | 10 +--
share/doc/src/config/query-servers.rst | 13 ++--
share/doc/src/install/windows.rst | 10 +--
share/doc/src/query-server/protocol.rst | 102 +++++++++++++-------------
14 files changed, 140 insertions(+), 145 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d3c0a82a/share/doc/ext/github.pyc
----------------------------------------------------------------------
diff --git a/share/doc/ext/github.pyc b/share/doc/ext/github.pyc
new file mode 100644
index 0000000..a6f95a3
Binary files /dev/null and b/share/doc/ext/github.pyc differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d3c0a82a/share/doc/src/api/database/bulk-docs.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/bulk-docs.rst b/share/doc/src/api/database/bulk-docs.rst
index 32253e6..2830e1d 100644
--- a/share/doc/src/api/database/bulk-docs.rst
+++ b/share/doc/src/api/database/bulk-docs.rst
@@ -32,9 +32,8 @@
* **true**: Ensures that any non-committed changes are committed to
physical storage.
- * **false**: Uses the delay commit in opposite to ``true`` value. CouchDB
- responses quickly, but without any guarantees that all data are
- successfully stored on disk.
+ * **false**: Uses delayed commits. CouchDB responds faster, but without
+ any guarantees that all data is successfully stored on disk.
* **Return Codes**:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d3c0a82a/share/doc/src/api/server/authn.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/authn.rst b/share/doc/src/api/server/authn.rst
index 083a262..337769c 100644
--- a/share/doc/src/api/server/authn.rst
+++ b/share/doc/src/api/server/authn.rst
@@ -41,10 +41,10 @@ A list of the available methods and URL paths are provided below:
Basic Authentication
====================
-`Basic authentication`_ (:rfc:`2617`) is a quick and simple way to be
-authenticated by CouchDB. The main flaw of this simplicity is the need to send
-user credentials with each request which may be insecure and hurts operations
-performance (since CouchDB must compute password hash with every request):
+`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):
.. code-block:: http
@@ -82,12 +82,12 @@ performance (since CouchDB must compute password hash with every request):
Cookie Authentication
=====================
-For cookie authentication (:rfc:`2109`) CouchDB generates a one-time token that
-the client can use for next requests to CouchDB. When CouchDB sees non expired
-the token in a subsequent request, it will authenticate user by this token
-without requesting the password again. By default, cookies are valid for
-10 minutes, but it's :ref:`adjustable <config/couch_httpd_auth/timeout>`.
-Also it's possible to make cookies
+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
+default, cookies are valid for 10 minutes, but it's :ref:`adjustable
+<config/couch_httpd_auth/timeout>`. Also it's possible to make cookies
:ref:`persistent <config/couch_httpd_auth/allow_persistent_cookies>`
To obtain the first token and thus authenticate a user for the first time, the
@@ -213,7 +213,7 @@ to the specified location in case of successful authentication:
* **401**:
Username or password wasn't recognized.
-Returns complete information about authenticated user:
+Returns complete information about the authenticated user:
.. code-block:: http
@@ -264,7 +264,7 @@ available ones and authentication database.
* **401**:
Username or password wasn't recognized.
-Closes user's session. If everything is ok, the response is:
+Closes a user's session. If everything is ok, the response is:
.. code-block:: javascript
@@ -288,8 +288,8 @@ Proxy Authentication
authentication_handlers = {couch_httpd_oauth, oauth_authentication_handler}, {couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, proxy_authentication_handler}, {couch_httpd_auth, default_authentication_handler}
-`Proxy authentication` is very useful in case when your application is already
-uses some external authentication service and you won't duplicate users and
+`Proxy authentication` is very useful in case your application already uses
+some external authentication service and you don't want to duplicate users and
their roles in CouchDB.
This authentication method allows creation of a :ref:`userctx_object` for
@@ -349,7 +349,7 @@ CouchDB sends the response:
}
-Note, that you don't need to request :ref:`session <api/auth/session>` resource
+Note that you don't need to request :ref:`session <api/auth/session>`
to be authenticated by this method if all required HTTP headers are provided.
@@ -455,6 +455,6 @@ Both snippets produces similar request and response pair:
}
}
-There we'd requested the :ref:`_session <api/auth/session>` resource to ensure
-that authentication was successful and target CouchDB username is correct.
+There we request the :ref:`_session <api/auth/session>` resource to ensure
+that authentication was successful and the target CouchDB username is correct.
Change the target URL to request required resource.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d3c0a82a/share/doc/src/config/auth.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/auth.rst b/share/doc/src/config/auth.rst
index e457647..410ae46 100644
--- a/share/doc/src/config/auth.rst
+++ b/share/doc/src/config/auth.rst
@@ -130,7 +130,7 @@ Number of :ref:`userctx_object` to cache in memory to reduce disk lookups::
``authentication_db`` :: Users database
---------------------------------------
-Specifies 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
@@ -145,8 +145,8 @@ Specifies name of the system database for storing CouchDB users::
``authentication_redirect`` :: Default redirect for authentication requests
---------------------------------------------------------------------------
-Specifies location for redirection on successful authentication if ``text/html``
-response accepted by client (via ``Accept`` header)::
+Specifies the location for redirection on successful authentication if a
+``text/html`` response is accepted by the client (via ``Accept`` header)::
[couch_httpd_auth]
authentication_redirect = /_utils/session.html
@@ -159,9 +159,8 @@ response accepted by client (via ``Accept`` header)::
.. versionadded:: 1.3
-Number of iterations for password hashing by PBKDF2 algorithm. Higher number
-provides better hash durability, but with cost of performance on each request
-that requires authentication::
+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::
[couch_httpd_auth]
iterations = 10000
@@ -172,8 +171,8 @@ that requires authentication::
``proxy_use_secret`` :: Force proxy auth use secret token
---------------------------------------------------------
-When this option ``true`` the :ref:`secret <config/couch_httpd_auth/secret>` is
-required for :ref:`api/auth/proxy`::
+When this option is ``true`` the :ref:`secret <config/couch_httpd_auth/secret>`
+is required for :ref:`api/auth/proxy`::
[couch_httpd_auth]
proxy_use_secret = false
@@ -203,14 +202,13 @@ If unset or not specified, authenticated users may retrieve only their own docs.
[couch_httpd_auth]
users_db_public = true
-
.. _config/couch_httpd_auth/require_valid_user:
``require_valid_user`` :: Force users authentication
----------------------------------------------------
-When this option ``true`` no requests allowed from anonymous users - everyone
-should be authenticated::
+When this option ``true`` no requests allowed from anonymous users. Everyone
+must be authenticated::
[couch_httpd_auth]
require_valid_user = false
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d3c0a82a/share/doc/src/config/compaction.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/compaction.rst b/share/doc/src/config/compaction.rst
index 085f829..c9216c8 100644
--- a/share/doc/src/config/compaction.rst
+++ b/share/doc/src/config/compaction.rst
@@ -26,7 +26,7 @@ Compaction Configuration
``doc_buffer_size`` :: Documents buffer size
--------------------------------------------
-Specifies maximum copy buffer size in bytes::
+Specifies the copy buffer's maximum size in bytes::
[database_compaction]
doc_buffer_size = 524288
@@ -37,8 +37,8 @@ Specifies maximum copy buffer size in bytes::
``checkpoint_after`` :: Checkpoint trigger
------------------------------------------
-Triggers checkpoint after special amount of bytes was successfully copied to
-the compacted database::
+Triggers a checkpoint after the specified amount of bytes were successfully
+copied to the compacted database::
[database_compaction]
checkpoint_after = 5242880
@@ -68,20 +68,20 @@ For example::
Possible parameters:
-- ``db_fragmentation``: If the ratio (as an integer percentage), of the amount
- of old data (and its supporting metadata) over the database file size is equal
- to or greater then this value, this database compaction condition is
- satisfied. This value is computed as::
+- ``db_fragmentation``: If the ratio of legacy data, including metadata, to
+ current data in the database file size is equal to or greater then this
+ value, this database compaction condition is satisfied. The percentage is
+ expressed as an integer percentage. This value is computed as::
(file_size - data_size) / file_size * 100
The data_size and file_size values can be obtained when
querying a :ref:`database's information URI <api/db.get>`.
-- ``view_fragmentation``: If the ratio (as an integer percentage), of the amount
- of old data (and its supporting metadata) over the view index (view group)
- file size is equal to or greater then this value, then this view index
- compaction condition is satisfied. This value is computed as::
+- ``view_fragmentation``: If the ratio of legacy data, including metadata, to
+ current data in a view index file size is equal to or greater then this
+ value, this database compaction condition is satisfied. The percentage is
+ expressed as an integer percentage. This value is computed as::
(file_size - data_size) / file_size * 100
@@ -104,7 +104,7 @@ Possible parameters:
It defaults to `false`.
Before a compaction is triggered, an estimation of how much free disk space is
-needed is computed. This estimation corresponds to 2 times the data size of
+needed is computed. This estimation corresponds to two times the data size of
the database or view index. When there's not enough free disk space to compact
a particular database or view index, a warning message is logged.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d3c0a82a/share/doc/src/config/couchdb.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/couchdb.rst b/share/doc/src/config/couchdb.rst
index 56bdb6f..053f7e9 100644
--- a/share/doc/src/config/couchdb.rst
+++ b/share/doc/src/config/couchdb.rst
@@ -99,9 +99,9 @@ section). Available methods are:
``fsync_options`` :: Fsync options
----------------------------------
-Conditions when to make `fsync` calls. `fsync` makes sure that any 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 any file system
+buffers kept by the operating system are written to disk. Normally, you have no
+need to edit this parameter::
[couchdb]
fsync_options = [before_header, after_header, on_file_open]
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d3c0a82a/share/doc/src/config/externals.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/externals.rst b/share/doc/src/config/externals.rst
index adbaea7..d4a8eab 100644
--- a/share/doc/src/config/externals.rst
+++ b/share/doc/src/config/externals.rst
@@ -112,7 +112,7 @@ see :ref:`http-proxying`. For further background on the OS Daemon service, see
------------------------------------------
Specifies maximum attempts to run :ref:`os_daemon <config/os_daemons>` before
-mark him halted::
+mark them halted::
[os_daemon_settings]
max_retries = 3
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d3c0a82a/share/doc/src/config/http-handlers.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/http-handlers.rst b/share/doc/src/config/http-handlers.rst
index 19ef17c..7da653d 100644
--- a/share/doc/src/config/http-handlers.rst
+++ b/share/doc/src/config/http-handlers.rst
@@ -61,7 +61,7 @@ The favicon handler looks for `favicon.ico` file within specified directory::
:ref:`_all_dbs <api/server/all_dbs>`
------------------------------------
-Provides list of all server's databases::
+Provides a list of all server's databases::
[httpd_global_handlers]
_all_dbs = {couch_httpd_misc_handlers, handle_all_dbs_req}
@@ -73,7 +73,7 @@ Provides list of all server's databases::
this handler disables ``_all_dbs`` resource and there will be no way to get
list of available databases.
- Same also is true for other resource handlers.
+ The s`ame also is true for other resource handlers.
.. _config/httpd_global_handlers/_config:
@@ -116,7 +116,7 @@ and doesn't requires server instance to be restarted::
:ref:`_replicate <api/server/replicate>`
----------------------------------------
-Provides API to run :ref:`temporary replications <api/server/replicate>`::
+Provides an API to run :ref:`temporary replications <api/server/replicate>`::
[httpd_global_handlers]
_replicate = {couch_replicator_httpd, handle_req}
@@ -138,7 +138,7 @@ Provides API to run :ref:`temporary replications <api/server/replicate>`::
``_session``
------------
-Provides resource with information about current user's session::
+Provides a resource with information about the current user's session::
[httpd_global_handlers]
_session = {couch_httpd_auth, handle_session_req}
@@ -166,7 +166,7 @@ page::
[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 on disk static
+In similar way, you may setup custom handler to let CouchDB serve any static
files.
@@ -175,19 +175,20 @@ files.
:ref:`_uuids <api/server/uuids>`
--------------------------------
-Provides resource to get UUIDs generated on server side::
+Provides a resource to get UUIDs generated by CouchDB::
[httpd_global_handlers]
_uuids = {couch_httpd_misc_handlers, handle_uuids_req}
+This is useful when your client environment isn't capable of providing truly
+random IDs (web browsers e.g.).
.. _config/httpd_db_handlers:
``[httpd_db_handlers]`` :: Database HTTP Handlers
=================================================
-These HTTP resources are provided for CouchDB database level in context of the
-related one.
+These HTTP resources are available on every CouchDB database.
.. _config/httpd_db_handlers/_all_docs:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d3c0a82a/share/doc/src/config/http.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/http.rst b/share/doc/src/config/http.rst
index 6c7e0ba..3c86585 100644
--- a/share/doc/src/config/http.rst
+++ b/share/doc/src/config/http.rst
@@ -170,14 +170,14 @@ After that, CouchDB URI could be located within the URI file.
``redirect_vhost_handler`` :: Virtual Hosts custom redirect handler
-------------------------------------------------------------------
-This option allows to change the default function that handles requests to
+This option customizes the default function that handles requests to
:ref:`virtual hosts <config/vhosts>`::
[httpd]
redirect_vhost_handler = {Module, Fun}
-Specified function take 2 arguments: the Mochiweb request object and the target
-path.
+The specified function take 2 arguments: the Mochiweb request object and the
+target path.
.. _config/httpd/server_options:
@@ -648,21 +648,22 @@ Finally, add an entry to your :ref:`configuration file <config>` in the
couchdb.local:5984 = /example
*.couchdb.local:5984 = /example
-If your CouchDB is listening on the default HTTP port, or is sitting
-behind a proxy, then don't specify a port number in the `vhost` key.
+If your CouchDB is listening on the the default HTTP port (80), or is sitting
+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`. Second rule on the other hand match 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 `www.couchdb.local` or `db.couchdb.local` will
+work.
.. _config/vhosts/rewriting:
-Rewriting Hosts to path
------------------------
+Rewriting Hosts to a Path
+-------------------------
-Like in the :ref:`_rewrite <api/ddoc/rewrite>` handler you could match some
+Like in the :ref:`_rewrite <api/ddoc/rewrite>` handler you can match some
variable and use them to create the target path. Some examples::
[vhosts]
@@ -671,9 +672,8 @@ variable and use them to create the target path. Some examples::
:ddocname.:dbname.example.com = /:dbname/_design/:ddocname/_rewrite
-First rule pass wildcard as `dbname`. The second one does the same, but uses a
-variable name. And the third one allows you to use any app with `ddocname` in
-any database with `dbname`.
+The first rule passes the wildcard as `dbname`. The second one does the same,
+but uses a variable name. And the third one allows you to use any URL with `ddocname` in any database with `dbname`.
You could also change the default function to handle request by changing
the setting :ref:`redirect_vhost_handler <config/httpd/redirect_vhost_handler>`
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d3c0a82a/share/doc/src/config/intro.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/intro.rst b/share/doc/src/config/intro.rst
index b3843bd..f8cffbe 100644
--- a/share/doc/src/config/intro.rst
+++ b/share/doc/src/config/intro.rst
@@ -158,11 +158,11 @@ easy to make CouchDB unavailable. For instance, you'd like to change the
curl -X PUT http://localhost:5984/_config/httpd/bind_address -d '"10.10.0.128"'
-Whatever if you'd made a typo or the specified IP address is not available from
-your network, you'll make CouchDB unavailable for you in both cases and you will
-have the only way to fix the problem by edit the configuration file and restart
-the server. To protect yourself against such accidents you may setup the
-:ref:`whilelist <config/httpd/config_whitelist>` of configuration parameters
-that are allowed to edit via the HTTP API. For others you'll need to directly
-edit the configuration file so you may quick fix any problems that had occurred
-due to misconfiguring.
+However, if you would made a typo or the specified IP address is not available
+from your network, you'll make CouchDB unavailable for you in both cases and
+you will have the only way to fix the problem by edit the configuration file
+and restart the server. To protect yourself against such accidents you may
+setup the :ref:`whilelist <config/httpd/config_whitelist>` of configuration
+parameters that are allowed to edit via the HTTP API. For others you'll need to
+directly edit the configuration file so you may quick fix any problems that had
+occurred due to misconfiguring.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d3c0a82a/share/doc/src/config/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/misc.rst b/share/doc/src/config/misc.rst
index 7e974ee..b373496 100644
--- a/share/doc/src/config/misc.rst
+++ b/share/doc/src/config/misc.rst
@@ -38,8 +38,8 @@ to ``9`` (highest, slowest). ``0`` value disables compression::
``compressible_types``
----------------------
-While not all attached files could be compressed well, it's possible to let
-CouchDB compress only specific attachments according by their MIME type::
+While not all attached files could be compressed well, it is possible to let
+CouchDB compress only specific attachments identified by their MIME type::
[attachments]
compressible_types = text/*, application/javascript, application/json, application/xml
@@ -66,7 +66,7 @@ Rate of statistics gathering in milliseconds::
``samples``
-----------
-Samples are used tracks the mean and standard value deviation within specified
+Samples are used to track the mean and standard value deviation within specified
intervals (in seconds)::
[stats]
@@ -194,8 +194,8 @@ ensure uniqueness of ``utc_id`` ids::
.. versionadded:: 1.3
-For CouchDB distributors there is option to explicitly define this information
-in welcome message::
+For CouchDB distributors there is an option to customise CouchDB's welcome
+message which is returned when requesting ``GET /``.
[vendor]
name = The Apache Software Foundation
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d3c0a82a/share/doc/src/config/query-servers.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/query-servers.rst b/share/doc/src/config/query-servers.rst
index 5462753..0dbe5c8 100644
--- a/share/doc/src/config/query-servers.rst
+++ b/share/doc/src/config/query-servers.rst
@@ -77,8 +77,8 @@ running via `Mozilla SpiderMonkey`_::
``commit_freq`` :: View index commit delay
------------------------------------------
-Specifies delay in seconds (``5`` by default) before commit view index changes
-on disk::
+Specifies the delay in seconds before view index changes are committed to disk.
+The default value is ``5``::
[query_server_config]
commit_freq = 5
@@ -94,8 +94,8 @@ Amount of time in seconds that the Query Server may process CouchDB command::
[query_server_config]
os_process_limit = 10
-CouchDB will raise `os_process_timeout` error and kill the process in case when
-Query Server doesn't return any result within this time frame.
+CouchDB will raise `os_process_timeout` error and kill the process in case the
+Query Server doesn't return any result within this limit.
.. _config/query_server_config/reduce_limit:
@@ -130,8 +130,7 @@ since main propose of `reduce` functions is to *reduce* the input.
about running them, especially if they were written by someone else.
CouchDB has a native Erlang query server, allowing you to write your map/reduce
-functions in Erlang. There is need no longer to manually install `erlview`_,
-unless you are running an old version (pre 0.10) of CouchDB.
+functions in Erlang.
First, you'll need to edit your `local.ini` to include a
``[native_query_servers]`` section::
@@ -163,5 +162,3 @@ following functions as a temporary view:
If all has gone well, after running the view you should see a list of the total
number of documents at each revision number.
-
-.. _erlview: https://github.com/mmcdanie/erlview
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d3c0a82a/share/doc/src/install/windows.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/install/windows.rst b/share/doc/src/install/windows.rst
index 79bbb87..ad0bfeb 100644
--- a/share/doc/src/install/windows.rst
+++ b/share/doc/src/install/windows.rst
@@ -22,7 +22,7 @@ There are two ways to install CouchDB on Windows.
Installation from binaries
==========================
-This is the most simplest way to go.
+This is the simplest way to go.
#. Get `the latest Windows binaries`_ from `CouchDB web site`_.
Old releases are available at `archive`_.
@@ -50,13 +50,13 @@ This is the most simplest way to go.
.. note:: **Upgrading note**
- It's very recommended to uninstall previous CouchDB version before upgrading,
+ It's recommended to uninstall previous CouchDB version before upgrading,
especially if the new one is built against different Erlang release.
- The reason is simple: there may left a some of libraries with alternative or
+ The reason is simple: there may be leftover libraries with alternative or
incompatible versions from old Erlang release that may create conflicts,
- errors and weird crushes.
+ errors and weird crashes.
- In this case, make sure you'd backup of your `local.ini` config and CouchDB
+ In this case, make sure you backup of your `local.ini` config and CouchDB
database/index files.
.. _Open up Futon: http://localhost:5984/_utils
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d3c0a82a/share/doc/src/query-server/protocol.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/query-server/protocol.rst b/share/doc/src/query-server/protocol.rst
index 9bc72e7..b7d8718 100644
--- a/share/doc/src/query-server/protocol.rst
+++ b/share/doc/src/query-server/protocol.rst
@@ -17,18 +17,18 @@
Query Server Protocol
=====================
-The `Query server` is external process that communicates with CouchDB by JSON
-protocol through stdio interface and processed all design functions calls:
+The `Query Server` is an external process that communicates with CouchDB via a
+JSON protocol over stdio and processes all design functions calls:
`views`, `shows`, `lists`, `filters`, `updates` and `validate_doc_update`.
-CouchDB communicates with Query Server process though stdio interface by JSON
-messages that terminated by newline character. Messages that are sent to QS
-always `array`-typed that could be matched by the pattern
+CouchDB communicates with the Query Server process though stdio interface by
+JSON messages that terminated by newline character. Messages that are sent to
+the Query Server are always `array`-typed that could be matched by the pattern
``[<command>, <*arguments>]\n``.
.. note::
- To simplify examples reading we'd omitted trailing ``\n`` character to let
- Sphinx highlight them well. Also, all examples contains formatted JSON values
+ To simplify examples reading we omitted trailing ``\n`` character to let
+ Sphinx highlight them well. Also, all examples contain formatted JSON values
while real data transfers in compact mode without formatting spaces.
.. _qs/reset:
@@ -91,9 +91,9 @@ The Query Server answers::
.. note::
- This library shouldn't have any side effects nor track his own state
+ This library shouldn't have any side effects nor track its own state
or you'll have a lot of happy debugging time if something went wrong.
- Remember, that complete index rebuilding is heavy cost operation and this is
+ Remember that a complete index rebuild is a heavy operation and this is
the only way to fix your mistakes with shared state.
.. _qs/add_fun:
@@ -105,11 +105,11 @@ The Query Server answers::
:Arguments: Map function source code.
:Returns: ``true``
-When creating or updating a view, the Query Server gets sent the view function
-for evaluation. The Query Server should parse/compile/evaluate the function he
-receives to make it callable later. If this fails, the Query Server returns an
-error. CouchDB might store several functions before sending in any actual
-documents.
+When creating or updating a view the Query Server gets sent the view function
+for evaluation. The Query Server should parse, compile and evaluate the
+function it receives to make it callable later. If this fails, the Query Server
+returns an error. CouchDB might store several functions before sending in any
+actual documents.
CouchDB sends::
@@ -134,7 +134,7 @@ The Query Server answers::
When the view function is stored in the Query Server, CouchDB starts sending in
all the documents in the database, one at a time. The Query Server calls the
-previously stored functions one after another with the document and stores its
+previously stored functions one after another with a document and stores its
result. When all functions have been called, the result is returned as a JSON
string.
@@ -288,8 +288,8 @@ The Query Server answers::
This command acts in two phases: `ddoc` registration and `design function`
execution.
-On first phase CouchDB sends full design document content to the Query Server to
-let him cache it be ``_id`` value for further functions execution.
+In the first phase CouchDB sends a full design document content to the Query
+Server to let it cache it by ``_id`` value for further function execution.
To do this, CouchDB sends::
@@ -438,16 +438,16 @@ The Query Server sends::
Executes :ref:`list function <listfun>`.
The communication protocol for `list` functions is a bit complex so let's use
-some example to have a talk about real things.
+an example for illustration.
-Let assume, that we have view function, that emits document's `id-rev` pairs::
+Let's assume that we have view a function that emits `id-rev` pairs::
function(doc) {
emit(doc._id, doc._rev);
}
And we'd like to emulate ``_all_docs`` JSON response with list function. Our
-*first* version of the list functions will be the next::
+*first* version of the list functions looks like this::
function(head, req){
start({'headers': {'Content-Type': 'application/json'}});
@@ -472,8 +472,8 @@ on three parts:
Where ``<chunks>`` is an array of text chunks that will be sent to client
and ``<headers>`` is an object with response HTTP headers.
- This message sends from Query Server to the CouchDB on :js:func:`start` call
- which initialize HTTP response to the client::
+ This message is sent from the Query Server to CouchDB on the
+ :js:func:`start` call which initialize HTTP response to the client::
[
"start",
@@ -489,12 +489,12 @@ on three parts:
#. View Processing
- Since view result could be extremely large, it's not wise to pass all his
- rows with single command. Instead of this, CouchDB send view rows one by one
- to Query Server allowing processing view and output generation in streaming
- way.
+ Since view results can be extremely large, it is not wise to pass all its
+ rows in a single command. Instead, CouchDB can send view rows one by one
+ to the Query Server allowing processing view and output generation in a
+ streaming way.
- CouchDB sends special array that carries view row data::
+ CouchDB sends a special array that carries view row data::
[
"list_row",
@@ -505,9 +505,9 @@ on three parts:
}
]
- If Query Server has something to return on this, he returns back array with
- ``"chunks"`` item in head and array of data at the tail. Suddenly, for our
- case there he has nothing to return, so the response will be::
+ If Query Server has something to return on this, it returns an array with a
+ ``"chunks"`` item in the head and an array of data in the tail. Now, for our
+ case it has nothing to return, so the response will be::
[
"chunks",
@@ -535,9 +535,10 @@ on three parts:
]
]
-There, we had made a big mistake: we had return result in single message from
-the Query Server. It's ok while there are few data in the database, but it's
-not acceptable for millions documents and millions view rows.
+There, we had made a big mistake: we had returned out result in a single
+message from the Query Server. That's ok when there are only a few rows in the
+view result, but it's not acceptable for millions documents and millions view
+rows
Let's fix our list function and see the changes in communication::
@@ -571,7 +572,7 @@ string chunks, but let's take a look on logs::
Note, that now the Query Server sends response by lightweight chunks and if
our communication process was extremely slow, the client will see how response
-data appears on his screen. Chunk by chunk, without waiting for the complete
+data appears on their screen. Chunk by chunk, without waiting for the complete
result, like he have for our previous list function.
.. _qs/ddoc/updates:
@@ -879,17 +880,16 @@ Raising errors
==============
When something went wrong the Query Server is able to inform CouchDB about
-such situation by sending special message in response of received command.
+such a situation by sending special message in response of received command.
-Error messages prevents further command execution and returns error description
-to the CouchDB. Since this point all errors are logically divided into two
-groups:
+Error messages prevent further command execution and return an error description
+to CouchDB. All errors are logically divided into two groups:
-- `Common errors`. These errors are only breaks current query server command and
- returns the error info to CouchDB instance *without* terminating Query Server
- process.
-- `Fatal errors`. The fatal errors signs about something really bad that hurts
- overall Query Server process stability and productivity. For instance, if
+- `Common errors`. These errors only break the current Query Server command and
+ return the error info to the CouchDB instance *without* terminating the Query
+ Server process.
+- `Fatal errors`. The fatal errors signal about something really bad that hurts
+ the overall Query Server process stability and productivity. For instance, if
you're using Python Query Server and some design function is unable to import
some third party module, it's better to count such error as fatal and
terminate whole process or you still have to do the same after import fixing,
@@ -910,12 +910,12 @@ notifies about missed resource and ``"type_error"`` definitely says about
invalid and non expected input from user.
The ``"reason why"`` is the error message that explains why it raised and, if
-possible, what need to do to fix it.
+possible, what is needed to do to fix it.
-For example, calling :ref:`updatefun` against non existed document could produce
+For example, calling :ref:`updatefun` against non existent document could produce
next error message::
- ["error", "not_found", "Update function requires existed document"]
+ ["error", "not_found", "Update function requires existent document"]
.. _qs/error/forbidden:
@@ -923,9 +923,9 @@ next error message::
``forbidden``
-------------
-The `forbidden` error are widely used by :ref:`vdufun` to stop further function
+The `forbidden` error is widely used by :ref:`vdufun` to stop further function
processing and prevent on disk store of the new document version. Since this
-errors actually is not an error, but an assertion against user actions, CouchDB
+error actually is not an error, but an assertion against user actions, CouchDB
doesn't log it at `"error"` level, but returns `HTTP 403 Forbidden` response
with error information object.
@@ -940,8 +940,8 @@ To raise this error, the Query Server have to answer::
----------------
The `unauthorized` error mostly acts like `forbidden` one, but with
-semantic as *please authorize first*. This small difference helps end user to
-understand what he can do to solve the problem. CouchDB doesn't log it at
+the meaning of *please authorize first*. This small difference helps end users
+to understand what they can do to solve the problem. CouchDB doesn't log it at
`"error"` level, but returns `HTTP 401 Unauthorized` response with error
information object.
@@ -960,7 +960,7 @@ field, log, on a separate line::
["log", "some message"]
-CouchDB response nothing, but writes received message into log file::
+CouchDB responds nothing, but writes received message into log file::
[Sun, 13 Feb 2009 23:31:30 GMT] [info] [<0.72.0>] Query Server Log Message: some message