couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From kxe...@apache.org
Subject [22/26] documentation commit: updated refs/heads/master to 5a81ace
Date Fri, 20 Feb 2015 00:26:55 GMT
src/api now follows the style


Project: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/commit/25273e7a
Tree: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/tree/25273e7a
Diff: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/diff/25273e7a

Branch: refs/heads/master
Commit: 25273e7ac2ee0c7bf427d6bb847459d02437f1e6
Parents: 71a4fc9
Author: Maria Andersson <maria@dualpose.com>
Authored: Fri Feb 6 22:23:07 2015 +0100
Committer: Maria Andersson <maria@dualpose.com>
Committed: Fri Feb 6 22:23:07 2015 +0100

----------------------------------------------------------------------
 src/api/basics.rst               |  619 ++++++------
 src/api/database/bulk-api.rst    |  784 ++++++++-------
 src/api/database/changes.rst     |  614 ++++++------
 src/api/database/common.rst      |  635 ++++++------
 src/api/database/compact.rst     |  376 +++----
 src/api/database/index.rst       |   15 +-
 src/api/database/misc.rst        |  569 ++++++-----
 src/api/database/security.rst    |  313 +++---
 src/api/database/temp-views.rst  |  122 +--
 src/api/ddoc/common.rst          |  267 +++--
 src/api/ddoc/index.rst           |   29 +-
 src/api/ddoc/render.rst          |  537 +++++-----
 src/api/ddoc/rewrites.rst        |  145 +--
 src/api/ddoc/views.rst           | 1199 +++++++++++------------
 src/api/document/attachments.rst |  498 +++++-----
 src/api/document/common.rst      | 1720 ++++++++++++++++-----------------
 src/api/document/index.rst       |    6 +-
 src/api/index.rst                |   35 +-
 src/api/local.rst                |   49 +-
 src/api/server/authn.rst         |  418 ++++----
 src/api/server/common.rst        | 1209 ++++++++++++-----------
 src/api/server/configuration.rst |  505 +++++-----
 src/api/server/index.rst         |    8 +-
 23 files changed, 5278 insertions(+), 5394 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/basics.rst
----------------------------------------------------------------------
diff --git a/src/api/basics.rst b/src/api/basics.rst
index dfa9bfc..a7def38 100644
--- a/src/api/basics.rst
+++ b/src/api/basics.rst
@@ -16,32 +16,31 @@
 API Basics
 ==========
 
-The CouchDB API is the primary method of interfacing to a CouchDB
-instance. Requests are made using HTTP and requests are used to request
-information from the database, store new data, and perform views and
-formatting of the information stored within the documents.
-
-Requests to the API can be categorised by the different areas of the
-CouchDB system that you are accessing, and the HTTP method used to send
-the request. Different methods imply different operations, for example
-retrieval of information from the database is typically handled by the
-``GET`` operation, while updates are handled by either a ``POST`` or
-``PUT`` request. There are some differences between the information that
-must be supplied for the different methods. For a guide to the basic
-HTTP methods and request structure, see :ref:`api/format`.
-
-For nearly all operations, the submitted data, and the returned data
-structure, is defined within a JavaScript Object Notation (JSON) object.
-Basic information on the content and data types for JSON are provided in
-:ref:`json`.
-
-Errors when accessing the CouchDB API are reported using standard HTTP
-Status Codes. A guide to the generic codes returned by CouchDB are
-provided in :ref:`errors`.
-
-When accessing specific areas of the CouchDB API, specific information
-and examples on the HTTP methods and request, JSON structures, and error
-codes are provided.
+The CouchDB API is the primary method of interfacing to a CouchDB instance.
+Requests are made using HTTP and requests are used to request information from
+the database, store new data, and perform views and formatting of the
+information stored within the documents.
+
+Requests to the API can be categorised by the different areas of the CouchDB
+system that you are accessing, and the HTTP method used to send the request.
+Different methods imply different operations, for example retrieval of
+information from the database is typically handled by the ``GET`` operation,
+while updates are handled by either a ``POST`` or ``PUT`` request. There are
+some differences between the information that must be supplied for the
+different methods. For a guide to the basic HTTP methods and request structure,
+see :ref:`api/format`.
+
+For nearly all operations, the submitted data, and the returned data structure,
+is defined within a JavaScript Object Notation (JSON) object. Basic information
+on the content and data types for JSON are provided in :ref:`json`.
+
+Errors when accessing the CouchDB API are reported using standard HTTP Status
+Codes. A guide to the generic codes returned by CouchDB are provided in
+:ref:`errors`.
+
+When accessing specific areas of the CouchDB API, specific information and
+examples on the HTTP methods and request, JSON structures, and error codes are
+provided.
 
 .. _api/format:
 
@@ -50,43 +49,41 @@ Request Format and Responses
 
 CouchDB supports the following HTTP request methods:
 
--  ``GET``
+- ``GET``
 
-   Request the specified item. As with normal HTTP requests, the format
-   of the URL defines what is returned. With CouchDB this can include
-   static items, database documents, and configuration and statistical
-   information. In most cases the information is returned in the form of
-   a JSON document.
+  Request the specified item. As with normal HTTP requests, the format of the
+  URL defines what is returned. With CouchDB this can include static items,
+  database documents, and configuration and statistical information. In most
+  cases the information is returned in the form of a JSON document.
 
--  ``HEAD``
+- ``HEAD``
 
-   The ``HEAD`` method is used to get the HTTP header of a ``GET``
-   request without the body of the response.
+  The ``HEAD`` method is used to get the HTTP header of a ``GET`` request
+  without the body of the response.
 
--  ``POST``
+- ``POST``
 
-   Upload data. Within CouchDB ``POST`` is used to set values, including
-   uploading documents, setting document values, and starting certain
-   administration commands.
+  Upload data. Within CouchDB ``POST`` is used to set values, including
+  uploading documents, setting document values, and starting certain
+  administration commands.
 
--  ``PUT``
+- ``PUT``
 
-   Used to put a specified resource. In CouchDB ``PUT`` is used to
-   create new objects, including databases, documents, views and design
-   documents.
+  Used to put a specified resource. In CouchDB ``PUT`` is used to create new
+  objects, including databases, documents, views and design documents.
 
--  ``DELETE``
+- ``DELETE``
 
-   Deletes the specified resource, including documents, views, and
-   design documents.
+  Deletes the specified resource, including documents, views, and design
+  documents.
 
--  ``COPY``
+- ``COPY``
 
-   A special method that can be used to copy documents and objects.
+  A special method that can be used to copy documents and objects.
 
-If you use an unsupported HTTP request type with an URL that does not
-support the specified type then a ``405 - Resource Not Allowed`` will be
-returned, listing the supported HTTP methods. For example:
+If you use an unsupported HTTP request type with an URL that does not support
+the specified type then a ``405 - Resource Not Allowed`` will be returned,
+listing the supported HTTP methods. For example:
 
 .. code-block:: javascript
 
@@ -95,226 +92,214 @@ returned, listing the supported HTTP methods. For example:
         "reason":"Only GET,HEAD allowed"
     }
 
-
-The CouchDB design document API and the functions when returning HTML
-(for example as part of a show or list) enables you to include custom
-HTTP headers through the ``headers`` block of the return object.
+The CouchDB design document API and the functions when returning HTML (for
+example as part of a show or list) enables you to include custom HTTP headers
+through the ``headers`` block of the return object.
 
 HTTP Headers
 ============
 
-Because CouchDB uses HTTP for all communication, you need to ensure that
-the correct HTTP headers are supplied (and processed on retrieval) so
-that you get the right format and encoding. Different environments and
-clients will be more or less strict on the effect of these HTTP headers
-(especially when not present). Where possible you should be as specific
-as possible.
+Because CouchDB uses HTTP for all communication, you need to ensure that the
+correct HTTP headers are supplied (and processed on retrieval) so that you get
+the right format and encoding. Different environments and clients will be more
+or less strict on the effect of these HTTP headers (especially when not
+present). Where possible you should be as specific as possible.
 
 Request Headers
 ---------------
 
