couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d..@apache.org
Subject [14/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/docs/couchdb-manual-1.1/couchdb-manual-ready.xml
----------------------------------------------------------------------
diff --git a/share/docs/couchdb-manual-1.1/couchdb-manual-ready.xml b/share/docs/couchdb-manual-1.1/couchdb-manual-ready.xml
deleted file mode 100644
index 8667927..0000000
--- a/share/docs/couchdb-manual-1.1/couchdb-manual-ready.xml
+++ /dev/null
@@ -1,9409 +0,0 @@
-<?xml version="1.0" encoding="utf-8" standalone="no"?>
-<book id="couchdb-1-1">
-
-  <title>CouchDB 1.1 Manual</title>
-
-  <bookinfo>
-
-    <abstract>
-
-      <para>
-        This manual documents the CouchDB
-        1.1 database system, including the installation,
-        functionality, and CouchDB API.
-      </para>
-
-      <para xml:base="../common/docbuilddate.xml">
-  <emphasis>Last document update</emphasis>: 21 Feb 2012 20:09;
-  <emphasis>Document built</emphasis>: 21 Feb 2012 20:9.
-</para>
-
-    </abstract>
-
-  </bookinfo>
-
-  <chapter id="couchdb-single-introduction">
-
-  <title>Introduction</title>
-
-  <para>
-    There are two interfaces to CouchDB, the built-in
-    Futon web-based interface and the CouchDB API accessed through the
-    HTTP REST interface. The former is the simplest way to view and
-    monitor your CouchDB installation and perform a
-    number of basic database and system operations. More information on
-    using the Futon interface can be found in
-    <xref linkend="couchdb-single-introduction-futon"/>.
-  </para>
-
-  <para>
-    The primary way to interact with the CouchDB API is to use a client
-    library or other interface that provides access to the underlying
-    functionality through your chosen language or platform. However,
-    since the API is supported through HTTP REST, you can interact with
-    your CouchDB with any solution that supports the
-    HTTP protocol.
-  </para>
-
-  <para>
-    There are a number of different tools that talk the HTTP protocol
-    and allow you to set and configure the necessary information. One
-    tool for this that allows for access from the command-line is
-    <command moreinfo="none">curl</command>. See
-    <xref linkend="couchdb-single-introduction-curl"/>.
-  </para>
-
-  <section id="couchdb-single-introduction-futon">
-
-    <title>Using Futon</title>
-
-    <para>
-      Futon is a native web-based interface built into CouchDB. It provides a basic interface to the majority of the
-      functionality, including the ability to create, update, delete and
-      view documents and views, provides access to the configuration
-      parameters, and an interface for initiating replication.
-    </para>
-
-    <para>
-      The default view is the <guilabel moreinfo="none">Overview</guilabel> page which
-      provides you with a list of the databases. The basic structure of
-      the page is consistent regardless of the section you are in. The
-      main panel on the left provides the main interface to the
-      databases, configuration or replication systems. The side panel on
-      the right provides navigation to the main areas of Futon
-      interface:
-    </para>
-
-    <figure id="fig-ccouchdb-single-introduction-futon-overview" float="0">
-
-      <title>Futon Overview</title>
-
-      <mediaobject>
-
-        <imageobject>
-
-          <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-overview.png" format="PNG" lang="en"/>
-
-        </imageobject>
-
-        <textobject>
-
-          <phrase lang="en">Futon Overview</phrase>
-
-        </textobject>
-
-      </mediaobject>
-
-    </figure>
-
-    <para>
-      The main sections are:
-    </para>
-
-    <itemizedlist>
-
-      <listitem>
-        <para>
-          <guibutton moreinfo="none">Overview</guibutton>
-        </para>
-
-        <para>
-          The main overview page, which provides a list of the databases
-          and provides the interface for querying the database and
-          creating and updating documents. See
-          <xref linkend="couchdb-single-introduction-futon-dbdocs"/>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <guibutton moreinfo="none">Configuration</guibutton>
-        </para>
-
-        <para>
-          An interface into the configuration of your CouchDB installation. The interface allows you to edit the
-          different configurable parameters. For more details on
-          configuration, see
-          <xref linkend="couchdb-single-configuration"/>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <guibutton moreinfo="none">Replicator</guibutton>
-        </para>
-
-        <para>
-          An interface to the replication system, enabling you to
-          initiate replication between local and remote databases. See
-          <xref linkend="couchdb-single-introduction-futon-replication"/>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <guibutton moreinfo="none">Status</guibutton>
-        </para>
-
-        <para>
-          Displays a list of the running background tasks on the server.
-          Background tasks include view index building, compaction and
-          replication. The <guibutton moreinfo="none">Status</guibutton> page is an
-          interface to the
-          <link linkend="couchdb-api-misc_active-tasks_get">Active
-          Tasks</link> API call. See
-          <xref linkend="couchdb-api-misc_active-tasks_get"/>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <guibutton moreinfo="none">Verify Installation</guibutton>
-        </para>
-
-        <para>
-          The <guibutton moreinfo="none">Verify Installation</guibutton> allows you to
-          check whether all of the components of your CouchDB installation are correctly installed.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <guibutton moreinfo="none">Test Suite</guibutton>
-        </para>
-
-        <para>
-          The <guibutton moreinfo="none">Test Suite</guibutton> section allows you to
-          run the built-in test suite. This executes a number of test
-          routines entirely within your browser to test the API and
-          functionality of your CouchDB installation. If
-          you select this page, you can run the tests by using the
-          <guibutton moreinfo="none">Run All</guibutton> button. This will execute all
-          the tests, which may take some time.
-        </para>
-      </listitem>
-
-    </itemizedlist>
-
-    <section id="couchdb-single-introduction-futon-dbdocs">
-
-      <title>Managing Databases and Documents</title>
-
-      <para>
-        You can manage databases and documents within Futon using the
-        main <guibutton moreinfo="none">Overview</guibutton> section of the Futon
-        interface.
-      </para>
-
-      <para>
-        To create a new database, click the <guibutton moreinfo="none">Create Database
-        …</guibutton> button. You will be prompted for the
-        database name, as shown in the figure below.
-      </para>
-
-      <figure id="fig-ccouchdb-single-introduction-futon-dbdocs-createdb" float="0">
-
-        <title>Creating a Database</title>
-
-        <mediaobject>
-
-          <imageobject>
-
-            <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-createdb.png" format="PNG" lang="en"/>
-
-          </imageobject>
-
-          <textobject>
-
-            <phrase lang="en">Creating a Database</phrase>
-
-          </textobject>
-
-        </mediaobject>
-
-      </figure>
-
-      <para>
-        Once you have created the database (or selected an existing
-        one), you will be shown a list of the current documents. If you
-        create a new document, or select an existing document, you will
-        be presented with the edit document display.
-      </para>
-
-      <para>
-        Editing documents within Futon requires selecting the document
-        and then editing (and setting) the fields for the document
-        individually before saving the document back into the database.
-      </para>
-
-      <para>
-        For example, the figure below shows the editor for a single
-        document, a newly created document with a single ID, the
-        document <literal moreinfo="none">_id</literal> field.
-      </para>
-
-      <figure id="fig-ccouchdb-single-introduction-futon-dbdocs-editdoc" float="0">
-
-        <title>Editing a Document</title>
-
-        <mediaobject>
-
-          <imageobject>
-
-            <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-editdoc.png" format="PNG" lang="en"/>
-
-          </imageobject>
-
-          <textobject>
-
-            <phrase lang="en">Editing a Document</phrase>
-
-          </textobject>
-
-        </mediaobject>
-
-      </figure>
-
-      <para>
-        To add a field to the document:
-      </para>
-
-      <orderedlist inheritnum="ignore" continuation="restarts">
-
-        <listitem>
-          <para>
-            Click <guibutton moreinfo="none">Add Field</guibutton>.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            In the fieldname box, enter the name of the field you want
-            to create. For example, <quote>company</quote>.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Click the green tick next to the field name to confirm the
-            field name change.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Double-click the corresponding <guilabel moreinfo="none">Value</guilabel>
-            cell.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Enter a company name, for example <quote>Example</quote>.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Click the green tick next to the field value to confirm the
-            field value.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            The document is still not saved as this point. You must
-            explicitly save the document by clicking the <guibutton moreinfo="none">Save
-            Document</guibutton> button at the top of the page. This
-            will save the document, and then display the new document
-            with the saved revision information (the
-            <literal moreinfo="none">_rev</literal> field).
-          </para>
-
-          <figure id="fig-ccouchdb-single-introduction-futon-dbdocs-finaldoc" float="0">
-
-            <title>Edited Document</title>
-
-            <mediaobject>
-
-              <imageobject>
-
-                <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-editeddoc.png" format="PNG" lang="en"/>
-
-              </imageobject>
-
-              <textobject>
-
-                <phrase lang="en">Edited Document</phrase>
-
-              </textobject>
-
-            </mediaobject>
-
-          </figure>
-        </listitem>
-
-      </orderedlist>
-
-      <para>
-        The same basic interface is used for all editng operations
-        within Futon. You <emphasis>must</emphasis> rememmbr to save the
-        individual element (fieldname, value) using the green tick
-        button, before then saving the document.
-      </para>
-
-    </section>
-
-    <section id="couchdb-single-introduction-futon-replication">
-
-      <title>Configuring Replication</title>
-
-      <para>
-        When you click the <guibutton moreinfo="none">Replicator</guibutton> option
-        within the <guilabel moreinfo="none">Tools</guilabel> menu you are presented
-        with the Replicator screen. This allows you to start replication
-        between two databases by filling in or select the appropriate
-        options within the form provided.
-      </para>
-
-      <figure id="fig-ccouchdb-single-introduction-futon-replication-form" float="0">
-
-        <title>Replication Form</title>
-
-        <mediaobject>
-
-          <imageobject>
-
-            <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-replform.png" format="PNG" lang="en"/>
-
-          </imageobject>
-
-          <textobject>
-
-            <phrase lang="en">Replication Form</phrase>
-
-          </textobject>
-
-        </mediaobject>
-
-      </figure>
-
-      <para>
-        To start a replication process, either the select the local
-        database or enter a remote database name into the corresponding
-        areas of the form. Replication occurs from the database on the
-        left to the database on the right.
-      </para>
-
-      <para>
-        If you are specifying a remote database name, you must specify
-        the full URL of the remote database (including the host, port
-        number and database name). If the remote instance requires
-        authentication, you can specify the username and password as
-        part of the URL, for example
-        <literal moreinfo="none">http://username:pass@remotehost:5984/demo</literal>.
-      </para>
-
-      <para>
-        To enable continuous replication, click the
-        <guilabel moreinfo="none">Continuous</guilabel> checkbox.
-      </para>
-
-      <para>
-        To start the replication process, click the
-        <guibutton moreinfo="none">Replicate</guibutton> button. The replication process
-        should start and will continue in the background. If the
-        replication process will take a long time, you can monitor the
-        status of the replication using the
-        <guibutton moreinfo="none">Status</guibutton> option under the
-        <guilabel moreinfo="none">Tools</guilabel> menu.
-      </para>
-
-      <para>
-        Once replication has been completed, the page will show the
-        information returned when the replication process completes by
-        the API.
-      </para>
-
-      <para>
-        The <guilabel moreinfo="none">Replicator</guilabel> tool is an interface to the
-        underlying replication API. For more information, see
-        <xref linkend="couchdb-api-misc_replicate_post"/>.
-        For more information on replication, see
-        <xref linkend="couchdb-single-replication"/>.
-      </para>
-
-    </section>
-
-  </section>
-
-  <section id="couchdb-single-introduction-curl">
-
-    <title>Using <command moreinfo="none">curl</command></title>
-
-    <para>
-      The <command moreinfo="none">curl</command> utility is a command line tool
-      available on Unix, Linux, Mac OS X and Windows and many other
-      platforms. <command moreinfo="none">curl</command> provides easy access to the
-      HTTP protocol (among others) directly from the command-line and is
-      therefore an ideal way of interacting with CouchDB
-      over the HTTP REST API.
-    </para>
-
-    <para>
-      For simple <literal moreinfo="none">GET</literal> requests you can supply the URL
-      of the request. For example, to get the database information:
-    </para>
-
-<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl http://127.0.0.1:5984</userinput></programlisting>
-
-    <para>
-      This returns the database information (formatted in the output
-      below for clarity):
-    </para>
-
-<programlisting format="linespecific">{
-   "modules" : {
-      "geocouch" : "7fd793c10f3aa667a1088a937398bc5b51472b7f"
-   },
-   "couchdb" : "Welcome",
-   "version" : "1.1.0",
-}</programlisting>
-
-    <note>
-      <para>
-        For some URLs, especially those that include special characters
-        such as ampersand, exclamation mark, or question mark, you
-        should quote the URL you are specifying on the command line. For
-        example:
-      </para>
-
-<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl 'http://couchdb:5984/_uuids?count=5'</userinput></programlisting>
-    </note>
-
-    <para>
-      You can explicitly set the HTTP command using the
-      <option>-X</option> command line option. For example, when
-      creating a database, you set the name of the database in the URL
-      you send using a PUT request:
-    </para>
-
-<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl -X PUT http://127.0.0.1:5984/demo</userinput>
-{"ok":true}</programlisting>
-
-    <para>
-      But to obtain the database information you use a
-      <literal moreinfo="none">GET</literal> request (with the return information
-      formatted for clarity):
-    </para>
-
-<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl -X GET http://127.0.0.1:5984/demo</userinput>
-{
-   "compact_running" : false,
-   "doc_count" : 0,
-   "db_name" : "demo",
-   "purge_seq" : 0,
-   "committed_update_seq" : 0,
-   "doc_del_count" : 0,
-   "disk_format_version" : 5,
-   "update_seq" : 0,
-   "instance_start_time" : "1306421773496000",
-   "disk_size" : 79
-}</programlisting>
-
-    <para>
-      For certain operations, you must specify the content type of
-      request, which you do by specifying the
-      <literal moreinfo="none">Content-Type</literal> header using the
-      <option>-H</option> command-line option:
-    </para>
-
-<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl -H 'Content-type: application/json' http://127.0.0.1:5984/_uuids</userinput></programlisting>
-
-    <para>
-      You can also submit 'payload' data, that is, data in the body of
-      the HTTP request using the <option>-d</option> option. This is
-      useful if you need to submit JSON structures, for example document
-      data, as part of the request. For example, to submit a simple
-      document to the <literal moreinfo="none">demo</literal> database:
-    </para>
-
-<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl -H 'Content-type: application/json' \
-     -X POST http://127.0.0.1:5984/demo \
-     -d '{"company": "Example, Inc."}'</userinput>
-{"ok":true,"id":"8843faaf0b831d364278331bc3001bd8",
- "rev":"1-33b9fbce46930280dab37d672bbc8bb9"}</programlisting>
-
-    <para>
-      In the above example, the argument after the <option>-d</option>
-      option is the JSON of the document we want to submit.
-    </para>
-
-    <para>
-      The document can be accessed by using the automatically generated
-      document ID that was returned:
-    </para>
-
-<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl -X GET http://127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8</userinput>
-{"_id":"8843faaf0b831d364278331bc3001bd8",
- "_rev":"1-33b9fbce46930280dab37d672bbc8bb9",
- "company":"Example, Inc."}</programlisting>
-
-    <para>
-      The API samples in the <xref linkend="couchdb-api-basics"/> show
-      the HTTP command, URL and any payload information that needs to be
-      submitted (and the expected return value). All of these examples
-      can be reproduced using <command moreinfo="none">curl</command> with the
-      command-line examples shown above.
-    </para>
-
-  </section>
-
-</chapter>
-
-  <chapter id="couchdb-single-features">
-
-  <title>Features and Functionality</title>
-
-  <para>
-     
-  </para>
-
-  <section id="couchdb-single-features-httprange">
-
-    <title>HTTP Range Requests</title>
-
-    <para>
-      HTTP allows you to specify byte ranges for requests. This allows
-      the implementation of resumable downloads and skippable audio and
-      video streams alike. The following example uses a text file to
-      make the range request process easier.
-    </para>
-
-<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">cat file.txt</userinput>
-My hovercraft is full of eels!</programlisting>
-
-    <para>
-      Uploading this as an attachment to a <literal moreinfo="none">text</literal>
-      database using <command moreinfo="none">curl</command>:
-    </para>
-
-<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl -X PUT http://127.0.0.1:5984/test/doc/file.txt \
-    -H "Content-Type: application/octet-stream" -d@file.txt</userinput>
-{"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"}</programlisting>
-
-    <para>
-      Requesting the whole file works as normal:
-    </para>
-
-<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl -X GET http://127.0.0.1:5984/test/doc/file.txt</userinput>
-My hovercraft is full of eels!</programlisting>
-
-    <para>
-      But to retrieve only the first 13 bytes using
-      <command moreinfo="none">curl</command>:
-    </para>
-
-<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl -X GET http://127.0.0.1:5984/test/doc/file.txt -H "Range: bytes=0-12"</userinput>
-My hovercraft</programlisting>
-
-    <para>
-      HTTP supports many ways to specify single and even multiple byte
-      rangers. See
-      <ulink url="http://tools.ietf.org/html/rfc2616#section-14.27">RFC
-      2616</ulink>.
-    </para>
-
-    <note>
-      <para>
-        Databases that have been created with CouchDB 1.0.2 or earlier
-        will support range requests in 1.1.0, but they are using a
-        less-optimal algorithm. If you plan to make heavy use of this
-        feature, make sure to compact your database with CouchDB 1.1.0
-        to take advantage of a better algorithm to find byte ranges.
-      </para>
-    </note>
-
-  </section>
-
-  <section id="couchdb-single-features-proxying">
-
-    <title>HTTP Proxying</title>
-
-    <para>
-      The HTTP proxy feature makes it easy to map and redirect different
-      content through your CouchDB URL. The proxy works by mapping a
-      pathname and passing all content after that prefix through to the
-      configured proxy address.
-    </para>
-
-    <para>
-      Configuration of the proxy redirect is handled through the
-      <literal moreinfo="none">[httpd_global_handlers]</literal> section of the CouchDB
-      configuration file (typically <filename moreinfo="none">local.ini</filename>). The
-      format is:
-    </para>
-
-<programlisting format="linespecific">[httpd_global_handlers]
-PREFIX = {couch_httpd_proxy, handle_proxy_req, &lt;&lt;"DESTINATION"&gt;&gt;}</programlisting>
-
-    <para>
-      Where:
-    </para>
-
-    <itemizedlist>
-
-      <listitem>
-        <para>
-          <literal moreinfo="none">PREFIX</literal>
-        </para>
-
-        <para>
-          Is the string that will be matched. The string can be any
-          valid qualifier, although to ensure that existing database
-          names are not overridden by a proxy configuration, you can use
-          an underscore prefix.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <literal moreinfo="none">DESTINATION</literal>
-        </para>
-
-        <para>
-          The fully-qualified URL to which the request should be sent.
-          The destination must include the <literal moreinfo="none">http</literal>
-          prefix. The content is used verbatim in the original request,
-          so you can also forward to servers on different ports and to
-          specific paths on the target host.
-        </para>
-      </listitem>
-
-    </itemizedlist>
-
-    <para>
-      The proxy process then translates requests of the form:
-    </para>
-
-<programlisting format="linespecific">http://couchdb:5984/PREFIX/path</programlisting>
-
-    <para>
-      To:
-    </para>
-
-<programlisting format="linespecific">DESTINATION/path</programlisting>
-
-    <note>
-      <para>
-        Everything after <literal moreinfo="none">PREFIX</literal> including the
-        required forward slash will be appended to the
-        <literal moreinfo="none">DESTINATION</literal>.
-      </para>
-    </note>
-
-    <para>
-      The response is then communicated back to the original client.
-    </para>
-
-    <para>
-      For example, the following configuration:
-    </para>
-
-<programlisting format="linespecific">_google = {couch_httpd_proxy, handle_proxy_req, &lt;&lt;"http://www.google.com"&gt;&gt;}</programlisting>
-
-    <para>
-      Would forward all requests for
-      <literal moreinfo="none">http://couchdb:5984/_google</literal> to the Google
-      website.
-    </para>
-
-    <para>
-      The service can also be used to forward to related CouchDB
-      services, such as Lucene:
-    </para>
-
-<programlisting format="linespecific">[httpd_global_handlers]
-_fti = {couch_httpd_proxy, handle_proxy_req, &lt;&lt;"http://127.0.0.1:5985"&gt;&gt;}</programlisting>
-
-    <note>
-      <para>
-        The proxy service is basic. If the request is not identified by
-        the <literal moreinfo="none">DESTINATION</literal>, or the remainder of the
-        <literal moreinfo="none">PATH</literal> specification is incomplete, the
-        original request URL is interpreted as if the
-        <literal moreinfo="none">PREFIX</literal> component of that URL does not exist.
-      </para>
-
-      <para>
-        For example, requesting
-        <literal moreinfo="none">http://couchdb:5984/_intranet/media</literal> when
-        <filename moreinfo="none">/media</filename> on the proxy destination does not
-        exist, will cause the request URL to be interpreted as
-        <literal moreinfo="none">http://couchdb:5984/media</literal>. Care should be
-        taken to ensure that both requested URLs and destination URLs
-        are able to cope
-      </para>
-    </note>
-
-  </section>
-
-  <section id="couchdb-single-features-commonjs">
-
-    <title>CommonJS support for map functions</title>
-
-    <para>
-      CommonJS support allows you to use CommonJS notation inside
-      <methodname>map</methodname> and <methodname>reduce</methodname>
-      functions, but only of libraries that are stored inside the views
-      part of the design doc.
-    </para>
-
-    <para>
-      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
-      <filename moreinfo="none">design_doc.views.lib</filename>.
-    </para>
-
-    <para>
-      There's no worry here about namespace collisions, as Couch just
-      plucks <literal moreinfo="none">views.*.map</literal> and
-      <literal moreinfo="none">views.*.reduce</literal> out of the design doc. So you
-      could have a view called <literal moreinfo="none">lib</literal> if you wanted, and
-      still have CommonJS stored in <literal moreinfo="none">views.lib.sha1</literal>
-      and <literal moreinfo="none">views.lib.stemmer</literal> if you wanted.
-    </para>
-
-    <para>
-      The implementation is simplified by enforcing that CommonJS
-      modules to be used in <methodname>map</methodname> functions be
-      stored in views.lib.
-    </para>
-
-    <para>
-      A sample design doc (taken from the test suite in Futon) is below:
-    </para>
-
-<programlisting format="linespecific">{
-   "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"
-}</programlisting>
-
-    <para>
-      The <literal moreinfo="none">require()</literal> statement is relative to the
-      design document, but anything loaded form outside of
-      <literal moreinfo="none">views/lib</literal> will fail.
-    </para>
-
-  </section>
-
-  <section id="couchdb-single-features-etag">
-
-    <title>Granular ETag support</title>
-
-    <para>
-      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
-      URL's in a single design doc, even if that specific view's results
-      had not changed.
-    </para>
-
-    <para>
-      In CouchDB 1.1 each <literal moreinfo="none">_view</literal> URL has it's 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).
-    </para>
-
-  </section>
-
-</chapter>
-
-  <chapter id="couchdb-single-replication">
-
-  <title>Replication</title>
-
-  <para>
-     
-  </para>
-
-  <section id="couchdb-single-replication-replicatordb">
-
-    <title>Replicator Database</title>
-
-    <para>
-      A database where you
-      <literal moreinfo="none">PUT</literal>/<literal moreinfo="none">POST</literal> documents to
-      trigger replications and you <literal moreinfo="none">DELETE</literal> to cancel
-      ongoing replications. These documents have exactly the same
-      content as the JSON objects we used to <literal moreinfo="none">POST</literal> to
-      <literal moreinfo="none">_replicate</literal> (fields <literal moreinfo="none">source</literal>,
-      <literal moreinfo="none">target</literal>, <literal moreinfo="none">create_target</literal>,
-      <literal moreinfo="none">continuous</literal>, <literal moreinfo="none">doc_ids</literal>,
-      <literal moreinfo="none">filter</literal>, <literal moreinfo="none">query_params</literal>.
-    </para>
-
-    <para>
-      Replication documents can have a user defined
-      <literal moreinfo="none">_id</literal>. Design documents (and
-      <literal moreinfo="none">_local</literal> documents) added to the replicator
-      database are ignored.
-    </para>
-
-    <para>
-      The default name of this database is
-      <literal moreinfo="none">_replicator</literal>. The name can be changed in the
-      <filename moreinfo="none">local.ini</filename> configuration, section
-      <literal moreinfo="none">[replicator]</literal>, parameter <literal moreinfo="none">db</literal>.
-    </para>
-
-    <section id="couchdb-single-replication-replicatordb-basics">
-
-      <title>Basics</title>
-
-      <para>
-        Let's say you PUT the following document into _replicator:
-      </para>
-
-<programlisting format="linespecific">{
-    "_id": "my_rep",
-    "source":  "http://myserver.com:5984/foo",
-    "target":  "bar",
-    "create_target":  true
-}</programlisting>
-
-      <para>
-        In the couch log you'll see 2 entries like these:
-      </para>
-
-<programlisting format="linespecific">[Thu, 17 Feb 2011 19:43:59 GMT] [info] [&lt;0.291.0&gt;] Document `my_rep` triggered replication `c0ebe9256695ff083347cbf95f93e280+create_target`
-[Thu, 17 Feb 2011 19:44:37 GMT] [info] [&lt;0.124.0&gt;] Replication `c0ebe9256695ff083347cbf95f93e280+create_target` finished (triggered by document `my_rep`)</programlisting>
-
-      <para>
-        As soon as the replication is triggered, the document will be
-        updated by CouchDB with 3 new fields:
-      </para>
-
-<programlisting format="linespecific">{
-    "_id": "my_rep",
-    "source":  "http://myserver.com:5984/foo",
-    "target":  "bar",
-    "create_target":  true,
-    "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
-    "_replication_state":  "triggered",
-    "_replication_state_time":  1297974122
-}</programlisting>
-
-      <para>
-        Special fields set by the replicator start with the prefix
-        <literal moreinfo="none">_replication_</literal>.
-      </para>
-
-      <itemizedlist>
-
-        <listitem>
-          <para>
-            <literal moreinfo="none">_replication_id</literal>
-          </para>
-
-          <para>
-            The ID internally assigned to the replication. This is also
-            the ID exposed by <literal moreinfo="none">/_active_tasks</literal>.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            <literal moreinfo="none">_replication_state</literal>
-          </para>
-
-          <para>
-            The current state of the replication.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            <literal moreinfo="none">_replication_state_time</literal>
-          </para>
-
-          <para>
-            A Unix timestamp (number of seconds since 1 Jan 1970) that
-            tells us when the current replication state (marked in
-            <literal moreinfo="none">_replication_state</literal>) was set.
-          </para>
-        </listitem>
-
-      </itemizedlist>
-
-      <para>
-        When the replication finishes, it will update the
-        <literal moreinfo="none">_replication_state</literal> field (and
-        <literal moreinfo="none">_replication_state_time</literal>) with the value
-        <literal moreinfo="none">completed</literal>, so the document will look like:
-      </para>
-
-<programlisting format="linespecific">{
-    "_id": "my_rep",
-    "source":  "http://myserver.com:5984/foo",
-    "target":  "bar",
-    "create_target":  true,
-    "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
-    "_replication_state":  "completed",
-    "_replication_state_time":  1297974122
-}</programlisting>
-
-      <para>
-        When an error happens during replication, the
-        <literal moreinfo="none">_replication_state</literal> field is set to
-        <literal moreinfo="none">error</literal> (and
-        <literal moreinfo="none">_replication_state</literal> gets updated of course).
-      </para>
-
-      <para>
-        When you PUT/POST a document to the
-        <literal moreinfo="none">_replicator</literal> database, CouchDB will attempt to
-        start the replication up to 10 times (configurable under
-        <literal moreinfo="none">[replicator]</literal>, parameter
-        <literal moreinfo="none">max_replication_retry_count</literal>). If it fails on
-        the first attempt, it waits 5 seconds before doing a second
-        attempt. If the second attempt fails, it waits 10 seconds before
-        doing a third attempt. If the third attempt fails, it waits 20
-        seconds before doing a fourth attempt (each attempt doubles the
-        previous wait period). When an attempt fails, the Couch log will
-        show you something like:
-      </para>
-
-<programlisting format="linespecific">[error] [&lt;0.149.0&gt;] Error starting replication `67c1bb92010e7abe35d7d629635f18b6+create_target` (document `my_rep_2`): {db_not_found,&lt;&lt;"could not open http://myserver:5986/foo/"&gt;&gt;</programlisting>
-
-      <note>
-        <para>
-          The <literal moreinfo="none">_replication_state</literal> field is only set to
-          <literal moreinfo="none">error</literal> when all the attempts were
-          unsuccessful.
-        </para>
-      </note>
-
-      <para>
-        There are only 3 possible values for the
-        <literal moreinfo="none">_replication_state</literal> field:
-        <literal moreinfo="none">triggered</literal>, <literal moreinfo="none">completed</literal> and
-        <literal moreinfo="none">error</literal>. Continuous replications never get
-        their state set to <literal moreinfo="none">completed</literal>.
-      </para>
-
-    </section>
-
-    <section id="couchdb-single-replication-replicatordb-docsame">
-
-      <title>Documents describing the same replication</title>
-
-      <para>
-        Lets suppose 2 documents are added to the
-        <literal moreinfo="none">_replicator</literal> database in the following order:
-      </para>
-
-<programlisting format="linespecific">{
-    "_id": "doc_A",
-    "source":  "http://myserver.com:5984/foo",
-    "target":  "bar"
-}</programlisting>
-
-      <para>
-        and
-      </para>
-
-<programlisting format="linespecific">{
-    "_id": "doc_B",
-    "source":  "http://myserver.com:5984/foo",
-    "target":  "bar"
-}</programlisting>
-
-      <para>
-        Both describe exactly the same replication (only their
-        <literal moreinfo="none">_ids</literal> differ). In this case document
-        <literal moreinfo="none">doc_A</literal> triggers the replication, getting
-        updated by CouchDB with the fields
-        <literal moreinfo="none">_replication_state</literal>,
-        <literal moreinfo="none">_replication_state_time</literal> and
-        <literal moreinfo="none">_replication_id</literal>, just like it was described
-        before. Document <literal moreinfo="none">doc_B</literal> however, is only
-        updated with one field, the <literal moreinfo="none">_replication_id</literal>
-        so it will look like this:
-      </para>
-
-<programlisting format="linespecific">{
-    "_id": "doc_B",
-    "source":  "http://myserver.com:5984/foo",
-    "target":  "bar",
-    "_replication_id":  "c0ebe9256695ff083347cbf95f93e280"
-}</programlisting>
-
-      <para>
-        While document <literal moreinfo="none">doc_A</literal> will look like this:
-      </para>
-
-<programlisting format="linespecific">{
-    "_id": "doc_A",
-    "source":  "http://myserver.com:5984/foo",
-    "target":  "bar",
-    "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
-    "_replication_state":  "triggered",
-    "_replication_state_time":  1297974122
-}</programlisting>
-
-      <para>
-        Note that both document get exactly the same value for the
-        <literal moreinfo="none">_replication_id</literal> field. This way you can
-        identify which documents refer to the same replication - you can
-        for example define a view which maps replication IDs to document
-        IDs.
-      </para>
-
-    </section>
-
-    <section id="couchdb-single-replication-replicatordb-cancel">
-
-      <title>Canceling replications</title>
-
-      <para>
-        To cancel a replication simply <literal moreinfo="none">DELETE</literal> the
-        document which triggered the replication. The Couch log will
-        show you an entry like the following:
-      </para>
-
-<programlisting format="linespecific">[Thu, 17 Feb 2011 20:16:29 GMT] [info] [&lt;0.125.0&gt;] Stopped replication `c0ebe9256695ff083347cbf95f93e280+continuous+create_target` because replication document `doc_A` was deleted</programlisting>
-
-      <note>
-        <para>
-          You need to <literal moreinfo="none">DELETE</literal> the document that
-          triggered the replication. <literal moreinfo="none">DELETE</literal>ing
-          another document that describes the same replication but did
-          not trigger it, will not cancel the replication.
-        </para>
-      </note>
-
-    </section>
-
-    <section id="couchdb-single-replication-replicatordb-restart">
-
-      <title>Server restart</title>
-
-      <para>
-        When CouchDB is restarted, it checks its
-        <literal moreinfo="none">_replicator</literal> database and restarts any
-        replication that is described by a document that either has its
-        <literal moreinfo="none">_replication_state</literal> field set to
-        <literal moreinfo="none">triggered</literal> or it doesn't have yet the
-        <literal moreinfo="none">_replication_state</literal> field set.
-      </para>
-
-      <note>
-        <para>
-          Continuous replications always have a
-          <literal moreinfo="none">_replication_state</literal> field with the value
-          <literal moreinfo="none">triggered</literal>, therefore they're always
-          restarted when CouchDB is restarted.
-        </para>
-      </note>
-
-    </section>
-
-    <section id="couchdb-single-replication-replicatordb-changing">
-
-      <title>Changing the Replicator Database</title>
-
-      <para>
-        Imagine your replicator database (default name is _replicator)
-        has the two following documents that represent pull replications
-        from servers A and B:
-      </para>
-
-<programlisting format="linespecific">{
-    "_id": "rep_from_A",
-    "source":  "http://aserver.com:5984/foo",
-    "target":  "foo_a",
-    "continuous":  true,
-    "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
-    "_replication_state":  "triggered",
-    "_replication_state_time":  1297971311
-}
-{
-    "_id": "rep_from_B",
-    "source":  "http://bserver.com:5984/foo",
-    "target":  "foo_b",
-    "continuous":  true,
-    "_replication_id":  "231bb3cf9d48314eaa8d48a9170570d1",
-    "_replication_state":  "triggered",
-    "_replication_state_time":  1297974122
-}</programlisting>
-
-      <para>
-        Now without stopping and restarting CouchDB, you change the name
-        of the replicator database to
-        <literal moreinfo="none">another_replicator_db</literal>:
-      </para>
-
-<programlisting format="linespecific">$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"another_replicator_db"'
-"_replicator"</programlisting>
-
-      <para>
-        As soon as this is done, both pull replications defined before,
-        are stopped. This is explicitly mentioned in CouchDB's log:
-      </para>
-
-<programlisting format="linespecific">[Fri, 11 Mar 2011 07:44:20 GMT] [info] [&lt;0.104.0&gt;] Stopping all ongoing replications because the replicator database was deleted or changed
-[Fri, 11 Mar 2011 07:44:20 GMT] [info] [&lt;0.127.0&gt;] 127.0.0.1 - - PUT /_config/replicator/db 200</programlisting>
-
-      <para>
-        Imagine now you add a replication document to the new replicator
-        database named <literal moreinfo="none">another_replicator_db</literal>:
-      </para>
-
-<programlisting format="linespecific">{
-    "_id": "rep_from_X",
-    "source":  "http://xserver.com:5984/foo",
-    "target":  "foo_x",
-    "continuous":  true
-}</programlisting>
-
-      <para>
-        From now own you have a single replication going on in your
-        system: a pull replication pulling from server X. Now you change
-        back the replicator database to the original one
-        <literal moreinfo="none">_replicator</literal>:
-      </para>
-
-<programlisting format="linespecific">$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"_replicator"'
-"another_replicator_db"</programlisting>
-
-      <para>
-        Immediately after this operation, the replication pulling from
-        server X will be stopped and the replications defined in the
-        _replicator database (pulling from servers A and B) will be
-        resumed.
-      </para>
-
-      <para>
-        Changing again the replicator database to
-        <literal moreinfo="none">another_replicator_db</literal> will stop the pull
-        replications pulling from servers A and B, and resume the pull
-        replication pulling from server X.
-      </para>
-
-    </section>
-
-    <section id="couchdb-single-replication-replicatordb-replicating">
-
-      <title>Replicating the replicator database</title>
-
-      <para>
-        Imagine you have in server C a replicator database with the two
-        following pull replication documents in it:
-      </para>
-
-<programlisting format="linespecific">{
-     "_id": "rep_from_A",
-     "source":  "http://aserver.com:5984/foo",
-     "target":  "foo_a",
-     "continuous":  true,
-     "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
-     "_replication_state":  "triggered",
-     "_replication_state_time":  1297971311
-}
-{
-     "_id": "rep_from_B",
-     "source":  "http://bserver.com:5984/foo",
-     "target":  "foo_b",
-     "continuous":  true,
-     "_replication_id":  "231bb3cf9d48314eaa8d48a9170570d1",
-     "_replication_state":  "triggered",
-     "_replication_state_time":  1297974122
-}</programlisting>
-
-      <para>
-        Now you would like to have the same pull replications going on
-        in server D, that is, you would like to have server D pull
-        replicating from servers A and B. You have two options:
-      </para>
-
-      <itemizedlist>
-
-        <listitem>
-          <para>
-            Explicitly add two documents to server's D replicator
-            database
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Replicate server's C replicator database into server's D
-            replicator database
-          </para>
-        </listitem>
-
-      </itemizedlist>
-
-      <para>
-        Both alternatives accomplish exactly the same goal.
-      </para>
-
-    </section>
-
-    <section id="couchdb-single-replication-replicatordb-delegations">
-
-      <title>Delegations</title>
-
-      <para>
-        Replication documents can have a custom
-        <literal moreinfo="none">user_ctx</literal> property. This property defines the
-        user context under which a replication runs. For the old way of
-        triggering replications (POSTing to
-        <literal moreinfo="none">/_replicate/</literal>), this property was not needed
-        (it didn't exist in fact) - this is because at the moment of
-        triggering the replication it has information about the
-        authenticated user. With the replicator database, since it's a
-        regular database, the information about the authenticated user
-        is only present at the moment the replication document is
-        written to the database - the replicator database implementation
-        is like a _changes feed consumer (with
-        <literal moreinfo="none">?include_docs=true</literal>) that reacts to what was
-        written to the replicator database - in fact this feature could
-        be implemented with an external script/program. This
-        implementation detail implies that for non admin users, a
-        <literal moreinfo="none">user_ctx</literal> property, containing the user's name
-        and a subset of his/her roles, must be defined in the
-        replication document. This is ensured by the document update
-        validation function present in the default design document of
-        the replicator database. This validation function also ensure
-        that a non admin user can set a user name property in the
-        <literal moreinfo="none">user_ctx</literal> property that doesn't match his/her
-        own name (same principle applies for the roles).
-      </para>
-
-      <para>
-        For admins, the <literal moreinfo="none">user_ctx</literal> property is
-        optional, and if it's missing it defaults to a user context with
-        name null and an empty list of roles - this mean design
-        documents will not be written to local targets. If writing
-        design documents to local targets is desired, the a user context
-        with the roles <literal moreinfo="none">_admin</literal> must be set explicitly.
-      </para>
-
-      <para>
-        Also, for admins the <literal moreinfo="none">user_ctx</literal> property can be
-        used to trigger a replication on behalf of another user. This is
-        the user context that will be passed to local target database
-        document validation functions.
-      </para>
-
-      <note>
-        <para>
-          The <literal moreinfo="none">user_ctx</literal> property only has effect for
-          local endpoints.
-        </para>
-      </note>
-
-      <para>
-        Example delegated replication document:
-      </para>
-
-<programlisting format="linespecific">{
-     "_id": "my_rep",
-     "source":  "http://bserver.com:5984/foo",
-     "target":  "bar",
-     "continuous":  true,
-     "user_ctx": {
-          "name": "joe",
-          "roles": ["erlanger", "researcher"]
-     }
-}</programlisting>
-
-      <para>
-        As stated before, for admins the user_ctx property is optional,
-        while for regular (non admin) users it's mandatory. When the
-        roles property of <literal moreinfo="none">user_ctx</literal> is missing, it
-        defaults to the empty list <literal moreinfo="none">[ ]</literal>.
-      </para>
-
-    </section>
-
-  </section>
-
-</chapter>
-
-
-
-  <chapter id="couchdb-api-basics">
-
-  <title>CouchDB API</title>
-
-  <para>
-    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.
-  </para>
-
-  <para>
-    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 <literal moreinfo="none">GET</literal> operation, while updates are
-    handled by either a <literal moreinfo="none">POST</literal> or
-    <literal moreinfo="none">PUT</literal> 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
-    <xref linkend="couchdb-api-introduction-requests"/>.
-  </para>
-
-  <para>
-    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 <xref linkend="couchdb-api-introduction-json"/>.
-  </para>
-
-  <para>
-    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
-    <xref linkend="couchdb-api-introduction-returncodes"/>.
-  </para>
-
-  <para>
-    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. For a guide to the
-    different areas of the API, see
-    <xref linkend="couchdb-api-overview"/>.
-  </para>
-
-  <section id="couchdb-api-introduction-requests">
-
-    <title>Request Format and Responses</title>
-
-    <para>
-      CouchDB supports the following HTTP request methods:
-    </para>
-
-    <itemizedlist>
-
-      <listitem>
-        <para>
-          <literal moreinfo="none">GET</literal>
-        </para>
-
-        <para>
-          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.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <literal moreinfo="none">HEAD</literal>
-        </para>
-
-        <para>
-          The <literal moreinfo="none">HEAD</literal> method is used to get the HTTP
-          header of a <literal moreinfo="none">GET</literal> request without the body of
-          the response.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <literal moreinfo="none">POST</literal>
-        </para>
-
-        <para>
-          Upload data. Within CouchDB <literal moreinfo="none">POST</literal> is used to
-          set values, including uploading documents, setting document
-          values, and starting certain administration commands.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <literal moreinfo="none">PUT</literal>
-        </para>
-
-        <para>
-          Used to put a specified resource. In CouchDB
-          <literal moreinfo="none">PUT</literal> is used to create new objects,
-          including databases, documents, views and design documents.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <literal moreinfo="none">DELETE</literal>
-        </para>
-
-        <para>
-          Deletes the specified resource, including documents, views,
-          and design documents.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <literal moreinfo="none">COPY</literal>
-        </para>
-
-        <para>
-          A special method that can be used to copy documents and
-          objects.
-        </para>
-      </listitem>
-
-    </itemizedlist>
-
-    <para>
-      If you use the an unsupported HTTP request type with a URL that
-      does not support the specified type, a 405 error will be returned,
-      listing the supported HTTP methods. For example:
-    </para>
-
-<programlisting format="linespecific">{
-    "error":"method_not_allowed",
-    "reason":"Only GET,HEAD allowed"
-}</programlisting>
-
-
-
-    <para>
-      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 <literal moreinfo="none">headers</literal>
-      block of the return object. For more information, see
-      <xref linkend="couchdb-api-functional"/>.
-    </para>
-
-  </section>
-
-  <section id="couchdb-api-introduction-request-header">
-
-    <title>HTTP Headers</title>
-
-    <para>
-      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.
-    </para>
-
-    <section id="couchdb-api-introduction-request-header-request">
-
-      <title>Request Headers</title>
-
-      <itemizedlist>
-
-        <listitem>
-          <para>
-            <literal moreinfo="none">Content-type</literal>
-          </para>
-
-          <para>
-            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 (<literal moreinfo="none">application/json</literal>). 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
-            (<literal moreinfo="none">application/octet-stream</literal>).
-          </para>
-
-          <para>
-            The use of the <literal moreinfo="none">Content-type</literal> on a request
-            is highly recommended.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            <literal moreinfo="none">Accept</literal>
-          </para>
-
-          <para>
-            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.
-          </para>
-
-          <para>
-            For the majority of requests the definition should be for
-            JSON data (<literal moreinfo="none">application/json</literal>). For
-            attachments you can either specify the MIME type explicitly,
-            or use <literal moreinfo="none">*/*</literal> to specify that all file types
-            are supported. If the <literal moreinfo="none">Accept</literal> header is
-            not supplied, then the <literal moreinfo="none">*/*</literal> MIME type is
-            assumed (i.e. client accepts all formats).
-          </para>
-
-          <para>
-            The use of <literal moreinfo="none">Accept</literal> 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.
-          </para>
-
-          <para>
-            If you specify a data type using the
-            <literal moreinfo="none">Accept</literal> header, CouchDB will honor the
-            specified type in the <literal moreinfo="none">Content-type</literal> header
-            field returned. For example, if you explicitly request
-            <literal moreinfo="none">application/json</literal> in the
-            <literal moreinfo="none">Accept</literal> of a request, the returned HTTP
-            headers will use the value in the returned
-            <literal moreinfo="none">Content-type</literal> field.
-          </para>
-
-          <para>
-            For example, when sending a request without an explicit
-            <literal moreinfo="none">Accept</literal> header, or when specifying
-            <literal moreinfo="none">*/*</literal>:
-          </para>
-
-<programlisting format="linespecific">GET /recipes HTTP/1.1
-Host: couchdb:5984
-Accept: */*</programlisting>
-
-          <para>
-            The returned headers are:
-          </para>
-
-<programlisting format="linespecific">Server: CouchDB/1.0.1 (Erlang OTP/R13B)
-Date: Thu, 13 Jan 2011 13:39:34 GMT
-Content-Type: text/plain;charset=utf-8
-Content-Length: 227
-Cache-Control: must-revalidate</programlisting>
-
-          <para>
-            Note that the returned content type is
-            <literal moreinfo="none">text/plain</literal> even though the information
-            returned by the request is in JSON format.
-          </para>
-
-          <para>
-            Explicitly specifying the <literal moreinfo="none">Accept</literal> header:
-          </para>
-
-<programlisting format="linespecific">GET /recipes HTTP/1.1
-Host: couchdb:5984
-Accept: application/json</programlisting>
-
-          <para>
-            The headers returned include the
-            <literal moreinfo="none">application/json</literal> content type:
-          </para>
-
-<programlisting format="linespecific">Server: CouchDB/1.0.1 (Erlang OTP/R13B)
-Date: Thu, 13 Jan 2011 13:40:11 GMT
-Content-Type: application/json
-Content-Length: 227
-Cache-Control: must-revalidate</programlisting>
-        </listitem>
-
-      </itemizedlist>
-
-    </section>
-
-    <section id="couchdb-api-introduction-request-header-response">
-
-      <title>Response Headers</title>
-
-      <para>
-        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.
-      </para>
-
-      <itemizedlist>
-
-        <listitem>
-          <para>
-            <literal moreinfo="none">Content-type</literal>
-          </para>
-
-          <para>
-            Specifies the MIME type of the returned data. For most
-            request, the returned MIME type is
-            <literal moreinfo="none">text/plain</literal>. All text is encoded in
-            Unicode (UTF-8), and this is explicitly stated in the
-            returned <literal moreinfo="none">Content-type</literal>, as
-            <literal moreinfo="none">text/plain;charset=utf-8</literal>.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            <literal moreinfo="none">Cache-control</literal>
-          </para>
-
-          <para>
-            The cache control HTTP response header provides a suggestion
-            for client caching mechanisms on how to treat the returned
-            information. CouchDB typically returns the
-            <literal moreinfo="none">must-revalidate</literal>, 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.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            <literal moreinfo="none">Content-length</literal>
-          </para>
-
-          <para>
-            The length (in bytes) of the returned content.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            <literal moreinfo="none">Etag</literal>
-          </para>
-
-          <para>
-            The <literal moreinfo="none">Etag</literal> HTTP header field is used to
-            show the revision for a document.
-          </para>
-        </listitem>
-
-      </itemizedlist>
-
-    </section>
-
-  </section>
-
-  <section id="couchdb-api-introduction-json">
-
-    <title>JSON Basics</title>
-
-    <para>
-      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.
-    </para>
-
-    <para>
-      JSON is used because it is the simplest and easiest to use
-      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.
-    </para>
-
-    <para>
-      JSON supports the same basic types as supported by JavaScript,
-      these are:
-    </para>
-
-    <itemizedlist>
-
-      <listitem>
-        <para>
-          Number (either integer or floating-point).
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          String; this should be enclosed by double-quotes and supports
-          Unicode characters and backslash escaping. For example:
-        </para>
-
-<programlisting format="linespecific">"A String"</programlisting>
-      </listitem>
-
-      <listitem>
-        <para>
-          Boolean - a <literal moreinfo="none">true</literal> or
-          <literal moreinfo="none">false</literal> value. You can use these strings
-          directly. For example:
-        </para>
-
-<programlisting format="linespecific">{ "value": true}</programlisting>
-      </listitem>
-
-      <listitem>
-        <para>
-          Array - a list of values enclosed in square brackets. For
-          example:
-        </para>
-
-<programlisting format="linespecific">["one", "two", "three"]</programlisting>
-      </listitem>
-
-      <listitem>
-        <para>
-          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:
-        </para>
-
-<programlisting format="linespecific">{
-   "servings" : 4,
-   "subtitle" : "Easy to make in advance, and then cook when ready",
-   "cooktime" : 60,
-   "title" : "Chicken Coriander"
-}</programlisting>
-
-        <para>
-          In CouchDB, the JSON object is used to represent a variety of
-          structures, including the main CouchDB document.
-        </para>
-      </listitem>
-
-    </itemizedlist>
-
-    <para>
-      Parsing JSON into a JavaScript object is supported through the
-      <literal moreinfo="none">eval()</literal> 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.
-    </para>
-
-    <warning>
-      <para>
-        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). See
-        <xref linkend="couchdb-api-introduction-returncode-500"/>
-        .
-      </para>
-    </warning>
-
-  </section>
-
-  <section id="couchdb-api-introduction-returncodes">
-
-    <title>HTTP Status Codes</title>
-
-    <para>
-      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.
-    </para>
-
-    <para>
-      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.
-    </para>
-
-    <itemizedlist>
-
-      <listitem>
-        <para id="couchdb-api-introduction-returncode-200">
-          <literal moreinfo="none">200 - OK</literal>
-        </para>
-
-        <para>
-          Request completed successfully.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para id="couchdb-api-introduction-returncode-201">
-          <literal moreinfo="none">201 - Created</literal>
-        </para>
-
-        <para>
-          Document created successfully.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para id="couchdb-api-introduction-returncode-202">
-          <literal moreinfo="none">202 - Accepted</literal>
-        </para>
-
-        <para>
-          Request has been accepted, but the corresponding operation may
-          not have completed. This is used for background operations,
-          such as database compaction.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para id="couchdb-api-introduction-returncode-304">
-          <literal moreinfo="none">304 - Not Modified</literal>
-        </para>
-
-        <para>
-          The additional content requested has not been modified. This
-          is used with the ETag system to identify the version of
-          information returned.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para id="couchdb-api-introduction-returncode-400">
-          <literal moreinfo="none">400 - Bad Request</literal>
-        </para>
-
-        <para>
-          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.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para id="couchdb-api-introduction-returncode-401">
-          <literal moreinfo="none">401 - Unauthorized</literal>
-        </para>
-
-        <para>
-          The item requested was not available using the supplied
-          authorization, or authorization was not supplied.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para id="couchdb-api-introduction-returncode-403">
-          <literal moreinfo="none">403 - Forbidden</literal>
-        </para>
-
-        <para>
-          The requested item or operation is forbidden.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para id="couchdb-api-introduction-returncode-404">
-          <literal moreinfo="none">404 - Not Found</literal>
-        </para>
-
-        <para>
-          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, <literal moreinfo="none">error</literal>
-          and <literal moreinfo="none">reason</literal>. For example:
-        </para>
-
-<programlisting format="linespecific">{"error":"not_found","reason":"no_db_file"}</programlisting>
-      </listitem>
-
-      <listitem>
-        <para id="couchdb-api-introduction-returncode-405">
-          <literal moreinfo="none">405 - Resource Not Allowed</literal>
-        </para>
-
-        <para>
-          A request was made using an invalid HTTP request type for the
-          URL requested. For example, you have requested a
-          <literal moreinfo="none">PUT</literal> when a <literal moreinfo="none">POST</literal> is
-          required. Errors of this type can also triggered by invalid
-          URL strings.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para id="couchdb-api-introduction-returncode-406">
-          <literal moreinfo="none">406 - Not Acceptable</literal>
-        </para>
-
-        <para>
-          The requested content type is not supported by the server.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para id="couchdb-api-introduction-returncode-409">
-          <literal moreinfo="none">409 - Conflict</literal>
-        </para>
-
-        <para>
-          Request resulted in an update conflict.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para id="couchdb-api-introduction-returncode-412">
-          <literal moreinfo="none">412 - Precondition Failed</literal>
-        </para>
-
-        <para>
-          The request headers from the client and the capabilities of
-          the server do not match.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para id="couchdb-api-introduction-returncode-415">
-          <literal moreinfo="none">415 - Bad Content Type</literal>
-        </para>
-
-        <para>
-          The content types supported, and the content type of the
-          information being requested or submitted indicate that the
-          content type is not supported.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para id="couchdb-api-introduction-returncode-416">
-          <literal moreinfo="none">416 - Requested Range Not Satisfiable</literal>
-        </para>
-
-        <para>
-          The range specified in the request header cannot be satisfied
-          by the server.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para id="couchdb-api-introduction-returncode-417">
-          <literal moreinfo="none">417 - Expectation Failed</literal>
-        </para>
-
-        <para>
-          When sending documents in bulk, the bulk load operation
-          failed.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para id="couchdb-api-introduction-returncode-500" xreflabel="HTTP               Status Code 500">
-          <literal moreinfo="none">500 - Internal Server Error</literal>
-        </para>
-
-        <para>
-          The request was invalid, either because the supplied JSON was
-          invalid, or invalid information was supplied as part of the
-          request.
-        </para>
-      </listitem>
-
-    </itemizedlist>
-
-  </section>
-
-  <section id="couchdb-api-overview">
-
-    <title>CouchDB API Overview</title>
-
-    <para>
-      The components of the API URL path help determine the part of the
-      CouchDB server that is being accessed. The result is the structure
-      of the URL request both identifies and effectively describes the
-      area of the database you are accessing.
-    </para>
-
-    <para>
-      As with all URLs, the individual components are separated by a
-      forward slash.
-    </para>
-
-    <para>
-      As a general rule, URL components and JSON fields starting with
-      the <literal moreinfo="none">_</literal> (underscore) character represent a
-      special component or entity within the server or returned object.
-      For example, the URL fragment <literal moreinfo="none">/_all_dbs</literal> gets a
-      list of all of the databases in a CouchDB instance.
-    </para>
-
-    <para>
-      The remainder of the URL API structure can be divided up according
-      to the URL structure. The different sections are divided as
-      follows:
-    </para>
-
-    <itemizedlist>
-
-      <listitem>
-        <para>
-          <literal moreinfo="none">/db</literal>
-        </para>
-
-        <para>
-          Database methods, related to adding, updating or deleting
-          databases, and setting database parameters and operations. For
-          more detailed information, see
-          <xref linkend="couchdb-api-db"/> .
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <literal moreinfo="none">/db/doc</literal>
-        </para>
-
-        <para>
-          Document methods, those that create, store, update or delete
-          CouchDB documents and their attachments. For more information,
-          see <xref linkend="couchdb-api-dbdoc"/>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <literal moreinfo="none">/db/_local/local-doc</literal>
-        </para>
-
-        <para>
-          Document methods, those that create, store, update or delete
-          CouchDB documents only within the local database. Local
-          documents are not synchronized with other databases. For more
-          information, see
-          <xref linkend="couchdb-api-localdb"/>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <literal moreinfo="none">/db/_design/design-doc</literal>
-        </para>
-
-        <para>
-          Design documents provide the methods and structure for
-          recovering information from a CouchDB database in the form of
-          views, shows and lists. For more information, see
-          <xref linkend="couchdb-api-design"/>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <literal moreinfo="none">/_special</literal>
-        </para>
-
-        <para>
-          Special methods that obtain or set information about the
-          CouchDB instance, including methods for configuring
-          replication, accessing the logs, and generate Universally
-          Unique IDs (UUIDs). For more information, see
-          <xref linkend="couchdb-api-misc"/>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <literal moreinfo="none">/_config</literal>
-        </para>
-
-        <para>
-          Methods for getting, and settings, CouchDB configuration
-          parameters. For more information, see
-          <xref linkend="couchdb-api-misc"/>.
-        </para>
-      </listitem>
-
-    </itemizedlist>
-
-
-
-  </section>
-
-</chapter>
-
-  <chapter id="couchdb-api-db">
-
-  <title>CouchDB API Server Database Methods</title>
-
-  <para>
-    The Database methods provide an interface to an entire database
-    withing CouchDB. These are database, rather than document, level
-    requests.
-  </para>
-
-  <para>
-    A list of the available methods and URL paths are provided below:
-  </para>
-
-  <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/>
-<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/>
-<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/>
-<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/>
-<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/>
-<table id="table-couchdb-api-db-summary"><title>Database API Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db</literal></entry><entry><link linkend="couchdb-api-db_db_get">
- Returns database information
- </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db</literal></entry><entry><link linkend="couchdb-api-db_db_put">
- Create a new database
- </link></entry></row><row><entry><literal moreinfo="none">DELETE</literal></entry><entry><literal moreinfo="none">/db</literal></entry><entry><link linkend="couchdb-api-db_db_delete">
- Delete an existing database
- </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_all_docs</literal></entry><entry><link linkend="couchdb-api-db_db-all-docs_get">
- Returns a built-in view of all documents in this database
- </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_all_docs</literal></entry><entry><link linkend="couchdb-api-db_db-all-docs_post">
- Returns certain rows from the built-in view of all documents
- </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_bulk_docs</literal></entry><entry><link linkend="couchdb-api-db_db-bulk-docs_post">
- Insert multiple documents in to the database in a single request
- </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_changes</literal></entry><entry><link linkend="couchdb-api-db_db-changes_get">
- Returns changes for the given database
- </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_compact</literal></entry><entry><link linkend="couchdb-api-db_db-compact_post">
- Starts a compaction for the database
- </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_compact/design-doc</literal></entry><entry><link linkend="couchdb-api-db_db-compact-design-doc_post">
- Starts a compaction for all the views in the selected design
- document
- </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_ensure_full_commit</literal></entry><entry><link linkend="couchdb-api-db_db-ensure-full-commit_post">
- Makes sure all uncommitted changes are written and synchronized
- to the disk
- </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_missing_revs</literal></entry><entry><link linkend="couchdb-api-db_db-missing-revs_post">
- Given a list of document revisions, returns the document
- revisions that do not exist in the database
- </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_purge</literal></entry><entry><link linkend="couchdb-api-db_db-purge_post">
- Purge some historical documents entirely from database history
- </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_revs_diff</literal></entry><entry><link linkend="couchdb-api-db_db-revs-diff_post">
- Given a list of document revisions, returns differences between
- the given revisions and ones that are in the database
- </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_revs_limit</literal></entry><entry><link linkend="couchdb-api-db_db-revs-limit_get">
- Gets the limit of historical revisions to store for a single
- document in the database
- </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db/_revs_limit</literal></entry><entry><link linkend="couchdb-api-db_db-revs-limit_put">
- Sets the limit of historical revisions to store for a single
- document in the database
- </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_security</literal></entry><entry><link linkend="couchdb-api-db_db-security_get">
- Returns the special security object for the database
- </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db/_security</literal></entry><entry><link linkend="couchdb-api-db_db-security_put">
- Sets the special security object for the database
- </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_temp_view</literal></entry><entry><link linkend="couchdb-api-db_db-temp-view_post">
- Execute a given view function for all documents and return the
- result
- </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_view_cleanup</literal></entry><entry><link linkend="couchdb-api-db_db-view-cleanup_post">
- Removes view files that are not used by any design document
- </link></entry></row></tbody></tgroup></table>
-
-  <para>
-    For all the database methods, the database name within the URL path
-    should be the database name that you wish to perform the operation
-    on. For example, to obtain the meta information for the database
-    <literal moreinfo="none">recipes</literal>, you would use the HTTP request:
-  </para>
-
-<programlisting format="linespecific">GET /recipes</programlisting>
-
-  <para>
-    For clarity, the form below is used in the URL paths:
-  </para>
-
-<programlisting format="linespecific">GET /db</programlisting>
-
-  <para>
-    Where <literal moreinfo="none">db</literal> is the name of any database.
-  </para>
-
-  <section id="couchdb-api-db_db_get">
-
-    <title><literal moreinfo="none">GET /db</literal></title>
-
-    <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/>
-<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/>
-<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/>
-<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/>
-<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/>
-<informaltable><textobject><phrase>URL API GET /db</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo">
- None
- </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo">
- Information about the database in JSON format
- </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo">
- The requested content could not be found. The returned content
- will include further information, as a JSON object, if available.
- </entry></row></tbody></tgroup></informaltable>
-
-    <para>
-      Gets information about the specified database. For example, to
-      retrieve the information for the database
-      <literal moreinfo="none">recipe</literal>:
-    </para>
-
-<programlisting role="httprequest" format="linespecific">GET http://couchdb:5984/recipes
-Accept: application/json</programlisting>
-
-    <para>
-      The JSON response contains meta information about the database. A
-      sample of the JSON returned for an empty database is provided
-      below:
-    </para>
-
-<programlisting role="httpresponse" format="linespecific">{
-   "compact_running" : false,
-   "committed_update_seq" : 375048,
-   "disk_format_version" : 5,
-   "disk_size" : 33153123,
-   "doc_count" : 18386,
-   "doc_del_count" : 0,
-   "db_name" : "recipes",
-   "instance_start_time" : "1290700340925570",
-   "purge_seq" : 10,
-   "update_seq" : 375048
-}</programlisting>
-
-    <para>
-      The elements of the returned structure are shown in the table
-      below:
-    </para>
-
-    <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/>
-<remark role="dependency-meta" condition="../metadocs//json/json.xml"/>
-<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/>
-<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/>
-<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/>
-<table id="table-couchdb-api-db-json-db-info" class="jsonstructure"><title>
- CouchDB database information object
- </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">committed_update_seq</literal>  </entry><entry>
- The number of committed update.
- </entry></row><row><entry><literal moreinfo="none">compact_running</literal>  </entry><entry>
- Set to true if the database compaction routine is operating on
- this database.
- </entry></row><row><entry><literal moreinfo="none">db_name</literal>  </entry><entry>
- The name of the database.
- </entry></row><row><entry><literal moreinfo="none">disk_format_version</literal>  </entry><entry>
- The version of the physical format used for the data when it is
- stored on disk.
- </entry></row><row><entry><literal moreinfo="none">disk_size</literal>  </entry><entry>
- Size in bytes of the data as stored on the disk. Views indexes
- are not included in the calculation.
- </entry></row><row><entry><literal moreinfo="none">doc_count</literal>  </entry><entry>
- A count of the documents in the specified database.
- </entry></row><row><entry><literal moreinfo="none">doc_del_count</literal>  </entry><entry>
- Number of deleted documents
- </entry></row><row><entry><literal moreinfo="none">instance_start_time</literal>  </entry><entry>
- Timestamp of when the database was created, expressed in
- milliseconds since the epoch.
- </entry></row><row><entry><literal moreinfo="none">purge_seq</literal>  </entry><entry>
- The number of purge operations on the database.
- </entry></row><row><entry><literal moreinfo="none">update_seq</literal>  </entry><entry>
- The current number of updates to the database.
- </entry></row></tbody></tgroup></table>
-
-  </section>
-
-  <section id="couchdb-api-db_db_put">
-
-    <title><literal moreinfo="none">PUT /db</literal></title>
-
-    <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/>
-<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/>
-<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/>
-<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/>
-<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/>
-<informaltable><textobject><phrase>URL API PUT /db</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">PUT /db</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo">
- None
- </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo">
- JSON success statement
- </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>400</entry><entry namest="info" nameend="addinfo">
- Invalid database name
- </entry></row><row><entry>412</entry><entry namest="info" nameend="addinfo">
- Database already exists
- </entry></row></tbody></tgroup></informaltable>
-
-    <para>
-      Creates a new database. The database name must be composed of one
-      or more of the following characters:
-    </para>
-
-    <itemizedlist>
-
-      <listitem>
-        <para>
-          Lowercase characters (<literal moreinfo="none">a-z</literal>)
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          Name must begin with a lowercase letter
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          Digits (<literal moreinfo="none">0-9</literal>)
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          Any of the characters <literal moreinfo="none">_</literal>,
-          <literal moreinfo="none">$</literal>, <literal moreinfo="none">(</literal>,
-          <literal moreinfo="none">)</literal>, <literal moreinfo="none">+</literal>,
-          <literal moreinfo="none">-</literal>, and <literal moreinfo="none">/</literal>.
-        </para>
-      </listitem>
-
-    </itemizedlist>
-
-    <para>
-      Trying to create a database that does not meet these requirements
-      will return an error quoting these restrictions.
-    </para>
-
-    <para>
-      To create the database <literal moreinfo="none">recipes</literal>:
-    </para>
-
-<programlisting format="linespecific">PUT http://couchdb:5984/recipes
-Content-Type: application/json</programlisting>
-
-    <para>
-      The returned content contains the JSON status:
-    </para>
-
-<programlisting format="linespecific">{
-   "ok" : true
-}</programlisting>
-
-    <para>
-      Anything should be treated as an error, and the problem should be
-      taken form the HTTP response code.
-    </para>
-
-  </section>
-
-  <section id="couchdb-api-db_db_delete">
-
-    <title><literal moreinfo="none">DELETE /db</literal></title>
-
-    <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/>
-<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/>
-<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/>
-

<TRUNCATED>

Mime
View raw message