couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d..@apache.org
Subject [7/34] Transmogrify Couchbase XML to .rst and support Sphinx
Date Wed, 12 Dec 2012 20:35:07 GMT
http://git-wip-us.apache.org/repos/asf/couchdb/blob/84226656/share/doc/src/api/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/misc.rst b/share/doc/src/api/misc.rst
new file mode 100644
index 0000000..f9562ae
--- /dev/null
+++ b/share/doc/src/api/misc.rst
@@ -0,0 +1,805 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. _api-misc:
+
+=====================
+Miscellaneous Methods
+=====================
+
+The CouchDB Miscellaneous interface provides the basic interface to a
+CouchDB server for obtaining CouchDB information and getting and setting
+configuration information.
+
+A list of the available methods and URL paths are provided below:
+
++--------+-------------------------+-------------------------------------------+
+| Method | Path                    | Description                               |
++========+=========================+===========================================+
+| GET    | /                       |  Get the welcome message and version      |
+|        |                         |  information                              |
++--------+-------------------------+-------------------------------------------+
+| GET    | /_active_tasks          |  Obtain a list of the tasks running in the|
+|        |                         |  server                                   |
++--------+-------------------------+-------------------------------------------+
+| GET    | /_all_dbs               |  Get a list of all the DBs                |
++--------+-------------------------+-------------------------------------------+
+| GET    | /_log                   |  Return the server log file               |
++--------+-------------------------+-------------------------------------------+
+| POST   | /_replicate             |  Set or cancel replication                |
++--------+-------------------------+-------------------------------------------+
+| POST   | /_restart               |  Restart the server                       |
++--------+-------------------------+-------------------------------------------+
+| GET    | /_stats                 |  Return server statistics                 |
++--------+-------------------------+-------------------------------------------+
+| GET    | /_utils                 |  CouchDB administration interface (Futon) |
++--------+-------------------------+-------------------------------------------+
+| GET    | /_uuids                 |  Get generated UUIDs from the server      |
++--------+-------------------------+-------------------------------------------+
+| GET    | /favicon.ico            |  Get the site icon                        |
++--------+-------------------------+-------------------------------------------+
+
+``GET /``
+=========
+
+* **Method**: ``GET /``
+* **Request**: None
+* **Response**: Welcome message and version
+* **Admin Privileges Required**: no
+* **Return Codes**:
+
+  * **200**:
+    Request completed successfully.
+
+Accessing the root of a CouchDB instance returns meta information about
+the instance. The response is a JSON structure containing information
+about the server, including a welcome message and the version of the
+server.
+
+.. code-block:: javascript
+
+    {
+       "couchdb" : "Welcome",
+       "version" : "1.0.1"
+    }
+
+.. _active-tasks:
+
+``GET /_active_tasks``
+======================
+
+* **Method**: ``GET /_active_tasks``
+* **Request**: None
+* **Response**: List of running tasks, including the task type, name, status
+  and process ID
+* **Admin Privileges Required**: yes
+* **Return Codes**:
+
+  * **200**:
+    Request completed successfully.
+
+You can obtain a list of active tasks by using the ``/_active_tasks``
+URL. The result is a JSON array of the currently running tasks, with
+each task being described with a single object. For example:
+
+.. code-block:: javascript
+
+    [
+       {
+        "pid" : "<0.11599.0>",
+        "status" : "Copied 0 of 18369 changes (0%)",
+        "task" : "recipes",
+        "type" : "Database Compaction"
+        }
+    ]
+
+The returned structure includes the following fields for each task:
+
+* **tasks** [array]: Active Task
+
+  * **pid**:Process ID
+  * **status**: Task status message
+  * **task**: Task name
+  * **type**: Operation Type
+
+For operation type, valid values include:
+
+-  ``Database Compaction``
+
+-  ``Replication``
+
+-  ``View Group Compaction``
+
+-  ``View Group Indexer``
+
+``GET /_all_dbs``
+=================
+
+* **Method**: ``GET /_all_dbs``
+* **Request**: None
+* **Response**: JSON list of DBs
+* **Admin Privileges Required**: no
+* **Return Codes**:
+
+  * **200**:
+    Request completed successfully.
+
+Returns a list of all the databases in the CouchDB instance. For
+example:
+
+.. code-block:: http
+
+    GET http://couchdb:5984/_all_dbs
+    Accept: application/json
+
+The return is a JSON array:
+
+.. code-block:: javascript
+
+    [
+       "_users",
+       "contacts",
+       "docs",
+       "invoices",
+       "locations"
+    ]
+
+``GET /_log``
+=============
+
+* **Method**: ``GET /_log``
+* **Request**: None
+* **Response**: Log content
+* **Admin Privileges Required**: yes
+* **Query Arguments**:
+
+  * **Argument**: bytes
+
+    * **Description**:  Bytes to be returned
+    * **Optional**: yes
+    * **Type**: numeric
+    * **Default**: 1000
+
+  * **Argument**: offset
+
+    * **Description**:  Offset in bytes where the log tail should be started
+    * **Optional**: yes
+    * **Type**: numeric
+    * **Default**: 0
+
+* **Return Codes**:
+
+  * **200**:
+    Request completed successfully.
+
+Gets the CouchDB log, equivalent to accessing the local log file of the
+corresponding CouchDB instance.
+
+When you request the log, the response is returned as plain (UTF-8)
+text, with an HTTP ``Content-type`` header as ``text/plain``.
+
+For example, the request:
+
+.. code-block:: http
+
+    GET http://couchdb:5984/_log
+    Accept: */*
+
+The raw text is returned:
+
+.. code-block:: text
+
+    [Wed, 27 Oct 2010 10:49:42 GMT] [info] [<0.23338.2>] 192.168.0.2 - - 'PUT' /authdb 401
+    [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /recipes/FishStew 200
+    [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /_session 200
+    [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.24199.2>] 192.168.0.116 - - 'GET' / 200
+    [Wed, 27 Oct 2010 13:03:38 GMT] [info] [<0.24207.2>] 192.168.0.116 - - 'GET' /_log?offset=5 200
+
+If you want to pick out specific parts of the log information you can
+use the ``bytes`` argument, which specifies the number of bytes to be
+returned, and ``offset``, which specifies where the reading of the log
+should start, counted back from the end. For example, if you use the
+following request:
+
+.. code-block:: http
+
+    GET /_log?bytes=500&offset=2000
+
+Reading of the log will start at 2000 bytes from the end of the log, and
+500 bytes will be shown.
+
+.. _replicate:
+
+``POST /_replicate``
+====================
+
+.. todo:: POST /_replicate :: what response is?
+
+* **Method**: ``POST /_replicate``
+* **Request**: Replication specification
+* **Response**: TBD
+* **Admin Privileges Required**: yes
+* **Query Arguments**:
+
+  * **Argument**: bytes
+
+    * **Description**:  Bytes to be returned
+    * **Optional**: yes
+    * **Type**: numeric
+    * **Default**: 1000
+
+  * **Argument**: offset
+
+    * **Description**:  Offset in bytes where the log tail should be started
+    * **Optional**: yes
+    * **Type**: numeric
+    * **Default**: 0
+
+* **Return Codes**:
+
+  * **200**:
+    Replication request successfully completed
+  * **202**:
+    Continuous replication request has been accepted
+  * **404**:
+    Either the source or target DB is not found
+  * **500**:
+    JSON specification was invalid
+
+Request, configure, or stop, a replication operation.
+
+The specification of the replication request is controlled through the
+JSON content of the request. The JSON should be an object with the
+fields defining the source, target and other options. The fields of the
+JSON request are shown in the table below:
+
+* **cancel (optional)**:  Cancels the replication
+* **continuous (optional)**:  Configure the replication to be continuous
+* **create_target (optional)**:  Creates the target database
+* **doc_ids (optional)**:  Array of document IDs to be synchronized
+* **proxy (optional)**:  Address of a proxy server through which replication
+  should occur
+* **source**:  Source database name or URL
+* **target**:  Target database name or URL
+
+Replication Operation
+---------------------
+
+The aim of the replication is that at the end of the process, all active
+documents on the source database are also in the destination database
+and all documents that were deleted in the source databases are also
+deleted (if they exist) on the destination database.
+
+Replication can be described as either push or pull replication:
+
+-  *Pull replication* is where the ``source`` is the remote CouchDB
+   instance, and the ``destination`` is the local database.
+
+   Pull replication is the most useful solution to use if your source
+   database has a permanent IP address, and your destination (local)
+   database may have a dynamically assigned IP address (for example,
+   through DHCP). This is particularly important if you are replicating
+   to a mobile or other device from a central server.
+
+-  *Push replication* is where the ``source`` is a local database, and
+   ``destination`` is a remote database.
+
+Specifying the Source and Target Database
+-----------------------------------------
+
+You must use the URL specification of the CouchDB database if you want
+to perform replication in either of the following two situations:
+
+-  Replication with a remote database (i.e. another instance of CouchDB
+   on the same host, or a different host)
+
+-  Replication with a database that requires authentication
+
+For example, to request replication between a database local to the
+CouchDB instance to which you send the request, and a remote database
+you might use the following request:
+
+.. code-block:: http
+
+    POST http://couchdb:5984/_replicate
+    Content-Type: application/json
+    Accept: application/json
+
+    {
+       "source" : "recipes",
+       "target" : "http://coucdb-remote:5984/recipes",
+    }
+
+
+In all cases, the requested databases in the ``source`` and ``target``
+specification must exist. If they do not, an error will be returned
+within the JSON object:
+
+.. code-block:: javascript
+
+    {
+       "error" : "db_not_found"
+       "reason" : "could not open http://couchdb-remote:5984/ol1ka/",
+    }
+
+You can create the target database (providing your user credentials
+allow it) by adding the ``create_target`` field to the request object:
+
+.. code-block:: http
+
+    POST http://couchdb:5984/_replicate
+    Content-Type: application/json
+    Accept: application/json
+
+    {
+       "create_target" : true
+       "source" : "recipes",
+       "target" : "http://couchdb-remote:5984/recipes",
+    }
+
+The ``create_target`` field is not destructive. If the database already
+exists, the replication proceeds as normal.
+
+Single Replication
+------------------
+
+You can request replication of a database so that the two databases can
+be synchronized. By default, the replication process occurs one time and
+synchronizes the two databases together. For example, you can request a
+single synchronization between two databases by supplying the ``source``
+and ``target`` fields within the request JSON content.
+
+.. code-block:: http
+
+    POST http://couchdb:5984/_replicate
+    Content-Type: application/json
+    Accept: application/json
+
+    {
+       "source" : "recipes",
+       "target" : "recipes-snapshot",
+    }
+
+In the above example, the databases ``recipes`` and ``recipes-snapshot``
+will be synchronized. These databases are local to the CouchDB instance
+where the request was made. The response will be a JSON structure
+containing the success (or failure) of the synchronization process, and
+statistics about the process:
+
+.. code-block:: javascript
+
+    {
+       "ok" : true,
+       "history" : [
+          {
+             "docs_read" : 1000,
+             "session_id" : "52c2370f5027043d286daca4de247db0",
+             "recorded_seq" : 1000,
+             "end_last_seq" : 1000,
+             "doc_write_failures" : 0,
+             "start_time" : "Thu, 28 Oct 2010 10:24:13 GMT",
+             "start_last_seq" : 0,
+             "end_time" : "Thu, 28 Oct 2010 10:24:14 GMT",
+             "missing_checked" : 0,
+             "docs_written" : 1000,
+             "missing_found" : 1000
+          }
+       ],
+       "session_id" : "52c2370f5027043d286daca4de247db0",
+       "source_last_seq" : 1000
+    }
+
+The structure defines the replication status, as described in the table
+below:
+
+* **history [array]**:  Replication History
+
+  * **doc_write_failures**:  Number of document write failures
+  * **docs_read**:  Number of documents read
+  * **docs_written**:  Number of documents written to target
+  * **end_last_seq**:  Last sequence number in changes stream
+  * **end_time**:  Date/Time replication operation completed
+  * **missing_checked**:  Number of missing documents checked
+  * **missing_found**:  Number of missing documents found
+  * **recorded_seq**:  Last recorded sequence number
+  * **session_id**:  Session ID for this replication operation
+  * **start_last_seq**:  First sequence number in changes stream
+  * **start_time**:  Date/Time replication operation started
+
+* **ok**:  Replication status
+* **session_id**:  Unique session ID
+* **source_last_seq**:  Last sequence number read from source database
+
+Continuous Replication
+----------------------
+
+Synchronization of a database with the previously noted methods happens
+only once, at the time the replicate request is made. To have the target
+database permanently replicated from the source, you must set the
+``continuous`` field of the JSON object within the request to true.
+
+With continuous replication changes in the source database are
+replicated to the target database in perpetuity until you specifically
+request that replication ceases.
+
+.. code-block:: http
+
+    POST http://couchdb:5984/_replicate
+    Content-Type: application/json
+    Accept: application/json
+
+    {
+       "continuous" : true
+       "source" : "recipes",
+       "target" : "http://couchdb-remote:5984/recipes",
+    }
+
+Changes will be replicated between the two databases as long as a
+network connection is available between the two instances.
+
+.. note::
+   Two keep two databases synchronized with each other, you need to set
+   replication in both directions; that is, you must replicate from
+   ``databasea`` to ``databaseb``, and separately from ``databaseb`` to
+   ``databasea``.
+
+Canceling Continuous Replication
+--------------------------------
+
+You can cancel continuous replication by adding the ``cancel`` field to
+the JSON request object and setting the value to true. Note that the
+structure of the request must be identical to the original for the
+cancellation request to be honoured. For example, if you requested
+continuous replication, the cancellation request must also contain the
+``continuous`` field.
+
+For example, the replication request:
+
+.. code-block:: http
+
+    POST http://couchdb:5984/_replicate
+    Content-Type: application/json
+    Accept: application/json
+
+    {
+       "source" : "recipes",
+       "target" : "http://couchdb-remote:5984/recipes",
+       "create_target" : true,
+       "continuous" : true
+    }
+
+Must be canceled using the request:
+
+.. code-block:: http
+
+    POST http://couchdb:5984/_replicate
+    Content-Type: application/json
+    Accept: application/json
+
+    {
+        "cancel" : true,
+        "continuous" : true
+        "create_target" : true,
+        "source" : "recipes",
+        "target" : "http://couchdb-remote:5984/recipes",
+    }
+
+Requesting cancellation of a replication that does not exist results in
+a 404 error.
+
+``POST /_restart``
+==================
+
+* **Method**: ``POST /_restart``
+* **Request**: None
+* **Response**: JSON status message
+* **Admin Privileges Required**: yes
+* **HTTP Headers**:
+
+  * **Header**: ``Content-Type``
+
+    * **Description**: Request content type
+    * **Optional**: no
+    * **Value**: :mimetype:`application/json`
+
+* **Return Codes**:
+
+  * **200**:
+    Replication request successfully completed
+
+Restarts the CouchDB instance. You must be authenticated as a user with
+administration privileges for this to work.
+
+For example:
+
+.. code-block:: http
+
+    POST http://admin:password@couchdb:5984/_restart
+
+The return value (if the server has not already restarted) is a JSON
+status object indicating that the request has been received:
+
+.. code-block:: javascript
+
+    {
+       "ok" : true,
+    }
+
+If the server has already restarted, the header may be returned, but no
+actual data is contained in the response.
+
+``GET /_stats``
+===============
+
+* **Method**: ``GET /_stats``
+* **Request**: None
+* **Response**: Server statistics
+* **Admin Privileges Required**: no
+* **Return Codes**:
+
+  * **200**:
+    Request completed successfully.
+
+The ``_stats`` method returns a JSON object containing the statistics
+for the running server. The object is structured with top-level sections
+collating the statistics for a range of entries, with each individual
+statistic being easily identified, and the content of each statistic is
+self-describing. For example, the request time statistics, within the
+``couchdb`` section are structured as follows:
+
+.. code-block:: javascript
+
+    {
+       "couchdb" : {
+    ...
+          "request_time" : {
+             "stddev" : "27.509",
+             "min" : "0.333333333333333",
+             "max" : "152",
+             "current" : "400.976",
+             "mean" : "10.837",
+             "sum" : "400.976",
+             "description" : "length of a request inside CouchDB without MochiWeb"
+          },
+    ...
+        }
+    }
+
+
+The fields provide the current, minimum and maximum, and a collection of
+statistical means and quantities. The quantity in each case is not
+defined, but the descriptions below provide
+
+The statistics are divided into the following top-level sections:
+
+-  ``couchdb``: Describes statistics specific to the internals of CouchDB.
+
+   +-------------------------+-------------------------------------------------------+----------------+
+   | Statistic ID            | Description                                           | Unit           |
+   +=========================+=======================================================+================+
+   | ``auth_cache_hits``     | Number of authentication cache hits                   | number         |
+   +-------------------------+-------------------------------------------------------+----------------+
+   | ``auth_cache_misses``   | Number of authentication cache misses                 | number         |
+   +-------------------------+-------------------------------------------------------+----------------+
+   | ``database_reads``      | Number of times a document was read from a database   | number         |
+   +-------------------------+-------------------------------------------------------+----------------+
+   | ``database_writes``     | Number of times a database was changed                | number         |
+   +-------------------------+-------------------------------------------------------+----------------+
+   | ``open_databases``      | Number of open databases                              | number         |
+   +-------------------------+-------------------------------------------------------+----------------+
+   | ``open_os_files``       | Number of file descriptors CouchDB has open           | number         |
+   +-------------------------+-------------------------------------------------------+----------------+
+   | ``request_time``        | Length of a request inside CouchDB without MochiWeb   | milliseconds   |
+   +-------------------------+-------------------------------------------------------+----------------+
+
+-  ``httpd_request_methods``
+
+   +----------------+----------------------------------+----------+
+   | Statistic ID   | Description                      | Unit     |
+   +================+==================================+==========+
+   | ``COPY``       | Number of HTTP COPY requests     | number   |
+   +----------------+----------------------------------+----------+
+   | ``DELETE``     | Number of HTTP DELETE requests   | number   |
+   +----------------+----------------------------------+----------+
+   | ``GET``        | Number of HTTP GET requests      | number   |
+   +----------------+----------------------------------+----------+
+   | ``HEAD``       | Number of HTTP HEAD requests     | number   |
+   +----------------+----------------------------------+----------+
+   | ``POST``       | Number of HTTP POST requests     | number   |
+   +----------------+----------------------------------+----------+
+   | ``PUT``        | Number of HTTP PUT requests      | number   |
+   +----------------+----------------------------------+----------+
+
+-  ``httpd_status_codes``
+
+   +----------------+------------------------------------------------------+----------+
+   | Statistic ID   | Description                                          | Unit     |
+   +================+======================================================+==========+
+   | ``200``        | Number of HTTP 200 OK responses                      | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``201``        | Number of HTTP 201 Created responses                 | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``202``        | Number of HTTP 202 Accepted responses                | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``301``        | Number of HTTP 301 Moved Permanently responses       | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``304``        | Number of HTTP 304 Not Modified responses            | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``400``        | Number of HTTP 400 Bad Request responses             | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``401``        | Number of HTTP 401 Unauthorized responses            | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``403``        | Number of HTTP 403 Forbidden responses               | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``404``        | Number of HTTP 404 Not Found responses               | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``405``        | Number of HTTP 405 Method Not Allowed responses      | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``409``        | Number of HTTP 409 Conflict responses                | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``412``        | Number of HTTP 412 Precondition Failed responses     | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``500``        | Number of HTTP 500 Internal Server Error responses   | number   |
+   +----------------+------------------------------------------------------+----------+
+
+-  ``httpd``
+
+   +----------------------------------+----------------------------------------------+----------+
+   | Statistic ID                     | Description                                  | Unit     |
+   +==================================+==============================================+==========+
+   | ``bulk_requests``                | Number of bulk requests                      | number   |
+   +----------------------------------+----------------------------------------------+----------+
+   | ``clients_requesting_changes``   | Number of clients for continuous _changes    | number   |
+   +----------------------------------+----------------------------------------------+----------+
+   | ``requests``                     | Number of HTTP requests                      | number   |
+   +----------------------------------+----------------------------------------------+----------+
+   | ``temporary_view_reads``         | Number of temporary view reads               | number   |
+   +----------------------------------+----------------------------------------------+----------+
+   | ``view_reads``                   | Number of view reads                         | number   |
+   +----------------------------------+----------------------------------------------+----------+
+
+You can also access individual statistics by quoting the statistics
+sections and statistic ID as part of the URL path. For example, to get
+the ``request_time`` statistics, you can use:
+
+.. code-block:: http
+
+    GET /_stats/couchdb/request_time
+
+This returns an entire statistics object, as with the full request, but
+containing only the request individual statistic. Hence, the returned
+structure is as follows:
+
+.. code-block:: javascript
+
+    {
+       "couchdb" : {
+          "request_time" : {
+             "stddev" : 7454.305,
+             "min" : 1,
+             "max" : 34185,
+             "current" : 34697.803,
+             "mean" : 1652.276,
+             "sum" : 34697.803,
+             "description" : "length of a request inside CouchDB without MochiWeb"
+          }
+       }
+    }
+
+
+``GET /_utils``
+===============
+
+* **Method**: ``GET /_utils``
+* **Request**: None
+* **Response**: Administration interface
+* **Admin Privileges Required**: no
+
+Accesses the built-in Futon administration interface for CouchDB.
+
+``GET /_uuids``
+===============
+
+* **Method**: ``GET /_uuids``
+* **Request**: None
+* **Response**: List of UUIDs
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+  * **Argument**: count
+
+    * **Description**:  Number of UUIDs to return
+    * **Optional**: yes
+    * **Type**: numeric
+
+* **Return Codes**:
+
+  * **200**:
+    Request completed successfully.
+
+Requests one or more Universally Unique Identifiers (UUIDs) from the
+CouchDB instance. The response is a JSON object providing a list of
+UUIDs. For example:
+
+.. code-block:: javascript
+
+    {
+       "uuids" : [
+          "7e4b5a14b22ec1cf8e58b9cdd0000da3"
+       ]
+    }
+
+You can use the ``count`` argument to specify the number of UUIDs to be
+returned. For example:
+
+.. code-block:: http
+
+    GET http://couchdb:5984/_uuids?count=5
+
+Returns:
+
+.. code-block:: javascript
+
+    {
+       "uuids" : [
+          "c9df0cdf4442f993fc5570225b405a80",
+          "c9df0cdf4442f993fc5570225b405bd2",
+          "c9df0cdf4442f993fc5570225b405e42",
+          "c9df0cdf4442f993fc5570225b4061a0",
+          "c9df0cdf4442f993fc5570225b406a20"
+       ]
+    }
+
+The UUID type is determined by the UUID type setting in the CouchDB
+configuration. See :ref:`api-put-config`.
+
+For example, changing the UUID type to ``random``:
+
+.. code-block:: http
+
+    PUT http://couchdb:5984/_config/uuids/algorithm
+    Content-Type: application/json
+    Accept: */*
+
+    "random"
+
+When obtaining a list of UUIDs:
+
+.. code-block:: javascript
+
+    {
+       "uuids" : [
+          "031aad7b469956cf2826fcb2a9260492",
+          "6ec875e15e6b385120938df18ee8e496",
+          "cff9e881516483911aa2f0e98949092d",
+          "b89d37509d39dd712546f9510d4a9271",
+          "2e0dbf7f6c4ad716f21938a016e4e59f"
+       ]
+    }
+
+``GET /favicon.ico``
+====================
+
+* **Method**: ``GET /favicon.ico``
+* **Request**: None
+* **Response**: Binary content for the `favicon.ico` site icon
+* **Admin Privileges Required**: no
+* **Return Codes**:
+
+  * **200**:
+    Request completed successfully.
+  * **404**:
+    The requested content could not be found. The returned content will include
+    further information, as a JSON object, if available.
+
+Returns the site icon. The return ``Content-Type`` header is
+:mimetype:`image/x-icon`, and the content stream is the image data.