--  ``Accept``
-
-   Specifies the list of accepted data types to be returned by the
-   server (i.e. that are accepted/understandable by the client). The
-   format should be a list of one or more MIME types, separated by
-   colons.
+- ``Accept``
 
-   For the majority of requests the definition should be for JSON data
-   (``application/json``). For attachments you can either specify the
-   MIME type explicitly, or use ``*/*`` to specify that all file types
-   are supported. If the ``Accept`` header is not supplied, then the
-   ``*/*`` MIME type is assumed (i.e. client accepts all formats).
+  Specifies the list of accepted data types to be returned by the server (i.e.
+  that are accepted/understandable by the client). The format should be a list
+  of one or more MIME types, separated by colons.
 
-   The use of ``Accept`` in queries for CouchDB is not required, but is
-   highly recommended as it helps to ensure that the data returned can
-   be processed by the client.
+  For the majority of requests the definition should be for JSON data
+  (``application/json``). For attachments you can either specify the MIME type
+  explicitly, or use ``*/*`` to specify that all file types are supported. If
+  the ``Accept`` header is not supplied, then the ``*/*`` MIME type is assumed
+  (i.e. client accepts all formats).
 
-   If you specify a data type using the ``Accept`` header, CouchDB will
-   honor the specified type in the ``Content-type`` header field
-   returned. For example, if you explicitly request ``application/json``
-   in the ``Accept`` of a request, the returned HTTP headers will use
-   the value in the returned ``Content-type`` field.
+  The use of ``Accept`` in queries for CouchDB is not required, but is highly
+  recommended as it helps to ensure that the data returned can be processed by
+  the client.
 
-   For example, when sending a request without an explicit ``Accept``
-   header, or when specifying ``*/*``:
+  If you specify a data type using the ``Accept`` header, CouchDB will honor
+  the specified type in the ``Content-type`` header field returned. For
+  example, if you explicitly request ``application/json`` in the ``Accept`` of
+  a request, the returned HTTP headers will use the value in the returned
+  ``Content-type`` field.
 
-   .. code-block:: http
+  For example, when sending a request without an explicit ``Accept`` header, or
+  when specifying ``*/*``:
 
-       GET /recipes HTTP/1.1
-       Host: couchdb:5984
-       Accept: */*
+  .. code-block:: http
 
-   The returned headers are:
+      GET /recipes HTTP/1.1
+      Host: couchdb:5984
+      Accept: */*
 
-   .. code-block:: http
+  The returned headers are:
 
-       Server: CouchDB (Erlang/OTP)
-       Date: Thu, 13 Jan 2011 13:39:34 GMT
-       Content-Type: text/plain;charset=utf-8
-       Content-Length: 227
-       Cache-Control: must-revalidate
+  .. code-block:: http
 
-   .. Note::
-       The returned content type is ``text/plain`` even though the
-       information returned by the request is in JSON format.
+      Server: CouchDB (Erlang/OTP)
+      Date: Thu, 13 Jan 2011 13:39:34 GMT
+      Content-Type: text/plain;charset=utf-8
+      Content-Length: 227
+      Cache-Control: must-revalidate
 
+  .. Note::
+      The returned content type is ``text/plain`` even though the information
+      returned by the request is in JSON format.
 
-   Explicitly specifying the ``Accept`` header:
+  Explicitly specifying the ``Accept`` header:
 
-   .. code-block:: http
+  .. code-block:: http
 
-       GET /recipes HTTP/1.1
-       Host: couchdb:5984
-       Accept: application/json
+      GET /recipes HTTP/1.1
+      Host: couchdb:5984
+      Accept: application/json
 
-   The headers returned include the ``application/json`` content type:
+  The headers returned include the ``application/json`` content type:
 
-   .. code-block:: http
+  .. code-block:: http
 
-       Server: CouchDB (Erlang/OTP)
-       Date: Thu, 13 Jan 2013 13:40:11 GMT
-       Content-Type: application/json
-       Content-Length: 227
-       Cache-Control: must-revalidate
+      Server: CouchDB (Erlang/OTP)
+      Date: Thu, 13 Jan 2013 13:40:11 GMT
+      Content-Type: application/json
+      Content-Length: 227
+      Cache-Control: must-revalidate
 
--  ``Content-type``
+- ``Content-type``
 
-   Specifies the content type of the information being supplied within
-   the request. The specification uses MIME type specifications. For the
-   majority of requests this will be JSON (``application/json``). For
-   some settings the MIME type will be plain text. When uploading
-   attachments it should be the corresponding MIME type for the
-   attachment or binary (``application/octet-stream``).
+  Specifies the content type of the information being supplied within the
+  request. The specification uses MIME type specifications. For the majority of
+  requests this will be JSON (``application/json``). For some settings the MIME
+  type will be plain text. When uploading attachments it should be the
+  corresponding MIME type for the attachment or binary
+  (``application/octet-stream``).
 
-   The use of the ``Content-type`` on a request is highly recommended.
+  The use of the ``Content-type`` on a request is highly recommended.
 
 Response Headers
 ----------------
 
-Response headers are returned by the server when sending back content
-and include a number of different header fields, many of which are
-standard HTTP response header and have no significance to CouchDB
-operation. The list of response headers important to CouchDB are listed
-below.
+Response headers are returned by the server when sending back content and
+include a number of different header fields, many of which are standard HTTP
+response header and have no significance to CouchDB operation. The list of
+response headers important to CouchDB are listed below.
 
--  ``Cache-control``
+- ``Cache-control``
 
-   The cache control HTTP response header provides a suggestion for
-   client caching mechanisms on how to treat the returned information.
-   CouchDB typically returns the ``must-revalidate``, which indicates
-   that the information should be revalidated if possible. This is used
-   to ensure that the dynamic nature of the content is correctly
-   updated.
+  The cache control HTTP response header provides a suggestion for client
+  caching mechanisms on how to treat the returned information. CouchDB
+  typically returns the ``must-revalidate``, which indicates that the
+  information should be revalidated if possible. This is used to ensure that
+  the dynamic nature of the content is correctly updated.
 
--  ``Content-length``
+- ``Content-length``
 
-   The length (in bytes) of the returned content.
+  The length (in bytes) of the returned content.
 
--  ``Content-type``
+- ``Content-type``
 
-   Specifies the MIME type of the returned data. For most request, the
-   returned MIME type is ``text/plain``. All text is encoded in Unicode
-   (UTF-8), and this is explicitly stated in the returned
-   ``Content-type``, as ``text/plain;charset=utf-8``.
+  Specifies the MIME type of the returned data. For most request, the returned
+  MIME type is ``text/plain``. All text is encoded in Unicode (UTF-8), and this
+  is explicitly stated in the returned ``Content-type``, as
+  ``text/plain;charset=utf-8``.
 
--  ``Etag``
+- ``Etag``
 
-   The ``Etag`` HTTP header field is used to show the revision for a
-   document, or a view.
+  The ``Etag`` HTTP header field is used to show the revision for a document,
+  or a view.
 
-   ETags have been assigned to a map/reduce group (the collection of
-   views in a single design document). Any change to any of the indexes
-   for those views would generate a new ETag for all view URLs in a
-   single design doc, even if that specific view's results had not
-   changed.
+  ETags have been assigned to a map/reduce group (the collection of views in a
+  single design document). Any change to any of the indexes for those views
+  would generate a new ETag for all view URLs in a single design doc, even if
+  that specific view's results had not changed.
 
-   Each ``_view`` URL has its own ETag which only gets updated when
-   changes are made to the database that effect that index. If the
-   index for that specific view does not change, that view keeps the
-   original ETag head (therefore sending back ``304 - Not Modified``
-   more often).
+  Each ``_view`` URL has its own ETag which only gets updated when changes are
+  made to the database that effect that index. If the index for that specific
+  view does not change, that view keeps the original ETag head (therefore
+  sending back ``304 - Not Modified`` more often).
 
--  ``Transfer-Encoding``
+- ``Transfer-Encoding``
 
-   If the response uses an encoding, then it is specified in this
-   header field.
+  If the response uses an encoding, then it is specified in this header field.
 
-   ``Transfer-Encoding: chunked`` means that the response is sent in
-   parts, a method known as `chunked transfer encoding`_. This is used
-   when CouchDB does not know beforehand the size of the data it will
-   send (for example, the :ref:`changes feed <changes>`).
+  ``Transfer-Encoding: chunked`` means that the response is sent in parts, a
+  method known as `chunked transfer encoding`_. This is used when CouchDB does
+  not know beforehand the size of the data it will send (for example,
+  the :ref:`changes feed <changes>`).
 
 .. _chunked transfer encoding:
-   https://en.wikipedia.org/wiki/Chunked_transfer_encoding
+    https://en.wikipedia.org/wiki/Chunked_transfer_encoding
 
 .. _json:
 
 JSON Basics
 ===========
 
-The majority of requests and responses to CouchDB use the JavaScript
-Object Notation (JSON) for formatting the content and structure of the
-data and responses.
+The majority of requests and responses to CouchDB use the JavaScript Object
+Notation (JSON) for formatting the content and structure of the data and
+responses.
 
-JSON is used because it is the simplest and easiest solution for
-working with data within a web browser, as JSON structures can be
-evaluated and used as JavaScript objects within the web browser
-environment. JSON also integrates with the server-side JavaScript used
-within CouchDB.
+JSON is used because it is the simplest and easiest solution for working with
+data within a web browser, as JSON structures can be evaluated and used as
+JavaScript objects within the web browser environment. JSON also integrates
+with the server-side JavaScript used within CouchDB.
 
-JSON supports the same basic types as supported by JavaScript, these
-are:
+JSON supports the same basic types as supported by JavaScript, these are:
 
--  Array - a list of values enclosed in square brackets. For example:
+- Array - a list of values enclosed in square brackets. For example:
 
-   .. code-block:: javascript
+  .. code-block:: javascript
 
-       ["one", "two", "three"]
+      ["one", "two", "three"]
 
--  Boolean - a ``true`` or ``false`` value. You can use these strings
-   directly. For example:
+- Boolean - a ``true`` or ``false`` value. You can use these strings directly.
+  For example:
 
-   .. code-block:: javascript
+  .. code-block:: javascript
 
-       { "value": true}
+      { "value": true}
 
--  Number - an integer or floating-point number.
+- Number - an integer or floating-point number.
 
--  Object - a set of key/value pairs (i.e. an associative array, or
-   hash). The key must be a string, but the value can be any of the
-   supported JSON values. For example:
+- Object - a set of key/value pairs (i.e. an associative array, or hash). The
+  key must be a string, but the value can be any of the supported JSON values.
+  For example:
 
-   .. code-block:: javascript
+  .. code-block:: javascript
 
-       {
+      {
           "servings" : 4,
           "subtitle" : "Easy to make in advance, and then cook when ready",
           "cooktime" : 60,
           "title" : "Chicken Coriander"
-       }
+      }
 
-   In CouchDB, the JSON object is used to represent a variety of
-   structures, including the main CouchDB document.
+  In CouchDB, the JSON object is used to represent a variety of structures,
+  including the main CouchDB document.
 
--  String - this should be enclosed by double-quotes and supports Unicode
-   characters and backslash escaping. For example:
+- String - this should be enclosed by double-quotes and supports Unicode
+  characters and backslash escaping. For example:
 
-   .. code-block:: javascript
+  .. code-block:: javascript
 
-       "A String"
+      "A String"
 
-Parsing JSON into a JavaScript object is supported through the
-``JSON.parse()`` function in JavaScript, or through various libraries that
-will perform the parsing of the content into a JavaScript object for
-you. Libraries for parsing and generating JSON are available in many
-languages, including Perl, Python, Ruby, Erlang and others.
+Parsing JSON into a JavaScript object is supported through the ``JSON.parse()``
+function in JavaScript, or through various libraries that will perform the
+parsing of the content into a JavaScript object for you. Libraries for parsing
+and generating JSON are available in many languages, including Perl, Python,
+Ruby, Erlang and others.
 
 .. warning::
-   Care should be taken to ensure that your JSON structures are
-   valid, invalid structures will cause CouchDB to return an HTTP status code
-   of 500 (server error).
-
+    Care should be taken to ensure that your JSON structures are valid,
+    invalid structures will cause CouchDB to return an HTTP status code of 500
+    (server error).
 
 .. _json/numbers:
 
@@ -325,19 +310,19 @@ Developers and users new to computer handling of numbers often encounter
 suprises when expecting that a number stored in JSON format does not
 necessarily return as the same number as compared character by character.
 