http://git-wip-us.apache.org/repos/asf/couchdb/blob/84226656/share/doc/src/api/reference.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/reference.rst b/share/doc/src/api/reference.rst
new file mode 100644
index 0000000..fce650a
--- /dev/null
+++ b/share/doc/src/api/reference.rst
@@ -0,0 +1,28 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+API Reference
+=============
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   configuration
+   authn
+   database
+   documents
+   design
+   misc
+   local
+   dbmaint

http://git-wip-us.apache.org/repos/asf/couchdb/blob/84226656/share/doc/src/changelog.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/changelog.rst b/share/doc/src/changelog.rst
new file mode 100644
index 0000000..18c19d4
--- /dev/null
+++ b/share/doc/src/changelog.rst
@@ -0,0 +1,1175 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+Apache CouchDB CHANGES
+======================
+
+Version 1.3.0
+-------------
+
+.. note:: This version has not been released yet.
+
+Database core
+^^^^^^^^^^^^^
+
+* :issue:`1512`: Validate bind address before assignment. :commit:`09ead8a0`
+* Restore ``max_document_size`` protection. :commit:`bf1eb135`
+
+Documentation
+^^^^^^^^^^^^^
+
+* :issue:`1523`: Import CouchBase documentation and convert them into
+  `Sphinx docs <http://sphinx.pocoo.org/>`_
+
+Futon
+^^^^^
+
+* :issue:`1470`: Futon raises popup on attempt to navigate to missed/deleted
+  document. :commit:`5da40eef`
+* :issue:`1383`: Futon view editor won't allow you to save original view after
+  saving a revision. :commit:`ce48342`
+* :issue:`627`: Support all timezones. :commit:`b1a049bb`
+* :issue:`509`: Added view request duration to Futon. :commit:`2d2c7d1e`
+* :issue:`1473`, :issue:`1472`: Disable buttons for actions that the user
+  doesn't have permissions to. :commit:`7156254d`
+
+HTTP Interface
+^^^^^^^^^^^^^^^^^
+
+* :issue:`1537`: Include user name in show/list `ETags`. :commit:`ac320479`
+* :issue:`1511`: CouchDB checks `roles` field for `_users` database documents
+  with more care. :commit:`41205000`
+* :issue:`1502`: Allow users to delete own _users doc. :commit:`f0d6f19bc8`
+* :issue:`1501`: :ref:`Changes feed <changes>` now can take special parameter
+  ``since=now`` to emit changes since current point of time. :commit:`3bbb2612`
+* :issue:`1442`: No longer rewrites the `X-CouchDB-Requested-Path` during
+  recursive calls to the rewriter. :commit:`56744f2f`
+* :issue:`1441`: Limit recursion depth in the URL rewriter.
+  Defaults to a maximum of 100 invocations but is configurable.
+  :commit:`d076976c`
+* :issue:`1381`: Add jquery.couch support for Windows 8 Metro apps.
+  :commit:`dfc5d37c`
+* :issue:`1337`: Use MD5 for attachment ETag header value. :commit:`6d912c9f`
+* :issue:`1321`: Variables in rewrite rules breaks OAuth authentication.
+  :commit:`c307ba95`
+* :issue:`1285`: Allow configuration of vendor and modules version in CouchDB
+  welcome message. :commit:`3c24a94d`
+* :issue:`1277`: Better query parameter support and code clarity:
+  :commit:`7e3c69ba`
+
+  * Responses to documents created/modified via form data `POST` to /db/doc or
+    copied with `COPY` should now include `Location` header.
+  * Form data POST to /db/doc now includes an `ETag` response header.
+  * ``?batch=ok`` is now supported for `COPY` and `POST` /db/doc updates.
+  * ``?new_edits=false`` is now supported for more operations.
+
+* :issue:`1210`: Files starting with underscore can be attached and updated now.
+  :commit:`05858792`
+* :issue:`1097`: Allow `OPTIONS` request to shows and lists functions.
+  :commit:`9f53704a`
+* :issue:`1026`: Database names are encoded with respect of special characters
+  in the rewriter now. :commit:`272d6415`
+* :issue:`986`: Added Server-Sent Events protocol to db changes API.
+  See http://www.w3.org/TR/eventsource/ for details. :commit:`093d2aa6`
+* :issue:`887`: Fix ``bytes`` and ``offset`` parameters semantic for `_log`
+  resource (`explanation <https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blobdiff;f=src/couchdb/couch_log.erl;h=1b05f4db2;hp=0befe7aab;hb=ad700014;hpb=7809f3ca>`_)
+  :commit:`ad700014`
+* :issue:`764`, :issue:`514`, :issue:`430`: Fix sending HTTP headers from
+  ``_list`` function, :commit:`2a74f88375`
+* Send a 202 response for `_restart`. :commit:`b213e16f`
+* Make password hashing synchronous when using the /_config/admins API.
+  :commit:`08071a80`
+* Fix `_session` for IE7.
+* Return ``X-Couch-Id`` header if doc is created, :commit:`98515bf0b9`
+* Allow any 2xx code to indicate success, :commit:`0d50103cfd`
+* Restore 400 error for empty PUT, :commit:`2057b895`
+* Add support to serve single file with CouchDB, :commit:`2774531ff2`
+* Support auth cookies with ``:`` characters, :commit:`d9566c831d`
+
+Log System
+^^^^^^^^^^
+
+* :issue:`1380`: Minor fixes for logrotate support.
+* Improve file I/O error logging and handling, :commit:`4b6475da`
+* Module Level Logging, :commit:`b58f069167`
+* Log 5xx responses at error level, :commit:`e896b0b7`
+* Log problems opening database at ERROR level except for auto-created
+  system dbs, :commit:`41667642f7`
+
+Replicator
+^^^^^^^^^^
+
+* :issue:`1557`: Upgrade some code to use BIFs bring good improvements for
+  replication.
+* :issue:`1363`: Fix rarely occurred, but still race condition in changes feed
+  if a quick burst of changes happens while replication is starting the
+  replication can go stale. :commit:`573a7bb9`
+* :issue:`1323`: Replicator now acts as standalone application.
+  :commit:`f913ca6e`
+* :issue:`1259`: Stabilize replication id, :commit:`c6252d6d7f`
+* :issue:`1248`: `HTTP 500` error now doesn't occurs when replicating with
+  ``?doc_ids=null``. :commit:`bea76dbf`
+
+Security
+^^^^^^^^
+
+* :issue:`1060`: Passwords are now hashed using the PBKDF2 algorithm with a
+  configurable work factor. :commit:`7d418134`
+
+Source Repository
+^^^^^^^^^^^^^^^^^
+
+* The source repository was migrated from `SVN`_ to `Git`_.
+
+.. _SVN: https://svn.apache.org/repos/asf/couchdb
+.. _Git: https://git-wip-us.apache.org/repos/asf/couchdb.git
+
+Storage System
+^^^^^^^^^^^^^^
+
+* Fixed unnecessary conflict when deleting and creating a
+  document in the same batch.
+
+Test Suite
+^^^^^^^^^^
+
+* :issue:`1563`: Ensures urlPrefix is set in all ajax requests.
+  :commit:`07a6af222`
+* :issue:`1389`: Improved tracebacks printed by the JS CLI tests.
+* :issue:`1339`: Use shell trap to catch dying beam processes during test runs.
+  :commit:`2921c78`
+* :issue:`1338`: Start CouchDB with ``port=0``. While CouchDB might be already
+  running on the default port 5984, port number 0 let the TCP stack figure out a
+  free port to run. :commit:`127cbe3`
+* :issue:`1321`: Moved the JS test suite to the CLI.
+* Improved the reliability of a number of tests.
+* Fix race condition for test running on faster hardware.
+
+URL Rewriter & Vhosts
+^^^^^^^^^^^^^^^^^^^^^
+
+* :issue:`1026`: Database name is encoded during rewriting
+  (allowing embedded /'s, etc). :commit:`272d6415`
+
+UUID Algorithms
+^^^^^^^^^^^^^^^
+
+* :issue:`1373`: Added the utc_id algorithm :commit:`5ab712a2`
+
+Query and View Server
+^^^^^^^^^^^^^^^^^^^^^
+
+* :issue:`1491`: Clenaup view tables. :commit:`c37204b7`
+* :issue:`1483`: Update handlers requires valid doc ids. :commit:`72ea7e38`
+* :issue:`1445`: CouchDB tries no more to delete view file if it couldn't open
+  it, even if the error is `emfile`.
+* :issue:`1444`: Fix missed_named_view error that occurs on existed design
+  documents and views. :commit:`b59ac98b`
+* :issue:`1372`: `_stats` builtin reduce function no longer produces error for
+  empty view result.
+* :issue:`1334`: Speedup in the communication with external view servers.
+  :commit:`a851c6e5`
+* :issue:`410`: More graceful error handling for JavaScript validate_doc_update
+  functions.
+* :issue:`111`: Improve the errors reported by the javascript view server
+  to provide a more friendly error report when something goes wrong.
+  :commit:`0c619ed`
+* Deprecate E4X support, :commit:`cdfdda2314`
+
+Windows
+^^^^^^^
+
+* :issue:`1482`: Use correct linker flang to build `snappy_nif.dll` on Windows.
+  :commit:`a6eaf9f1`
+* Allows building cleanly on Windows without cURL, :commit:`fb670f5712`
+
+
+Version 1.2.0
+-------------
+
+Authentication
+^^^^^^^^^^^^^^
+
+* Fix use of OAuth with VHosts and URL rewriting.
+* OAuth secrets can now be stored in the users system database
+  as an alternative to key value pairs in the .ini configuration.
+  By default this is disabled (secrets are stored in the .ini)
+  but can be enabled via the .ini configuration key `use_users_db`
+  in the `couch_httpd_oauth` section.
+* Documents in the _users database are no longer publicly
+  readable.
+* Confidential information in the _replication database is no
+  longer publicly readable.
+* Password hashes are now calculated by CouchDB. Clients are no
+  longer required to do this manually.
+* Cookies used for authentication can be made persistent by enabling
+  the .ini configuration key `allow_persistent_cookies` in the
+  `couch_httpd_auth` section.
+
+Build System
+^^^^^^^^^^^^
+
+* cURL is no longer required to build CouchDB as it is only
+  used by the command line JS test runner. If cURL is available
+  when building CouchJS you can enable the HTTP bindings by
+  passing -H on the command line.
+* Temporarily made `make check` pass with R15B. A more thorough
+  fix is in the works (:issue:`1424`).
+* Fixed --with-js-include and --with-js-lib options.
+* Added --with-js-lib-name option.
+
+Futon
+^^^^^
+
+* The `Status` screen (active tasks) now displays two new task status
+  fields: `Started on` and `Updated on`.
+* Futon remembers view code every time it is saved, allowing to save an
+  edit that amounts to a revert.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Added a native JSON parser.
+* The _active_tasks API now offers more granular fields. Each
+  task type is now able to expose different properties.
+* Added built-in changes feed filter `_view`.
+* Fixes to the `_changes` feed heartbeat option which caused
+  heartbeats to be missed when used with a filter. This caused
+  timeouts of continuous pull replications with a filter.
+* Properly restart the SSL socket on configuration changes.
+
+Replicator
+^^^^^^^^^^
+
+* A new replicator implementation. It offers more performance and
+  configuration options.
+* Passing non-string values to query_params is now a 400 bad
+  request. This is to reduce the surprise that all parameters
+  are converted to strings internally.
+* Added optional field `since_seq` to replication objects/documents.
+  It allows to bootstrap a replication from a specific source sequence
+  number.
+* Simpler replication cancellation. In addition to the current method,
+  replications can now be canceled by specifying the replication ID
+  instead of the original replication object/document.
+
+Storage System
+^^^^^^^^^^^^^^
+
+* Added optional database and view index file compression (using Google's
+  snappy or zlib's deflate). This feature is enabled by default, but it
+  can be disabled by adapting local.ini accordingly. The on-disk format
+  is upgraded on compaction and new DB/view creation to support this.
+* Several performance improvements, most notably regarding database writes
+  and view indexing.
+* Computation of the size of the latest MVCC snapshot data and all its
+  supporting metadata, both for database and view index files. This
+  information is exposed as the `data_size` attribute in the database and
+  view group information URIs.
+* The size of the buffers used for database and view compaction is now
+  configurable.
+* Added support for automatic database and view compaction. This feature
+  is disabled by default, but it can be enabled via the .ini configuration.
+* Performance improvements for the built-in changes feed filters `_doc_ids`
+  and `_design'.
+
+View Server
+^^^^^^^^^^^
+
+* Add CoffeeScript (http://coffeescript.org/) as a first class view server
+  language.
+* Fixed old index file descriptor leaks after a view cleanup.
+* The requested_path property keeps the pre-rewrite path even when no VHost
+  configuration is matched.
+* Fixed incorrect reduce query results when using pagination parameters.
+* Made icu_driver work with Erlang R15B and later.
+
+OAuth
+^^^^^
+
+* Updated bundled erlang_oauth library to the latest version.
+
+
+Version 1.1.1
+-------------
+
+* Support SpiderMonkey 1.8.5
+* Add configurable maximum to the number of bytes returned by _log.
+* Allow CommonJS modules to be an empty string.
+* Bump minimum Erlang version to R13B02.
+* Do not run deleted validate_doc_update functions.
+* ETags for views include current sequence if include_docs=true.
+* Fix bug where duplicates can appear in _changes feed.
+* Fix bug where update handlers break after conflict resolution.
+* Fix bug with _replicator where include "filter" could crash couch.
+* Fix crashes when compacting large views.
+* Fix file descriptor leak in _log
+* Fix missing revisions in _changes?style=all_docs.
+* Improve handling of compaction at max_dbs_open limit.
+* JSONP responses now send "text/javascript" for Content-Type.
+* Link to ICU 4.2 on Windows.
+* Permit forward slashes in path to update functions.
+* Reap couchjs processes that hit reduce_overflow error.
+* Status code can be specified in update handlers.
+* Support provides() in show functions.
+* _view_cleanup when ddoc has no views now removes all index files.
+* max_replication_retry_count now supports "infinity".
+* Fix replication crash when source database has a document with empty ID.
+* Fix deadlock when assigning couchjs processes to serve requests.
+* Fixes to the document multipart PUT API.
+* Fixes regarding file descriptor leaks for databases with views.
+
+
+Version 1.1.0
+-------------
+
+.. note:: All CHANGES for 1.0.2 and 1.0.3 also apply to 1.1.0.
+
+Externals
+^^^^^^^^^
+
+* Added OS Process module to manage daemons outside of CouchDB.
+* Added HTTP Proxy handler for more scalable externals.
+
+Futon
+^^^^^
+
+* Added a "change password"-feature to Futon.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Native SSL support.
+* Added support for HTTP range requests for attachments.
+* Added built-in filters for `_changes`: `_doc_ids` and `_design`.
+* Added configuration option for TCP_NODELAY aka "Nagle".
+* Allow POSTing arguments to `_changes`.
+* Allow `keys` parameter for GET requests to views.
+* Allow wildcards in vhosts definitions.
+* More granular ETag support for views.
+* More flexible URL rewriter.
+* Added support for recognizing "Q values" and media parameters in
+  HTTP Accept headers.
+* Validate doc ids that come from a PUT to a URL.
+
+Replicator
+^^^^^^^^^^
+
+* Added `_replicator` database to manage replications.
+* Fixed issues when an endpoint is a remote database accessible via SSL.
+* Added support for continuous by-doc-IDs replication.
+* Fix issue where revision info was omitted when replicating attachments.
+* Integrity of attachment replication is now verified by MD5.
+
+Storage System
+^^^^^^^^^^^^^^
+
+* Multiple micro-optimizations when reading data.
+
+URL Rewriter & Vhosts
+^^^^^^^^^^^^^^^^^^^^^
+
+* Fix for variable substituion
+
+View Server
+^^^^^^^^^^^
+
+* Added CommonJS support to map functions.
+* Added `stale=update_after` query option that triggers a view update after
+  returning a `stale=ok` response.
+* Warn about empty result caused by `startkey` and `endkey` limiting.
+* Built-in reduce function `_sum` now accepts lists of integers as input.
+* Added view query aliases start_key, end_key, start_key_doc_id and
+  end_key_doc_id.
+
+
+Version 1.0.3
+-------------
+
+General
+^^^^^^^
+
+* Fixed compatibility issues with Erlang R14B02.
+
+Etap Test Suite
+^^^^^^^^^^^^^^^
+
+* Etap tests no longer require use of port 5984. They now use a randomly
+  selected port so they won't clash with a running CouchDB.
+
+Futon
+^^^^^
+
+* Made compatible with jQuery 1.5.x.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Fix bug that allows invalid UTF-8 after valid escapes.
+* The query parameter `include_docs` now honors the parameter `conflicts`.
+  This applies to queries against map views, _all_docs and _changes.
+* Added support for inclusive_end with reduce views.
+
+Replicator
+^^^^^^^^^^
+
+* Enabled replication over IPv6.
+* Fixed for crashes in continuous and filtered changes feeds.
+* Fixed error when restarting replications in OTP R14B02.
+* Upgrade ibrowse to version 2.2.0.
+* Fixed bug when using a filter and a limit of 1.
+
+Security
+^^^^^^^^
+
+* Fixed OAuth signature computation in OTP R14B02.
+* Handle passwords with : in them.
+
+Storage System
+^^^^^^^^^^^^^^
+
+* More performant queries against _changes and _all_docs when using the
+  `include_docs` parameter.
+
+Windows
+^^^^^^^
+
+* Windows builds now require ICU >= 4.4.0 and Erlang >= R14B03. See
+  :issue:`1152`, and :issue:`963` + OTP-9139 for more information.
+
+
+Version 1.0.2
+-------------
+
+Futon
+^^^^^
+
+* Make test suite work with Safari and Chrome.
+* Fixed animated progress spinner.
+* Fix raw view document link due to overzealous URI encoding.
+* Spell javascript correctly in loadScript(uri).
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Allow reduce=false parameter in map-only views.
+* Fix parsing of Accept headers.
+* Fix for multipart GET APIs when an attachment was created during a
+  local-local replication. See :issue:`1022` for details.
+
+Log System
+^^^^^^^^^^
+
+* Reduce lengthy stack traces.
+* Allow logging of native <xml> types.
+
+Replicator
+^^^^^^^^^^
+
+* Updated ibrowse library to 2.1.2 fixing numerous replication issues.
+* Make sure that the replicator respects HTTP settings defined in the config.
+* Fix error when the ibrowse connection closes unexpectedly.
+* Fix authenticated replication (with HTTP basic auth) of design documents
+  with attachments.
+* Various fixes to make replication more resilient for edge-cases.
+
+Storage System
+^^^^^^^^^^^^^^
+
+* Fix leaking file handles after compacting databases and views.
+* Fix databases forgetting their validation function after compaction.
+* Fix occasional timeout errors after successfully compacting large databases.
+* Fix ocassional error when writing to a database that has just been compacted.
+* Fix occasional timeout errors on systems with slow or heavily loaded IO.
+* Fix for OOME when compactions include documents with many conflicts.
+* Fix for missing attachment compression when MIME types included parameters.
+* Preserve purge metadata during compaction to avoid spurious view rebuilds.
+* Fix spurious conflicts introduced when uploading an attachment after
+  a doc has been in a conflict. See :issue:`902` for details.
+* Fix for frequently edited documents in multi-master deployments being
+  duplicated in _changes and _all_docs.  See :issue:`968` for details on how
+  to repair.
+* Significantly higher read and write throughput against database and
+  view index files.
+
+View Server
+^^^^^^^^^^^
+
+* Don't trigger view updates when requesting `_design/doc/_info`.
+* Fix for circular references in CommonJS requires.
+* Made isArray() function available to functions executed in the query server.
+* Documents are now sealed before being passed to map functions.
+* Force view compaction failure when duplicated document data exists. When
+  this error is seen in the logs users should rebuild their views from
+  scratch to fix the issue. See :issue:`999` for details.
+
+
+Version 1.0.1
+-------------
+
+Authentication
+^^^^^^^^^^^^^^
+
+* Enable basic-auth popup when required to access the server, to prevent
+   people from getting locked out.
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Included additional source files for distribution.
+
+Futon
+^^^^^
+
+* User interface element for querying stale (cached) views.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Expose `committed_update_seq` for monitoring purposes.
+* Show fields saved along with _deleted=true. Allows for auditing of deletes.
+* More robust Accept-header detection.
+
+Replicator
+^^^^^^^^^^
+
+* Added support for replication via an HTTP/HTTPS proxy.
+* Fix pull replication of attachments from 0.11 to 1.0.x.
+* Make the _changes feed work with non-integer seqnums.
+
+Storage System
+^^^^^^^^^^^^^^
+
+* Fix data corruption bug :issue:`844`. Please see
+  http://couchdb.apache.org/notice/1.0.1.html for details.
+
+
+Version 1.0.0
+-------------
+
+Security
+^^^^^^^^
+
+* Added authentication caching, to avoid repeated opening and closing of the
+  users database for each request requiring authentication.
+
+Storage System
+^^^^^^^^^^^^^^
+
+* Small optimization for reordering result lists.
+* More efficient header commits.
+* Use O_APPEND to save lseeks.
+* Faster implementation of pread_iolist(). Further improves performance on
+  concurrent reads.
+
+View Server
+^^^^^^^^^^^
+
+* Faster default view collation.
+* Added option to include update_seq in view responses.
+
+
+Version 0.11.2
+--------------
+
+Authentication
+^^^^^^^^^^^^^^
+
+* User documents can now be deleted by admins or the user.
+
+Futon
+^^^^^
+
+* Add some Futon files that were missing from the Makefile.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Better error messages on invalid URL requests.
+
+Replicator
+^^^^^^^^^^
+
+* Fix bug when pushing design docs by non-admins, which was hanging the
+   replicator for no good reason.
+* Fix bug when pulling design documents from a source that requires
+   basic-auth.
+
+Security
+^^^^^^^^
+
+* Avoid potential DOS attack by guarding all creation of atoms.
+
+
+Version 0.11.1
+--------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Output of `couchdb --help` has been improved.
+* Fixed compatibility with the Erlang R14 series.
+* Fixed warnings on Linux builds.
+* Fixed build error when aclocal needs to be called during the build.
+* Require ICU 4.3.1.
+* Fixed compatibility with Solaris.
+
+Configuration System
+^^^^^^^^^^^^^^^^^^^^
+
+* Fixed timeout with large .ini files.
+
+Futon
+^^^^^
+
+* Use "expando links" for over-long document values in Futon.
+* Added continuous replication option.
+* Added option to replicating test results anonymously to a community
+  CouchDB instance.
+* Allow creation and deletion of config entries.
+* Fixed display issues with doc ids that have escaped characters.
+* Fixed various UI issues.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Mask passwords in active tasks and logging.
+* Update mochijson2 to allow output of BigNums not in float form.
+* Added support for X-HTTP-METHOD-OVERRIDE.
+* Better error message for database names.
+* Disable jsonp by default.
+* Accept gzip encoded standalone attachments.
+* Made max_concurrent_connections configurable.
+* Made changes API more robust.
+* Send newly generated document rev to callers of an update function.
+
+JavaScript Clients
+^^^^^^^^^^^^^^^^^^
+
+* Added tests for couch.js and jquery.couch.js
+* Added changes handler to jquery.couch.js.
+* Added cache busting to jquery.couch.js if the user agent is msie.
+* Added support for multi-document-fetch (via _all_docs) to jquery.couch.js.
+* Added attachment versioning to jquery.couch.js.
+* Added option to control ensure_full_commit to jquery.couch.js.
+* Added list functionality to jquery.couch.js.
+* Fixed issues where bulkSave() wasn't sending a POST body.
+
+Log System
+^^^^^^^^^^
+
+* Log HEAD requests as HEAD, not GET.
+* Keep massive JSON blobs out of the error log.
+* Fixed a timeout issue.
+
+Replication System
+^^^^^^^^^^^^^^^^^^
+
+* Refactored various internal APIs related to attachment streaming.
+* Fixed hanging replication.
+* Fixed keepalive issue.
+
+Security
+^^^^^^^^
+
+* Added authentication redirect URL to log in clients.
+* Fixed query parameter encoding issue in oauth.js.
+* Made authentication timeout configurable.
+* Temporary views are now admin-only resources.
+
+Storage System
+^^^^^^^^^^^^^^
+
+* Don't require a revpos for attachment stubs.
+* Added checking to ensure when a revpos is sent with an attachment stub,
+  it's correct.
+* Make file deletions async to avoid pauses during compaction and db
+  deletion.
+* Fixed for wrong offset when writing headers and converting them to blocks,
+  only triggered when header is larger than 4k.
+* Preserve _revs_limit and instance_start_time after compaction.
+
+Test Suite
+^^^^^^^^^^
+
+* Made the test suite overall more reliable.
+
+View Server
+^^^^^^^^^^^
+
+* Provide a UUID to update functions (and all other functions) that they can
+  use to create new docs.
+* Upgrade CommonJS modules support to 1.1.1.
+* Fixed erlang filter funs and normalize filter fun API.
+* Fixed hang in view shutdown.
+
+URL Rewriter & Vhosts
+^^^^^^^^^^^^^^^^^^^^^
+
+* Allow more complex keys in rewriter.
+* Allow global rewrites so system defaults are available in vhosts.
+* Allow isolation of databases with vhosts.
+* Fix issue with passing variables to query parameters.
+
+
+Version 0.11.0
+--------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Updated and improved source documentation.
+* Fixed distribution preparation for building on Mac OS X.
+* Added support for building a Windows installer as part of 'make dist'.
+* Bug fix for building couch.app's module list.
+* ETap tests are now run during make distcheck. This included a number of
+  updates to the build system to properly support VPATH builds.
+* Gavin McDonald setup a build-bot instance. More info can be found at
+  http://ci.apache.org/buildbot.html
+
+Futon
+^^^^^
+
+* Added a button for view compaction.
+* JSON strings are now displayed as-is in the document view, without the
+  escaping of new-lines and quotes. That dramatically improves readability of
+  multi-line strings.
+* Same goes for editing of JSON string values. When a change to a field value is
+  submitted, and the value is not valid JSON it is assumed to be a string. This
+  improves editing of multi-line strings a lot.
+* Hitting tab in textareas no longer moves focus to the next form field, but
+  simply inserts a tab character at the current caret position.
+* Fixed some font declarations.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Provide Content-MD5 header support for attachments.
+* Added URL Rewriter handler.
+* Added virtual host handling.
+
+Replication
+^^^^^^^^^^^
+
+* Added option to implicitly create replication target databases.
+* Avoid leaking file descriptors on automatic replication restarts.
+* Added option to replicate a list of documents by id.
+* Allow continuous replication to be cancelled.
+
+Runtime Statistics
+^^^^^^^^^^^^^^^^^^
+
+* Statistics are now calculated for a moving window instead of non-overlapping
+  timeframes.
+* Fixed a problem with statistics timers and system sleep.
+* Moved statistic names to a term file in the priv directory.
+
+Security
+^^^^^^^^
+
+* Fixed CVE-2010-0009: Apache CouchDB Timing Attack Vulnerability.
+* Added default cookie-authentication and users database.
+* Added Futon user interface for user signup and login.
+* Added per-database reader access control lists.
+* Added per-database security object for configuration data in validation
+  functions.
+* Added proxy authentication handler
+
+Storage System
+^^^^^^^^^^^^^^
+
+* Adds batching of multiple updating requests, to improve throughput with many
+  writers. Removed the now redundant couch_batch_save module.
+* Adds configurable compression of attachments.
+
+View Server
+^^^^^^^^^^^
+
+* Added optional 'raw' binary collation for faster view builds where Unicode
+  collation is not important.
+* Improved view index build time by reducing ICU collation callouts.
+* Improved view information objects.
+* Bug fix for partial updates during view builds.
+* Move query server to a design-doc based protocol.
+* Use json2.js for JSON serialization for compatiblity with native JSON.
+* Major refactoring of couchjs to lay the groundwork for disabling cURL
+  support. The new HTTP interaction acts like a synchronous XHR. Example usage
+  of the new system is in the JavaScript CLI test runner.
+
+
+
+
+Version 0.10.1
+--------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Test suite now works with the distcheck target.
+
+Replicator
+^^^^^^^^^^
+
+* Stability enhancements regarding redirects, timeouts, OAuth.
+
+Query Server
+^^^^^^^^^^^^
+
+* Avoid process leaks
+* Allow list and view to span languages
+
+Stats
+^^^^^
+
+* Eliminate new process flood on system wake
+
+
+Version 0.10.0
+--------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Changed `couchdb` script configuration options.
+* Added default.d and local.d configuration directories to load sequence.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Added optional cookie-based authentication handler.
+* Added optional two-legged OAuth authentication handler.
+
+Storage Format
+^^^^^^^^^^^^^^
+
+* Add move headers with checksums to the end of database files for extra robust
+  storage and faster storage.
+
+View Server
+^^^^^^^^^^^
+
+* Added native Erlang views for high-performance applications.
+
+
+Version 0.9.2
+-------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Remove branch callbacks to allow building couchjs against newer versions of
+  Spidermonkey.
+
+Replication
+^^^^^^^^^^^
+
+* Fix replication with 0.10 servers initiated by an 0.9 server (:issue:`559`).
+
+
+Version 0.9.1
+-------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* PID file directory is now created by the SysV/BSD daemon scripts.
+* Fixed the environment variables shown by the configure script.
+* Fixed the build instructions shown by the configure script.
+* Updated ownership and permission advice in `README` for better security.
+
+Configuration and stats system
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Corrected missing configuration file error message.
+* Fixed incorrect recording of request time.
+
+Database Core
+^^^^^^^^^^^^^
+
+* Document validation for underscore prefixed variables.
+* Made attachment storage less sparse.
+* Fixed problems when a database with delayed commits pending is considered
+  idle, and subject to losing changes when shutdown. (:issue:`334`)
+
+External Handlers
+^^^^^^^^^^^^^^^^^
+
+* Fix POST requests.
+
+Futon
+^^^^^
+
+* Redirect when loading a deleted view URI from the cookie.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Attachment requests respect the "rev" query-string parameter.
+
+JavaScript View Server
+^^^^^^^^^^^^^^^^^^^^^^
+
+* Useful JavaScript Error messages.
+
+Replication
+^^^^^^^^^^^
+
+* Added support for Unicode characters transmitted as UTF-16 surrogate pairs.
+* URL-encode attachment names when necessary.
+* Pull specific revisions of an attachment, instead of just the latest one.
+* Work around a rare chunk-merging problem in ibrowse.
+* Work with documents containing Unicode characters outside the Basic
+  Multilingual Plane.
+
+
+Version 0.9.0
+-------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* The `couchdb` script now supports system chainable configuration files.
+* The Mac OS X daemon script now redirects STDOUT and STDERR like SysV/BSD.
+* The build and system integration have been improved for portability.
+* Added COUCHDB_OPTIONS to etc/default/couchdb file.
+* Remove COUCHDB_INI_FILE and COUCHDB_PID_FILE from etc/default/couchdb file.
+* Updated `configure.ac` to manually link `libm` for portability.
+* Updated `configure.ac` to extended default library paths.
+* Removed inets configuration files.
+* Added command line test runner.
+* Created dev target for make.
+
+Configuration and stats system
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Separate default and local configuration files.
+* HTTP interface for configuration changes.
+* Statistics framework with HTTP query API.
+
+Database Core
+^^^^^^^^^^^^^
+
+* Faster B-tree implementation.
+* Changed internal JSON term format.
+* Improvements to Erlang VM interactions under heavy load.
+* User context and administrator role.
+* Update validations with design document validation functions.
+* Document purge functionality.
+* Ref-counting for database file handles.
+
+Design Document Resource Paths
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Added httpd_design_handlers config section.
+* Moved _view to httpd_design_handlers.
+* Added ability to render documents as non-JSON content-types with _show and
+  _list functions, which are also httpd_design_handlers.
+
+Futon Utility Client
+^^^^^^^^^^^^^^^^^^^^
+
+* Added pagination to the database listing page.
+* Implemented attachment uploading from the document page.
+* Added page that shows the current configuration, and allows modification of
+  option values.
+* Added a JSON "source view" for document display.
+* JSON data in view rows is now syntax highlighted.
+* Removed the use of an iframe for better integration with browser history and
+  bookmarking.
+* Full database listing in the sidebar has been replaced by a short list of
+  recent databases.
+* The view editor now allows selection of the view language if there is more
+  than one configured.
+* Added links to go to the raw view or document URI.
+* Added status page to display currently running tasks in CouchDB.
+* JavaScript test suite split into multiple files.
+* Pagination for reduce views.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Added client side UUIDs for idempotent document creation
+* HTTP COPY for documents
+* Streaming of chunked attachment PUTs to disk
+* Remove negative count feature
+* Add include_docs option for view queries
+* Add multi-key view post for views
+* Query parameter validation
+* Use stale=ok to request potentially cached view index
+* External query handler module for full-text or other indexers.
+* Etags for attachments, views, shows and lists
+* Show and list functions for rendering documents and views as developer
+  controlled content-types.
+* Attachment names may use slashes to allow uploading of nested directories
+  (useful for static web hosting).
+* Option for a view to run over design documents.
+* Added newline to JSON responses. Closes bike-shed.
+
+Replication
+^^^^^^^^^^^
+
+* Using ibrowse.
+* Checkpoint replications so failures are less expensive.
+* Automatically retry of failed replications.
+* Stream attachments in pull-replication.
+
+
+Version 0.8.1-incubating
+------------------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* The `couchdb` script no longer uses `awk` for configuration checks as this
+  was causing portability problems.
+* Updated `sudo` example in `README` to use the `-i` option, this fixes
+  problems when invoking from a directory the `couchdb` user cannot access.
+
+Database Core
+^^^^^^^^^^^^^
+
+* Fix for replication problems where the write queues can get backed up if the
+  writes aren't happening fast enough to keep up with the reads. For a large
+  replication, this can exhaust memory and crash, or slow down the machine
+  dramatically. The fix keeps only one document in the write queue at a time.
+* Fix for databases sometimes incorrectly reporting that they contain 0
+  documents after compaction.
+* CouchDB now uses ibrowse instead of inets for its internal HTTP client
+  implementation. This means better replication stability.
+
+Futon
+^^^^^
+
+* The view selector dropdown should now work in Opera and Internet Explorer
+  even when it includes optgroups for design documents. (:issue:`81`)
+
+JavaScript View Server
+^^^^^^^^^^^^^^^^^^^^^^
+
+* Sealing of documents has been disabled due to an incompatibility with
+  SpiderMonkey 1.9.
+* Improve error handling for undefined values emitted by map functions.
+  (:issue:`83`)
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* Fix for chunked responses where chunks were always being split into multiple
+  TCP packets, which caused problems with the test suite under Safari, and in
+  some other cases.
+* Fix for an invalid JSON response body being returned for some kinds of
+  views. (:issue:`84`)
+* Fix for connections not getting closed after rejecting a chunked request.
+  (:issue:`55`)
+* CouchDB can now be bound to IPv6 addresses.
+* The HTTP `Server` header now contains the versions of CouchDB and Erlang.
+
+
+Version 0.8.0-incubating
+------------------------
+
+Build and System Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* CouchDB can automatically respawn following a server crash.
+* Database server no longer refuses to start with a stale PID file.
+* System logrotate configuration provided.
+* Improved handling of ICU shared libraries.
+* The `couchdb` script now automatically enables SMP support in Erlang.
+* The `couchdb` and `couchjs` scripts have been improved for portability.
+* The build and system integration have been improved for portability.
+
+Database Core
+^^^^^^^^^^^^^
+
+* The view engine has been completely decoupled from the storage engine. Index
+  data is now stored in separate files, and the format of the main database
+  file has changed.
+* Databases can now be compacted to reclaim space used for deleted documents
+  and old document revisions.
+* Support for incremental map/reduce views has been added.
+* To support map/reduce, the structure of design documents has changed. View
+  values are now JSON objects containing at least a `map` member, and
+  optionally a `reduce` member.
+* View servers are now identified by name (for example `javascript`) instead of
+  by media type.
+* Automatically generated document IDs are now based on proper UUID generation
+  using the crypto module.
+* The field `content-type` in the JSON representation of attachments has been
+  renamed to `content_type` (underscore).
+
+Futon
+^^^^^
+
+* When adding a field to a document, Futon now just adds a field with an
+  autogenerated name instead of prompting for the name with a dialog. The name
+  is automatically put into edit mode so that it can be changed immediately.
+* Fields are now sorted alphabetically by name when a document is displayed.
+* Futon can be used to create and update permanent views.
+* The maximum number of rows to display per page on the database page can now
+  be adjusted.
+* Futon now uses the XMLHTTPRequest API asynchronously to communicate with the
+  CouchDB HTTP server, so that most operations no longer block the browser.
+* View results sorting can now be switched between ascending and descending by
+  clicking on the `Key` column header.
+* Fixed a bug where documents that contained a `@` character could not be
+  viewed. (:issue:`12`)
+* The database page now provides a `Compact` button to trigger database
+  compaction. (:issue:`38`)
+* Fixed portential double encoding of document IDs and other URI segments in
+  many instances. (:issue:`39`)
+* Improved display of attachments.
+* The JavaScript Shell has been removed due to unresolved licensing issues.
+
+JavaScript View Server
+^^^^^^^^^^^^^^^^^^^^^^
+
+* SpiderMonkey is no longer included with CouchDB, but rather treated as a
+  normal external dependency. A simple C program (`_couchjs`) is provided that
+  links against an existing SpiderMonkey installation and uses the interpreter
+  embedding API.
+* View functions using the default JavaScript view server can now do logging
+  using the global `log(message)` function. Log messages are directed into the
+  CouchDB log at `INFO` level. (:issue:`59`)
+* The global `map(key, value)` function made available to view code has been
+  renamed to `emit(key, value)`.
+* Fixed handling of exceptions raised by view functions.
+
+HTTP Interface
+^^^^^^^^^^^^^^
+
+* CouchDB now uses MochiWeb instead of inets for the HTTP server
+  implementation. Among other things, this means that the extra configuration
+  files needed for inets (such as `couch_httpd.conf`) are no longer used.
+* The HTTP interface now completely supports the `HEAD` method. (:issue:`3`)
+* Improved compliance of `Etag` handling with the HTTP specification.
+  (:issue:`13`)
+* Etags are no longer included in responses to document `GET` requests that
+  include query string parameters causing the JSON response to change without
+  the revision or the URI having changed.
+* The bulk document update API has changed slightly on both the request and the
+  response side. In addition, bulk updates are now atomic.
+* CouchDB now uses `TCP_NODELAY` to fix performance problems with persistent
+  connections on some platforms due to nagling.
+* Including a `?descending=false` query string parameter in requests to views
+  no longer raises an error.
+* Requests to unknown top-level reserved URLs (anything with a leading
+  underscore) now return a `unknown_private_path` error instead of the
+  confusing `illegal_database_name`.
+* The Temporary view handling now expects a JSON request body, where the JSON
+  is an object with at least a `map` member, and optional `reduce` and
+  `language` members.
+* Temporary views no longer determine the view server based on the Content-Type
+  header of the `POST` request, but rather by looking for a `language` member
+  in the JSON body of the request.
+* The status code of responses to `DELETE` requests is now 200 to reflect that
+  that the deletion is performed synchronously.

http://git-wip-us.apache.org/repos/asf/couchdb/blob/84226656/share/doc/src/changes.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/changes.rst b/share/doc/src/changes.rst
new file mode 100644
index 0000000..0d98c86
--- /dev/null
+++ b/share/doc/src/changes.rst
@@ -0,0 +1,214 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. _changes:
+
+============
+Changes Feed
+============
+
+Polling
+=======
+
+A list of changes made to documents in the database, in the order they were
+made, can be obtained from the database's ``_changes`` resource. You can query
+the ``_changes`` resource by issuing a ``GET`` request with the following
+(optional) parameters:
+
++--------------+----------------------------------------------+---------------+--------------+
+| Parameter    | Value                                        | Default Value |  Notes       |
++==============+==============================================+===============+==============+
+| since        | seqnum / now                                 | 0             | \(1)         |
++--------------+----------------------------------------------+---------------+--------------+
+| limit        | maxsequences                                 | none          | \(2)         |
++--------------+----------------------------------------------+---------------+--------------+
+| descending   | boolean                                      | false         | \(3)         |
++--------------+----------------------------------------------+---------------+--------------+
+| feed         | normal / longpoll / continuous / eventsource | normal        | \(4)         |
++--------------+----------------------------------------------+---------------+--------------+
+| heartbeat    | milliseconds                                 | 60000         | \(5)         |
++--------------+----------------------------------------------+---------------+--------------+
+| timeout      | milliseconds                                 | 60000         | \(6)         |
++--------------+----------------------------------------------+---------------+--------------+
+| filter       | designdoc/filtername / _view                 | none          | \(7)         |
++--------------+----------------------------------------------+---------------+--------------+
+| include_docs | boolean                                      | false         | \(8)         |
++--------------+----------------------------------------------+---------------+--------------+
+| style        | all_docs / main_only                         | main_only     | \(9)         |
++--------------+----------------------------------------------+---------------+--------------+
+| view         | designdoc/filtername                         | none          | \(10)        |
++--------------+----------------------------------------------+---------------+--------------+
+
+Notes:
+
+(1) Start the results from the change immediately after the given sequence
+    number.
+
+(2) Limit number of result rows to the specified value (note that using 0 here
+    has the same effect as 1).
+
+(3) Return the change results in descending sequence order (most recent change
+    first)
+
+(4) Select the type of feed.
+
+(5) Period in milliseconds after which an empty line is sent in the results.
+    Only applicable for `longpoll` or `continuous` feeds. Overrides any timeout
+    to keep the feed alive indefinitely.
+
+(6) Maximum period in milliseconds to wait for a change before the response is
+    sent, even if there are no results. Only applicable for `longpoll` or
+    `continuous` feeds. Note that 60000 is also the default maximum timeout to
+    prevent undetected dead connections.
+
+    You can change the default maximum timeout in your ini-configuration:
+
+    .. code-block:: ini
+
+        [httpd]
+        changes_timeout=#millisecs
+
+(7) Reference to a :ref:`filter function <filterfun>` from a design document
+    that will filter whole stream emitting only filtered events.
+    See the `section in the book`_ for more information.
+
+(8) Include the associated document with each result. If there are conflicts,
+    only the winning revision is returned.
+
+(9) Specifies how many revisions are returned in the changes array.
+    The default, `main_only`, will only return the current "winning" revision;
+    `all_docs` will return all leaf revisions (including conflicts and deleted
+    former conflicts.)
+
+(10) Allows to use view functions as filters. It requires to set ``filter``
+     special value `_view` to enable this feature. Documents counted as "passed"
+     for view filter in case if map function emits at least one record for them.
+
+.. versionchanged:: 0.11.0 added ``include_docs`` parameter
+.. versionchanged:: 1.2.0 added ``view`` parameter and special value `_view`
+   for ``filter`` one
+.. versionchanged:: 1.3.0 ``since`` parameter could take `now` value to start
+   listen changes since current seq number.
+.. versionchanged:: 1.3.0 ``eventsource`` feed type added.
+
+By default all changes are immediately returned as a JSON object::
+
+    GET /somedatabase/_changes HTTP/1.1
+
+.. code-block:: javascript
+
+    {"results":[
+    {"seq":1,"id":"fresh","changes":[{"rev":"1-967a00dff5e02add41819138abb3284d"}]},
+    {"seq":3,"id":"updated","changes":[{"rev":"2-7051cbe5c8faecd085a3fa619e6e6337"}]},
+    {"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
+    ],
+    "last_seq":5}
+
+``results`` is the list of changes in sequential order. New and changed
+documents only differ in the value of the rev; deleted documents include the
+``"deleted": true`` attribute. (In the ``style=all_docs mode``, deleted applies
+only to the current/winning revision. The other revisions listed might be
+deleted even if there is no deleted property; you have to ``GET`` them
+individually to make sure.)
+
+``last_seq`` is the sequence number of the last update returned. (Currently it
+will always be the same as the seq of the last item in results.)
+
+Sending a ``since`` param in the query string skips all changes up to and
+including the given sequence number::
+
+    GET /somedatabase/_changes?since=3 HTTP/1.1
+
+.. code-block:: javascript
+
+    {"results":[
+    {"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
+    ],
+    "last_seq":5} 
+
+Long Polling
+============
+
+The `longpoll` feed (probably most useful used from a browser) is a more
+efficient form of polling that waits for a change to occur before the response
+is sent. `longpoll` avoids the need to frequently poll CouchDB to discover
+nothing has changed!
+
+The response is basically the same JSON as is sent for the normal feed.
+
+A timeout limits the maximum length of time the connection is open. If there
+are no changes before the timeout expires the response's results will be an
+empty list.  
+
+Continuous
+==========
+
+Polling the CouchDB server is not a good thing to do. Setting up new HTTP
+connections just to tell the client that nothing happened puts unnecessary
+strain on CouchDB.
+
+A continuous feed stays open and connected to the database until explicitly
+closed and changes are sent to the client as they happen, i.e. in near
+real-time.
+
+The continuous feed's response is a little different than the other feed types
+to simplify the job of the client - each line of the response is either empty
+or a JSON object representing a single change, as found in the normal feed's
+results.
+
+.. code-block:: text
+
+    GET /somedatabase/_changes?feed=continuous HTTP/1.1
+
+.. code-block:: javascript
+
+    {"seq":1,"id":"fresh","changes":[{"rev":"1-967a00dff5e02add41819138abb3284d"}]}
+    {"seq":3,"id":"updated","changes":[{"rev":"2-7051cbe5c8faecd085a3fa619e6e6337"}]}
+    {"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
+    ... tum tee tum ...
+    {"seq":6,"id":"updated","changes":[{"rev":"3-825cb35de44c433bfb2df415563a19de"}]}
+
+Obviously, `... tum tee tum ...` does not appear in the actual response, but
+represents a long pause before the change with seq 6 occurred.  
+
+.. _section in the book: http://books.couchdb.org/relax/reference/change-notifications
+
+Event Source
+============
+
+The `eventsource` feed provides push notifications that can be consumed in
+the form of DOM events in the browser. Refer to theW3C specification for
+`W3 eventsource specification`_ for further details.
+
+.. code-block:: text
+
+    GET /somedatabase/_changes?feed=eventsource HTTP/1.1
+
+.. code-block:: javascript
+
+    // define the event handling function
+    if (window.EventSource) {
+      var source = new EventSource(
+              "/somedatabase/_changes?feed=eventsource");
+      var results = [];
+      var sourceListener = function(e) {
+        var data = JSON.parse(e.data);
+        results.push(data);
+      };
+
+    // start listening for events
+    source.addEventListener('message', sourceListener , false);
+
+    // stop listening for events
+    source.removeEventListener('message', sourceListener , false);
+
+.. _W3 eventsource specification: http://www.w3.org/TR/eventsource/

http://git-wip-us.apache.org/repos/asf/couchdb/blob/84226656/share/doc/src/commonjs.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/commonjs.rst b/share/doc/src/commonjs.rst
new file mode 100644
index 0000000..49ccaa6
--- /dev/null
+++ b/share/doc/src/commonjs.rst
@@ -0,0 +1,56 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. _commonjs:
+
+CommonJS support for map functions
+==================================
+
+CommonJS support allows you to use `CommonJS notation <http://commonjs.org/specs>`_
+inside map and reduce functions, but only of libraries that are stored
+inside the views part of the design doc.
+
+So you could continue to access CommonJS code in design\_doc.foo, from
+your list functions etc, but we'd add the ability to require CommonJS
+modules within map and reduce, but only from ``design_doc.views.lib``.
+
+There's no worry here about namespace collisions, as Couch just plucks
+``views.*.map`` and ``views.*.reduce`` out of the design doc. So you
+could have a view called ``lib`` if you wanted, and still have CommonJS
+stored in ``views.lib.sha1`` and ``views.lib.stemmer`` if you wanted.
+
+The implementation is simplified by enforcing that CommonJS modules to
+be used in map functions be stored in views.lib.
+
+A sample design doc (taken from the test suite in Futon) is below:
+
+.. code-block:: javascript
+
+    {
+       "views" : {
+          "lib" : {
+             "baz" : "exports.baz = 'bam';",
+             "foo" : {
+                "zoom" : "exports.zoom = 'yeah';",
+                "boom" : "exports.boom = 'ok';",
+                "foo" : "exports.foo = 'bar';"
+             }
+          },
+          "commonjs" : {
+             "map" : "function(doc) { emit(null, require('views/lib/foo/boom').boom)}"
+          }
+       },
+       "_id" : "_design/test"
+    }
+
+The ``require()`` statement is relative to the design document, but
+anything loaded form outside of ``views/lib`` will fail.

http://git-wip-us.apache.org/repos/asf/couchdb/blob/84226656/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
new file mode 100644
index 0000000..26974fc
--- /dev/null
+++ b/share/doc/src/conf.py
@@ -0,0 +1,88 @@
+## Licensed under the Apache License, Version 2.0 (the "License"); you may not
+## use this file except in compliance with the License. You may obtain a copy of
+## the License at
+##
+##   http://www.apache.org/licenses/LICENSE-2.0
+##
+## Unless required by applicable law or agreed to in writing, software
+## distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+## WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+## License for the specific language governing permissions and limitations under
+## the License.
+
+import sys, os
+
+extensions = ["sphinx.ext.todo", "sphinx.ext.extlinks"]
+
+source_suffix = ".rst"
+
+master_doc = "index"
+
+nitpicky = True
+
+version = "1.3"
+
+release = "1.3.0"
+
+project = u"Apache CouchDB"
+
+copyright = u"2012, The Apache Software Foundation"
+
+highlight_language = "json"
+
+pygments_style = "sphinx"
+
+html_theme = "default"
+
+templates_path = ["../templates"]
+
+html_static_path = ["../static"]
+
+html_title = "Apache CouchDB " + version + " Manual"
+
+html_style = "rtd.css"
+
+html_logo = "../images/logo.png"
+
+html_favicon = "../images/favicon.ico"
+
+html_sidebars= {
+    "**": [
+        "searchbox.html",
+        "localtoc.html",
+        "relations.html",
+        "utilities.html",
+        "help.html",
+    ]
+}
+
+text_newlines = "native"
+
+latex_documents = [(
+    "index",
+    "CouchDB.tex",
+    project,
+    "",
+    "manual",
+    True
+)]
+
+latex_elements = {
+    "papersize":"a4paper"
+}
+
+texinfo_documents = [(
+    "index",
+    "CouchDB",
+    project,
+    "",
+    "CouchDB",
+    "The Apache CouchDB database",
+    "Databases",
+    True
+)]
+
+extlinks = {
+    'issue': ('https://issues.apache.org/jira/browse/COUCHDB-%s', 'COUCHDB-'),
+    'commit': ('https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=commit;h=%s', '#')
+}


Mime
View raw message