-Any numbers defined in JSON that contain a decimal point or exponent
-will be passed through the Erlang VM's idea of the "double" data type.
-Any numbers that are used in views will pass through the view server's
-idea of a number (the common JavaScript case means even integers pass
-through a double due to JavaScript's definition of a number).
+Any numbers defined in JSON that contain a decimal point or exponent will be
+passed through the Erlang VM's idea of the "double" data type. Any numbers that
+are used in views will pass through the view server's idea of a number (the
+common JavaScript case means even integers pass through a double due to
+JavaScript's definition of a number).
 
 Consider this document that we write to CouchDB:
 
 .. code-block:: javascript
 
     {
-      "_id":"30b3b38cdbd9e3a587de9b8122000cff",
-      "number": 1.1
+        "_id":"30b3b38cdbd9e3a587de9b8122000cff",
+        "number": 1.1
     }
 
 Now let’s read that document back from CouchDB:
@@ -345,12 +330,11 @@ Now let’s read that document back from CouchDB:
 .. code-block:: javascript
 
     {
-      "_id":"30b3b38cdbd9e3a587de9b8122000cff",
-      "_rev":"1-f065cee7c3fd93aa50f6c97acde93030",
-      "number":1.1000000000000000888
+        "_id":"30b3b38cdbd9e3a587de9b8122000cff",
+        "_rev":"1-f065cee7c3fd93aa50f6c97acde93030",
+        "number":1.1000000000000000888
     }
 
-
 What happens is CouchDB is changing the textual representation of the
 result of decoding what it was given into some numerical format. In most
 cases this is an `IEEE 754`_ double precision floating point number which
@@ -358,29 +342,27 @@ is exactly what almost all other languages use as well.
 
 .. _IEEE 754: https://en.wikipedia.org/wiki/IEEE_754-2008
 
-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:
+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:
 
 .. code-block:: erlang
 
     ejson:encode(ejson:decode(<<"1.1">>)).
     <<"1.1000000000000000888">>
 
-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 we know about.
+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 we know
+about.
 
-While we've only been discussing cases where the textual
-representation changes, another important case is when an input value
-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).
+While we've only been discussing cases where the textual representation
+changes, another important case is when an input value 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 that happen
-to be on the author's machine:
+Here's a log for a couple of the more common JSON libraries that happen to be
+on the author's machine:
 
 Ejson (CouchDB's current parser) at CouchDB sha 168a663b::
 
@@ -434,9 +416,10 @@ Ruby::
     JSON.dump(JSON.load(f))
     => "[1.01234567890123]"
 
-.. note:: A small aside on Ruby, it requires a top level object or array, so I just
-         wrapped the value. Should be obvious it doesn't affect the result of
-         parsing the number though.
+.. note::
+    A small aside on Ruby, it requires a top level object or array, so I just
+    wrapped the value. Should be obvious it doesn't affect the result of
+    parsing the number though.
 
 Spidermonkey::
 
@@ -449,53 +432,49 @@ Spidermonkey::
     js> JSON.stringify(JSON.parse(f))
     "1.0123456789012346"
 
-As you can see they all pretty much behave the same except for Ruby
-actually does appear to be losing some precision over the other
-libraries.
+As you can see they all pretty much behave the same except for Ruby actually
+does appear to be losing some precision over the other libraries.
 
-The astute observer will notice that ejson (the CouchDB JSON library)
-reported an extra three digits. While its tempting to think that this
-is due to some internal difference, its just a more specific case of
-the 1.1 input as described above.
+The astute observer will notice that ejson (the CouchDB JSON library) reported
+an extra three digits. While its tempting to think that this is due to some
+internal difference, its just a more specific case of the 1.1 input as
+described above.
 
-The important point to realize here is that a double can only hold a
-finite number of values. What we're doing here is generating a string
-that when passed through the "standard" floating point parsing
-algorithms (ie, ``strtod``) will result in the same bit pattern in memory
-as we started with. Or, slightly different, the bytes in a JSON
-serialized number are chosen such that they refer to a single specific
-value that a double can represent.
+The important point to realize here is that a double can only hold a finite
+number of values. What we're doing here is generating a string that when passed
+through the "standard" floating point parsing algorithms (ie, ``strtod``) will
+result in the same bit pattern in memory as we started with. Or, slightly
+different, the bytes in a JSON serialized number are chosen such that they
+refer to a single specific value that a double can represent.
 
-The important point to understand is that we're mapping from one
-infinite set onto a finite set. An easy way to see this is by
-reflecting on this::
+The important point to understand is that we're mapping from one infinite set
+onto a finite set. An easy way to see this is by reflecting on this::
 
     1.0 == 1.00 == 1.000 = 1.(infinite zeroes)
 
-Obviously a computer can't hold infinite bytes so we have to
-decimate our infinitely sized set to a finite set that can be
-represented concisely.
+Obviously a computer can't hold infinite bytes so we have to decimate our
+infinitely sized set to a finite set that can be represented concisely.
 
 The game that other JSON libraries are playing is merely:
 
-"How few characters do I have to use to select this specific value for a double"
+"How few characters do I have to use to select this specific value for a
+double"
 
-And that game has lots and lots of subtle details that are difficult
-to duplicate in C without a significant amount of effort (it took
-Python over a year to get it sorted with their fancy build systems
-that automatically run on a number of different architectures).
+And that game has lots and lots of subtle details that are difficult to
+duplicate in C without a significant amount of effort (it took Python over a
+year to get it sorted with their fancy build systems that automatically run on
+a number of different architectures).
 
-Hopefully we've shown that CouchDB is not doing anything "funky" by
-changing input. Its behaving the same as any other common JSON library
-does, its just not pretty printing its output.
+Hopefully we've shown that CouchDB is not doing anything "funky" by changing
+input. Its behaving the same as any other common JSON library does, its just
+not pretty printing its output.
 
-On the other hand, if you actually are in a position where an IEEE-754
-double is not a satisfactory datatype for your numbers, then the
-answer as has been stated is to not pass your numbers through this
-representation. In JSON this is accomplished by encoding them as a
-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).
+On the other hand, if you actually are in a position where an IEEE-754 double
+is not a satisfactory datatype for your numbers, then the answer as has been
+stated is to not pass your numbers through this representation. In JSON this is
+accomplished by encoding them as a 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).
 
 Further information can be found easily, including the
 `Floating Point Guide`_, and  `David Goldberg's Reference`_.
@@ -503,12 +482,11 @@ Further information can be found easily, including the
 .. _Floating Point Guide: http://floating-point-gui.de/
 .. _David Goldberg's Reference: http://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html
 
-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 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.
+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 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
 
@@ -517,96 +495,91 @@ holler.
 HTTP Status Codes
 =================
 
-With the interface to CouchDB working through HTTP, error codes and
-statuses are reported using a combination of the HTTP status code
-number, and corresponding data in the body of the response data.
+With the interface to CouchDB working through HTTP, error codes and statuses
+are reported using a combination of the HTTP status code number, and
+corresponding data in the body of the response data.
 
-A list of the error codes returned by CouchDB, and generic descriptions
-of the related errors are provided below. The meaning of different
-status codes for specific request types are provided in the
-corresponding API call reference.
+A list of the error codes returned by CouchDB, and generic descriptions of the
+related errors are provided below. The meaning of different status codes for
+specific request types are provided in the corresponding API call reference.
 
--  ``200 - OK``
+- ``200 - OK``
 
-   Request completed successfully.
+  Request completed successfully.
 
--  ``201 - Created``
+- ``201 - Created``
 
-   Document created successfully.
+  Document created successfully.
 
--  ``202 - Accepted``
+- ``202 - Accepted``
 
-   Request has been accepted, but the corresponding operation may not
-   have completed. This is used for background operations, such as
-   database compaction.
+  Request has been accepted, but the corresponding operation may not have
+  completed. This is used for background operations, such as database
+  compaction.
 
--  ``304 - Not Modified``
+- ``304 - Not Modified``
 
-   The additional content requested has not been modified. This is used
-   with the ETag system to identify the version of information returned.
+  The additional content requested has not been modified. This is used with the
+  ETag system to identify the version of information returned.
 
--  ``400 - Bad Request``
+- ``400 - Bad Request``
 
-   Bad request structure. The error can indicate an error with the
-   request URL, path or headers. Differences in the supplied MD5 hash
-   and content also trigger this error, as this may indicate message
-   corruption.
+  Bad request structure. The error can indicate an error with the request URL,
+  path or headers. Differences in the supplied MD5 hash and content also
+  trigger this error, as this may indicate message corruption.
 
--  ``401 - Unauthorized``
+- ``401 - Unauthorized``
 
-   The item requested was not available using the supplied
-   authorization, or authorization was not supplied.
+  The item requested was not available using the supplied authorization, or
+  authorization was not supplied.
 
--  ``403 - Forbidden``
+- ``403 - Forbidden``
 
-   The requested item or operation is forbidden.
+  The requested item or operation is forbidden.
 
--  ``404 - Not Found``
+- ``404 - Not Found``
 
-   The requested content could not be found. The content will include
-   further information, as a JSON object, if available. The structure
-   will contain two keys, ``error`` and ``reason``. For example:
+  The requested content could not be found. The content will include further
+  information, as a JSON object, if available. The structure will contain two
+  keys, ``error`` and ``reason``. For example:
 
-   .. code-block:: javascript
+  .. code-block:: javascript
 
-       {"error":"not_found","reason":"no_db_file"}
+      {"error":"not_found","reason":"no_db_file"}
 
--  ``405 - Resource Not Allowed``
+- ``405 - Resource Not Allowed``
 
-   A request was made using an invalid HTTP request type for the URL
-   requested. For example, you have requested a ``PUT`` when a ``POST``
-   is required. Errors of this type can also triggered by invalid URL
-   strings.
+  A request was made using an invalid HTTP request type for the URL requested.
+  For example, you have requested a ``PUT`` when a ``POST`` is required. Errors
+  of this type can also triggered by invalid URL strings.
 
--  ``406 - Not Acceptable``
+- ``406 - Not Acceptable``
 
-   The requested content type is not supported by the server.
+  The requested content type is not supported by the server.
 
--  ``409 - Conflict``
+- ``409 - Conflict``
 
-   Request resulted in an update conflict.
+  Request resulted in an update conflict.
 
--  ``412 - Precondition Failed``
+- ``412 - Precondition Failed``
 
-   The request headers from the client and the capabilities of the
-   server do not match.
+  The request headers from the client and the capabilities of the server do not
+  match.
 
--  ``415 - Bad Content Type``
+- ``415 - Bad Content Type``
 
-   The content types supported, and the content type of the information
-   being requested or submitted indicate that the content type is not
-   supported.
+  The content types supported, and the content type of the information being
+  requested or submitted indicate that the content type is not supported.
 
--  ``416 - Requested Range Not Satisfiable``
+- ``416 - Requested Range Not Satisfiable``
 
-   The range specified in the request header cannot be satisfied by the
-   server.
+  The range specified in the request header cannot be satisfied by the server.
 
--  ``417 - Expectation Failed``
+- ``417 - Expectation Failed``
 
-   When sending documents in bulk, the bulk load operation failed.
+  When sending documents in bulk, the bulk load operation failed.
 
--  ``500 - Internal Server Error``
+- ``500 - Internal Server Error``
 
-   The request was invalid, either because the supplied JSON was
-   invalid, or invalid information was supplied as part of the request.
+  The request was invalid, either because the supplied JSON was invalid, or
+  invalid information was supplied as part of the request.

http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/database/bulk-api.rst
----------------------------------------------------------------------
diff --git a/src/api/database/bulk-api.rst b/src/api/database/bulk-api.rst
index d13ff30..22a6197 100644
--- a/src/api/database/bulk-api.rst
+++ b/src/api/database/bulk-api.rst
@@ -10,280 +10,278 @@
 .. License for the specific language governing permissions and limitations under
 .. the License.
 
-
 .. _api/db/all_docs:
 
+=================
 ``/db/_all_docs``
 =================
 
 .. http:get:: /{db}/_all_docs
-  :synopsis: Returns a built-in view of all documents in this database
-
-  Returns a JSON structure of all of the documents in a given database.
-  The information is returned as a JSON structure containing meta
-  information about the return structure, including a list of all documents
-  and basic contents, consisting the ID, revision and key. The key is the
-  from the document's ``_id``.
-
-  :param db: Database name
-  :<header Accept: - :mimetype:`application/json`
-                   - :mimetype:`text/plain`
-  :query boolean conflicts: Includes `conflicts` information in response.
-    Ignored if `include_docs` isn't ``true``. Default is ``false``.
-  :query boolean descending: Return the documents in descending by key order.
-    Default is ``false``.
-  :query string endkey: Stop returning records when the specified key is
-    reached. *Optional*.
-  :query string end_key: Alias for `endkey` param.
-  :query string endkey_docid: Stop returning records when the specified
-    document ID is reached. *Optional*.
-  :query string end_key_doc_id: Alias for `endkey_docid` param.
-  :query boolean include_docs: Include the full content of the documents in
-    the return. Default is ``false``.
-  :query boolean inclusive_end: Specifies whether the specified end key should
-    be included in the result. Default is ``true``.
-  :query string key: Return only documents that match the specified key.
-    *Optional*.
-  :query number limit: Limit the number of the returned documents to the
-    specified number. *Optional*.
-  :query number skip: Skip this number of records before starting to return
-    the results. Default is ``0``.
-  :query string stale: Allow the results from a stale view to be used, without
-    triggering a rebuild of all views within the encompassing design doc.
-    Supported values: ``ok`` and ``update_after``. *Optional*.
-  :query string startkey: Return records starting with the specified key.
-    *Optional*.
-  :query string start_key: Alias for `startkey` param.
-  :query string startkey_docid: Return records starting with the specified
-    document ID. *Optional*.
-  :query string start_key_doc_id: Alias for `startkey_docid` param.
-  :query boolean update_seq: Response includes an ``update_seq`` value
-    indicating which sequence id of the underlying database the view reflects.
-    Default is ``false``.
-  :>header Content-Type: - :mimetype:`application/json`
-                         - :mimetype:`text/plain; charset=utf-8`
-  :>header ETag: Response signature
-  :>json number offset: Offset where the document list started
-  :>json array rows: Array of view row objects. By default the information
-    returned contains only the document ID and revision.
-  :>json number total_rows: Number of documents in the database/view. Note that
-    this is not the number of rows returned in the actual query.
-  :>json number update_seq: Current update sequence for the database
-  :code 200: Request completed successfully
-
-  **Request**:
-
-  .. code-block:: http
-
-    GET /db/_all_docs HTTP/1.1
-    Accept: application/json
-    Host: localhost:5984
+    :synopsis: Returns a built-in view of all documents in this database
+
+    Returns a JSON structure of all of the documents in a given database.
+    The information is returned as a JSON structure containing meta
+    information about the return structure, including a list of all documents
+    and basic contents, consisting the ID, revision and key. The key is the
+    from the document's ``_id``.
+
+    :param db: Database name
+    :<header Accept: - :mimetype:`application/json`
+                     - :mimetype:`text/plain`
+    :query boolean conflicts: Includes `conflicts` information in response.
+      Ignored if `include_docs` isn't ``true``. Default is ``false``.
+    :query boolean descending: Return the documents in descending by key order.
+      Default is ``false``.
+    :query string endkey: Stop returning records when the specified key is
+      reached. *Optional*.
+    :query string end_key: Alias for `endkey` param.
+    :query string endkey_docid: Stop returning records when the specified
+      document ID is reached. *Optional*.
+    :query string end_key_doc_id: Alias for `endkey_docid` param.
+    :query boolean include_docs: Include the full content of the documents in
+      the return. Default is ``false``.
+    :query boolean inclusive_end: Specifies whether the specified end key
+      should be included in the result. Default is ``true``.
+    :query string key: Return only documents that match the specified key.
+      *Optional*.
+    :query number limit: Limit the number of the returned documents to the
+      specified number. *Optional*.
+    :query number skip: Skip this number of records before starting to return
+      the results. Default is ``0``.
+    :query string stale: Allow the results from a stale view to be used,
+      without triggering a rebuild of all views within the encompassing design
+      doc. Supported values: ``ok`` and ``update_after``. *Optional*.
+    :query string startkey: Return records starting with the specified key.
+      *Optional*.
+    :query string start_key: Alias for `startkey` param.
+    :query string startkey_docid: Return records starting with the specified
+      document ID. *Optional*.
+    :query string start_key_doc_id: Alias for `startkey_docid` param.
+    :query boolean update_seq: Response includes an ``update_seq`` value
+      indicating which sequence id of the underlying database the view
+      reflects. Default is ``false``.
+    :>header Content-Type: - :mimetype:`application/json`
+                           - :mimetype:`text/plain; charset=utf-8`
+    :>header ETag: Response signature
+    :>json number offset: Offset where the document list started
+    :>json array rows: Array of view row objects. By default the information
+      returned contains only the document ID and revision.
+    :>json number total_rows: Number of documents in the database/view. Note
+      that this is not the number of rows returned in the actual query.
+    :>json number update_seq: Current update sequence for the database
+    :code 200: Request completed successfully
+
+    **Request**:
+
+    .. code-block:: http
+
+        GET /db/_all_docs HTTP/1.1
+        Accept: application/json
+        Host: localhost:5984
+
+    **Response**:
+
+    .. code-block:: http
+
+        HTTP/1.1 200 OK
+        Cache-Control: must-revalidate
+        Content-Type: application/json
+        Date: Sat, 10 Aug 2013 16:22:56 GMT
+        ETag: "1W2DJUZFZSZD9K78UFA3GZWB4"
+        Server: CouchDB (Erlang/OTP)
+        Transfer-Encoding: chunked
 
-  **Response**:
-
-  .. code-block:: http
-
-    HTTP/1.1 200 OK
-    Cache-Control: must-revalidate
-    Content-Type: application/json
-    Date: Sat, 10 Aug 2013 16:22:56 GMT
-    ETag: "1W2DJUZFZSZD9K78UFA3GZWB4"
-    Server: CouchDB (Erlang/OTP)
-    Transfer-Encoding: chunked
-
-    {
-        "offset": 0,
-        "rows": [
-            {
-                "id": "16e458537602f5ef2a710089dffd9453",
-                "key": "16e458537602f5ef2a710089dffd9453",
-                "value": {
-                    "rev": "1-967a00dff5e02add41819138abb3284d"
-                }
-            },
-            {
-                "id": "a4c51cdfa2069f3e905c431114001aff",
-                "key": "a4c51cdfa2069f3e905c431114001aff",
-                "value": {
-                    "rev": "1-967a00dff5e02add41819138abb3284d"
-                }
-            },
-            {
-                "id": "a4c51cdfa2069f3e905c4311140034aa",
-                "key": "a4c51cdfa2069f3e905c4311140034aa",
-                "value": {
-                    "rev": "5-6182c9c954200ab5e3c6bd5e76a1549f"
-                }
-            },
-            {
-                "id": "a4c51cdfa2069f3e905c431114003597",
-                "key": "a4c51cdfa2069f3e905c431114003597",
-                "value": {
-                    "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
-                }
-            },
-            {
-                "id": "f4ca7773ddea715afebc4b4b15d4f0b3",
-                "key": "f4ca7773ddea715afebc4b4b15d4f0b3",
-                "value": {
-                    "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
+        {
+            "offset": 0,
+            "rows": [
+                {
+                    "id": "16e458537602f5ef2a710089dffd9453",
+                    "key": "16e458537602f5ef2a710089dffd9453",
+                    "value": {
+                        "rev": "1-967a00dff5e02add41819138abb3284d"
+                    }
+                },
+                {
+                    "id": "a4c51cdfa2069f3e905c431114001aff",
+                    "key": "a4c51cdfa2069f3e905c431114001aff",
+                    "value": {
+                        "rev": "1-967a00dff5e02add41819138abb3284d"
+                    }
+                },
+                {
+                    "id": "a4c51cdfa2069f3e905c4311140034aa",
+                    "key": "a4c51cdfa2069f3e905c4311140034aa",
+                    "value": {
+                        "rev": "5-6182c9c954200ab5e3c6bd5e76a1549f"
+                    }
+                },
+                {
+                    "id": "a4c51cdfa2069f3e905c431114003597",
+                    "key": "a4c51cdfa2069f3e905c431114003597",
+                    "value": {
+                        "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
+                    }
+                },
+                {
+                    "id": "f4ca7773ddea715afebc4b4b15d4f0b3",
+                    "key": "f4ca7773ddea715afebc4b4b15d4f0b3",
+                    "value": {
+                        "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
+                    }
                 }
-            }
-        ],
-        "total_rows": 5
-    }
-
+            ],
+            "total_rows": 5
+        }
 
 .. http:post:: /{db}/_all_docs
-  :synopsis: Returns certain rows from the built-in view of all documents
+    :synopsis: Returns certain rows from the built-in view of all documents
 
-  The ``POST`` to ``_all_docs`` allows to specify multiple keys to be
-  selected from the database. This enables you to request multiple
-  documents in a single request, in place of multiple :get:`/{db}/{docid}`
-  requests.
+    The ``POST`` to ``_all_docs`` allows to specify multiple keys to be
+    selected from the database. This enables you to request multiple
+    documents in a single request, in place of multiple :get:`/{db}/{docid}`
+    requests.
 
-  The request body should contain a list of the keys to be returned as an
-  array to a ``keys`` object. For example:
+    The request body should contain a list of the keys to be returned as an
+    array to a ``keys`` object. For example:
 
-  .. code-block:: http
+    .. code-block:: http
 
-    POST /db/_all_docs HTTP/1.1
-    Accept: application/json
-    Content-Length: 70
-    Content-Type: application/json
-    Host: localhost:5984
+        POST /db/_all_docs HTTP/1.1
+        Accept: application/json
+        Content-Length: 70
+        Content-Type: application/json
+        Host: localhost:5984
 
-    {
-       "keys" : [
-          "Zingylemontart",
-          "Yogurtraita"
-       ]
-    }
-
-  The returned JSON is the all documents structure, but with only the
-  selected keys in the output:
+        {
+            "keys" : [
+                "Zingylemontart",
+                "Yogurtraita"
+            ]
+        }
 
-  .. code-block:: javascript
+    The returned JSON is the all documents structure, but with only the
+    selected keys in the output:
 
-      {
-         "total_rows" : 2666,
-         "rows" : [
-            {
-               "value" : {
-                  "rev" : "1-a3544d296de19e6f5b932ea77d886942"
-               },
-               "id" : "Zingylemontart",
-               "key" : "Zingylemontart"
-            },
-            {
-               "value" : {
-                  "rev" : "1-91635098bfe7d40197a1b98d7ee085fc"
-               },
-               "id" : "Yogurtraita",
-               "key" : "Yogurtraita"
-            }
-         ],
-         "offset" : 0
-      }
+    .. code-block:: javascript
 
+        {
+            "total_rows" : 2666,
+            "rows" : [
+                {
+                    "value" : {
+                        "rev" : "1-a3544d296de19e6f5b932ea77d886942"
+                    },
+                    "id" : "Zingylemontart",
+                    "key" : "Zingylemontart"
+                },
+                {
+                    "value" : {
+                        "rev" : "1-91635098bfe7d40197a1b98d7ee085fc"
+                    },
+                    "id" : "Yogurtraita",
+                    "key" : "Yogurtraita"
+                }
+            ],
+            "offset" : 0
+        }
 
 .. _api/db/bulk_docs:
 
+==================
 ``/db/_bulk_docs``
 ==================
 
 .. http:post:: /{db}/_bulk_docs
-  :synopsis: Inserts or updates multiple documents in to the database in a single request
-
-  The bulk document API allows you to create and update multiple documents
-  at the same time within a single request. The basic operation is similar
-  to creating or updating a single document, except that you batch the
-  document structure and information.
-
-  When creating new documents the document ID (``_id``) is optional.
-
-  For updating existing documents, you must provide the document ID, revision
-  information (``_rev``), and new document values.
-
-  In case of batch deleting documents all fields as document ID, revision
-  information and deletion status (``_deleted``) are required.
-
-  :param db: Database name
-  :<header Accept: - :mimetype:`application/json`
-                   - :mimetype:`text/plain`
-  :<header Content-Type: :mimetype:`application/json`
-  :<header X-Couch-Full-Commit: Overrides server's
-    :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
-    are: ``false`` and ``true``. *Optional*
-  :<json boolean all_or_nothing: Sets the database commit mode to use
-    :ref:`all-or-nothing <api/db/bulk_docs/semantics>` semantics.
-    Default is ``false``. *Optional*
-  :<json array docs: List of documents objects
-  :<json boolean new_edits: If ``false``, prevents the database from assigning
-    them new revision IDs. Default is ``true``. *Optional*
-  :>header Content-Type: - :mimetype:`application/json`
-                         - :mimetype:`text/plain; charset=utf-8`
-  :>jsonarr string id: Document ID
-  :>jsonarr string rev: New document revision token. Available
-    if document have saved without errors. *Optional*
-  :>jsonarr string error: Error type. *Optional*
-  :>jsonarr string reason: Error reason. *Optional*
-  :code 201: Document(s) have been created or updated
-  :code 400: The request provided invalid JSON data
-  :code 417: Occurs when ``all_or_nothing`` option set as ``true`` and
-    at least one document was rejected by :ref:`validation function <vdufun>`
-  :code 500: Malformed data provided, while it's still valid JSON
-
-  **Request**:
-
-  .. code-block:: http
-
-    POST /db/_bulk_docs HTTP/1.1
-    Accept: application/json
-    Content-Length: 109
-    Content-Type:application/json
-    Host: localhost:5984
+    :synopsis: Inserts or updates multiple documents in to the database in a single request
+
+    The bulk document API allows you to create and update multiple documents
+    at the same time within a single request. The basic operation is similar
+    to creating or updating a single document, except that you batch the
+    document structure and information.
+
+    When creating new documents the document ID (``_id``) is optional.
+
+    For updating existing documents, you must provide the document ID, revision
+    information (``_rev``), and new document values.
+
+    In case of batch deleting documents all fields as document ID, revision
+    information and deletion status (``_deleted``) are required.
+
+    :param db: Database name
+    :<header Accept: - :mimetype:`application/json`
+                     - :mimetype:`text/plain`
+    :<header Content-Type: :mimetype:`application/json`
+    :<header X-Couch-Full-Commit: Overrides server's
+      :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
+      are: ``false`` and ``true``. *Optional*
+    :<json boolean all_or_nothing: Sets the database commit mode to use
+      :ref:`all-or-nothing <api/db/bulk_docs/semantics>` semantics.
+      Default is ``false``. *Optional*
+    :<json array docs: List of documents objects
+    :<json boolean new_edits: If ``false``, prevents the database from
+      assigning them new revision IDs. Default is ``true``. *Optional*
+    :>header Content-Type: - :mimetype:`application/json`
+                           - :mimetype:`text/plain; charset=utf-8`
+    :>jsonarr string id: Document ID
+    :>jsonarr string rev: New document revision token. Available
+      if document have saved without errors. *Optional*
+    :>jsonarr string error: Error type. *Optional*
+    :>jsonarr string reason: Error reason. *Optional*
+    :code 201: Document(s) have been created or updated
+    :code 400: The request provided invalid JSON data
+    :code 417: Occurs when ``all_or_nothing`` option set as ``true`` and
+      at least one document was rejected by :ref:`validation function <vdufun>`
+    :code 500: Malformed data provided, while it's still valid JSON
+
+    **Request**:
+
+    .. code-block:: http
+
+        POST /db/_bulk_docs HTTP/1.1
+        Accept: application/json
+        Content-Length: 109
+        Content-Type:application/json
+        Host: localhost:5984
 
-    {
-      "docs": [
-        {
-          "_id": "FishStew"
-        },
         {
-          "_id": "LambStew",
-          "_rev": "2-0786321986194c92dd3b57dfbfc741ce",
-          "_deleted": true
+            "docs": [
+                {
+                    "_id": "FishStew"
+                },
+                {
+                    "_id": "LambStew",
+                    "_rev": "2-0786321986194c92dd3b57dfbfc741ce",
+                    "_deleted": true
+                }
+            ]
         }
-      ]
-    }
 
-  **Response**:
+    **Response**:
 
-  .. code-block:: http
+    .. code-block:: http
 
-    HTTP/1.1 201 Created
-    Cache-Control: must-revalidate
-    Content-Length: 144
-    Content-Type: application/json
-    Date: Mon, 12 Aug 2013 00:15:05 GMT
-    Server: CouchDB (Erlang/OTP)
-
-    [
-      {
-        "ok": true,
-        "id": "FishStew",
-        "rev":" 1-967a00dff5e02add41819138abb3284d"
-      },
-      {
-        "ok": true,
-        "id": "LambStew",
-        "rev": "3-f9c62b2169d0999103e9f41949090807"
-      }
-    ]
+        HTTP/1.1 201 Created
+        Cache-Control: must-revalidate
+        Content-Length: 144
+        Content-Type: application/json
+        Date: Mon, 12 Aug 2013 00:15:05 GMT
+        Server: CouchDB (Erlang/OTP)
 
+        [
+            {
+                "ok": true,
+                "id": "FishStew",
+                "rev":" 1-967a00dff5e02add41819138abb3284d"
+            },
+            {
+                "ok": true,
+                "id": "LambStew",
+                "rev": "3-f9c62b2169d0999103e9f41949090807"
+            }
+        ]
 
 Inserting Documents in Bulk
----------------------------
+===========================
 
 Each time a document is stored or updated in CouchDB, the internal B-tree
 is updated. Bulk insertion provides efficiency gains in both storage space,
@@ -303,35 +301,34 @@ supplied document IDs, and one which will have a document ID generated:
 
 .. code-block:: http
 
-  POST /source/_bulk_docs HTTP/1.1
-  Accept: application/json
-  Content-Length: 323
-  Content-Type: application/json
-  Host: localhost:5984
-
-  {
-      "docs": [
-          {
-              "_id": "FishStew",
-              "servings": 4,
-              "subtitle": "Delicious with freshly baked bread",
-              "title": "FishStew"
-          },
-          {
-              "_id": "LambStew",
-              "servings": 6,
-              "subtitle": "Serve with a whole meal scone topping",
-              "title": "LambStew"
-          },
-          {
-              "_id": "BeefStew",
-              "servings": 8,
-              "subtitle": "Hand-made dumplings make a great accompaniment",
-              "title": "BeefStew"
-          }
-      ]
-  }
+    POST /source/_bulk_docs HTTP/1.1
+    Accept: application/json
+    Content-Length: 323
+    Content-Type: application/json
+    Host: localhost:5984
 
+    {
+        "docs": [
+            {
+                "_id": "FishStew",
+                "servings": 4,
+                "subtitle": "Delicious with freshly baked bread",
+                "title": "FishStew"
+            },
+            {
+                "_id": "LambStew",
+                "servings": 6,
+                "subtitle": "Serve with a whole meal scone topping",
+                "title": "LambStew"
+            },
+            {
+                "_id": "BeefStew",
+                "servings": 8,
+                "subtitle": "Hand-made dumplings make a great accompaniment",
+                "title": "BeefStew"
+            }
+        ]
+    }
 
 The return type from a bulk insertion will be :statuscode:`201`,
 with the content of the returned structure indicating specific success
@@ -342,39 +339,38 @@ documents created, here with the combination and their revision IDs:
 
 .. code-block:: http
 
-  HTTP/1.1 201 Created
-  Cache-Control: must-revalidate
-  Content-Length: 215
-  Content-Type: application/json
-  Date: Sat, 26 Oct 2013 00:10:39 GMT
-  Server: CouchDB (Erlang OTP)
-
-  [
-      {
-          "id": "FishStew",
-          "ok": true,
-          "rev": "1-6a466d5dfda05e613ba97bd737829d67"
-      },
-      {
-          "id": "LambStew",
-          "ok": true,
-          "rev": "1-648f1b989d52b8e43f05aa877092cc7c"
-      },
-      {
-          "id": "BeefStew",
-          "ok": true,
-          "rev": "1-e4602845fc4c99674f50b1d5a804fdfa"
-      }
-  ]
+    HTTP/1.1 201 Created
+    Cache-Control: must-revalidate
+    Content-Length: 215
+    Content-Type: application/json
+    Date: Sat, 26 Oct 2013 00:10:39 GMT
+    Server: CouchDB (Erlang OTP)
 
+    [
+        {
+            "id": "FishStew",
+            "ok": true,
+            "rev": "1-6a466d5dfda05e613ba97bd737829d67"
+        },
+        {
+            "id": "LambStew",
+            "ok": true,
+            "rev": "1-648f1b989d52b8e43f05aa877092cc7c"
+        },
+        {
+            "id": "BeefStew",
+            "ok": true,
+            "rev": "1-e4602845fc4c99674f50b1d5a804fdfa"
+        }
+    ]
 
 The content and structure of the returned JSON will depend on the transaction
 semantics being used for the bulk update; see :ref:`api/db/bulk_docs/semantics`
-for more information. Conflicts and validation errors when updating documents in
-bulk must be handled separately; see :ref:`api/db/bulk_docs/validation`.
+for more information. Conflicts and validation errors when updating documents
+in bulk must be handled separately; see :ref:`api/db/bulk_docs/validation`.
 
 Updating Documents in Bulk
---------------------------
+==========================
 
 The bulk document update procedure is similar to the insertion
 procedure, except that you must specify the document ID and current
@@ -384,68 +380,67 @@ For example, you could send the following request:
 
 .. code-block:: http
 
-  POST /recipes/_bulk_docs HTTP/1.1
-  Accept: application/json
-  Content-Length: 464
-  Content-Type: application/json
-  Host: localhost:5984
-
-  {
-      "docs": [
-          {
-              "_id": "FishStew",
-              "_rev": "1-6a466d5dfda05e613ba97bd737829d67",
-              "servings": 4,
-              "subtitle": "Delicious with freshly baked bread",
-              "title": "FishStew"
-          },
-          {
-              "_id": "LambStew",
-              "_rev": "1-648f1b989d52b8e43f05aa877092cc7c",
-              "servings": 6,
-              "subtitle": "Serve with a whole meal scone topping",
-              "title": "LambStew"
-          },
-          {
-              "_id": "BeefStew",
-              "_rev": "1-e4602845fc4c99674f50b1d5a804fdfa",
-              "servings": 8,
-              "subtitle": "Hand-made dumplings make a great accompaniment",
-              "title": "BeefStew"
-          }
-      ]
-  }
+    POST /recipes/_bulk_docs HTTP/1.1
+    Accept: application/json
+    Content-Length: 464
+    Content-Type: application/json
+    Host: localhost:5984
+
+    {
+        "docs": [
+            {
+                "_id": "FishStew",
+                "_rev": "1-6a466d5dfda05e613ba97bd737829d67",
+                "servings": 4,
+                "subtitle": "Delicious with freshly baked bread",
+                "title": "FishStew"
+            },
+            {
+                "_id": "LambStew",
+                "_rev": "1-648f1b989d52b8e43f05aa877092cc7c",
+                "servings": 6,
+                "subtitle": "Serve with a whole meal scone topping",
+                "title": "LambStew"
+            },
+            {
+                "_id": "BeefStew",
+                "_rev": "1-e4602845fc4c99674f50b1d5a804fdfa",
+                "servings": 8,
+                "subtitle": "Hand-made dumplings make a great accompaniment",
+                "title": "BeefStew"
+            }
+        ]
+    }
 
 The return structure is the JSON of the updated documents, with the new
 revision and ID information:
 
 .. code-block:: http
 
-  HTTP/1.1 201 Created
-  Cache-Control: must-revalidate
-  Content-Length: 215
-  Content-Type: application/json
-  Date: Sat, 26 Oct 2013 00:10:39 GMT
-  Server: CouchDB (Erlang OTP)
-
-  [
-      {
-          "id": "FishStew",
-          "ok": true,
-          "rev": "2-2bff94179917f1dec7cd7f0209066fb8"
-      },
-      {
-          "id": "LambStew",
-          "ok": true,
-          "rev": "2-6a7aae7ac481aa98a2042718d09843c4"
-      },
-      {
-          "id": "BeefStew",
-          "ok": true,
-          "rev": "2-9801936a42f06a16f16c30027980d96f"
-      }
-  ]
+    HTTP/1.1 201 Created
+    Cache-Control: must-revalidate
+    Content-Length: 215
+    Content-Type: application/json
+    Date: Sat, 26 Oct 2013 00:10:39 GMT
+    Server: CouchDB (Erlang OTP)
 
+    [
+        {
+            "id": "FishStew",
+            "ok": true,
+            "rev": "2-2bff94179917f1dec7cd7f0209066fb8"
+        },
+        {
+            "id": "LambStew",
+            "ok": true,
+            "rev": "2-6a7aae7ac481aa98a2042718d09843c4"
+        },
+        {
+            "id": "BeefStew",
+            "ok": true,
+            "rev": "2-9801936a42f06a16f16c30027980d96f"
+        }
+    ]
 
 You can optionally delete documents during a bulk update by adding the
 ``_deleted`` field with a value of ``true`` to each document ID/revision
@@ -457,13 +452,13 @@ messages on a per-document basis.
 
 The content and structure of the returned JSON will depend on the transaction
 semantics being used for the bulk update; see :ref:`api/db/bulk_docs/semantics`
-for more information. Conflicts and validation errors when updating documents in
-bulk must be handled separately; see :ref:`api/db/bulk_docs/validation`.
+for more information. Conflicts and validation errors when updating documents
+in bulk must be handled separately; see :ref:`api/db/bulk_docs/validation`.
 
 .. _api/db/bulk_docs/semantics:
 
 Bulk Documents Transaction Semantics
-------------------------------------
+====================================
 
 CouchDB supports two different modes for updating (or inserting)
 documents using the bulk documentation system. Each mode affects both
@@ -487,24 +482,23 @@ of conflict checking performed on each document. The two modes are:
    .. code-block:: javascript
 
        [
-          {
-             "id" : "FishStew",
-             "error" : "conflict",
-             "reason" : "Document update conflict."
-          },
-          {
-             "id" : "LambStew",
-             "error" : "conflict",
-             "reason" : "Document update conflict."
-          },
-          {
-             "id" : "BeefStew",
-             "error" : "conflict",
-             "reason" : "Document update conflict."
-          }
+           {
+               "id" : "FishStew",
+               "error" : "conflict",
+               "reason" : "Document update conflict."
+           },
+           {
+               "id" : "LambStew",
+               "error" : "conflict",
+               "reason" : "Document update conflict."
+           },
+           {
+               "id" : "BeefStew",
+               "error" : "conflict",
+               "reason" : "Document update conflict."
+           }
        ]
 
-
    In this case no new revision has been created and you will need to
    submit the document update, with the correct revision tag, to update
    the document.
@@ -523,30 +517,30 @@ of conflict checking performed on each document. The two modes are:
 
    .. code-block:: http
 
-      HTTP/1.1 201 Created
-      Cache-Control: must-revalidate
-      Content-Length: 215
-      Content-Type: application/json
-      Date: Sat, 26 Oct 2013 00:13:33 GMT
-      Server: CouchDB (Erlang OTP)
-
-      [
-          {
-              "id": "FishStew",
-              "ok": true,
-              "rev": "1-6a466d5dfda05e613ba97bd737829d67"
-          },
-          {
-              "id": "LambStew",
-              "ok": true,
-              "rev": "1-648f1b989d52b8e43f05aa877092cc7c"
-          },
-          {
-              "id": "BeefStew",
-              "ok": true,
-              "rev": "1-e4602845fc4c99674f50b1d5a804fdfa"
-          }
-      ]
+       HTTP/1.1 201 Created
+       Cache-Control: must-revalidate
+       Content-Length: 215
+       Content-Type: application/json
+       Date: Sat, 26 Oct 2013 00:13:33 GMT
+       Server: CouchDB (Erlang OTP)
+
+       [
+           {
+               "id": "FishStew",
+               "ok": true,
+               "rev": "1-6a466d5dfda05e613ba97bd737829d67"
+           },
+           {
+               "id": "LambStew",
+               "ok": true,
+               "rev": "1-648f1b989d52b8e43f05aa877092cc7c"
+           },
+           {
+               "id": "BeefStew",
+               "ok": true,
+               "rev": "1-e4602845fc4c99674f50b1d5a804fdfa"
+           }
+       ]
 
    When updating documents using this mode the revision of a document
    included in views will be arbitrary. You can check the conflict
@@ -590,7 +584,7 @@ other databases correctly.
 .. _api/db/bulk_docs/validation:
 
 Bulk Document Validation and Conflict Errors
---------------------------------------------
+============================================
 
 The JSON returned by the ``_bulk_docs`` operation consists of an array
 of JSON structures, one for each document in the original submission.
@@ -625,7 +619,7 @@ following type:
 
    .. code-block:: javascript
 
-        throw({forbidden: 'invalid recipe ingredient'});
+       throw({forbidden: 'invalid recipe ingredient'});
 
    The error response returned will be:
 


Mime
View raw message