Merge lp:~thisfred/u1db/documentation-update into lp:u1db

[Eric Casteleijn]

Added make doctest to make check, so the documentation has a higher chance of not lying. Corrected the documentation to pass doctests and tell the truth.

Added make doctest to make check, so the documentation has a higher chance of not lying. Corrected the documentation to pass doctests and tell the truth.

[Lucio Torre (lucio.torre)]

review: Approve

=== modified file 'CMakeLists.txt'
--- CMakeLists.txt	2012-07-05 16:00:16 +0000
+++ CMakeLists.txt	2012-07-16 17:22:17 +0000
@@ -40,9 +40,13 @@
   ${CMAKE_CURRENT_BINARY_DIR}
   WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} )
 
+add_custom_target(doctests
+    COMMAND cd html-docs && make doctest && cd ..
+)
+
 add_custom_target(check
     COMMAND python -m testtools.run discover
-    DEPENDS build-inplace
+    DEPENDS build-inplace doctests
 )
 
 add_custom_target(build-inplace
 
=== modified file 'doc/sqlite_schema.txt'
--- doc/sqlite_schema.txt	2011-12-02 10:15:55 +0000
+++ doc/sqlite_schema.txt	2012-07-16 17:22:17 +0000
@@ -25,7 +25,7 @@
 It is intended to be a list of fields, and possibly mappings on those fields.
 Something like::
 
-    CREATE_INDEX(mydb, "myindex", ["field", "other.subfield", "number(third)"]) 
+    CREATE_INDEX(mydb, "myindex", ["field", "other.subfield", "number(third)"])
 
 
 Recommended Implementation
@@ -83,7 +83,7 @@
 
     {"lastname": "pedroni", "firstname": "john"}
 
-Which should not match the above query. 
+Which should not match the above query.
 
 We also want an SQL index on this table, something like [#]_::
 
@@ -134,7 +134,7 @@
 3) It isn't hard to map nested fields into this structure. And you have
    the nice property that you don't have to change the data to add/remove an
    index.
-   
+
 4) It isn't 100% clear how we handle mapped fields in this structure. Something
    like ``lower(lastname)``. It is possible that we could only support the set
    of mappings that we can do with SQL on the live data. However, that will
@@ -147,7 +147,7 @@
    seem to support turning "SELECT * FROM table WHERE value LIKE 'p%'" into an
    index query. Even though value is in a btree, it doesn't use it. However,
    you could use >= and < to get a range query. Something like::
-   
+
         SELECT * FROM table WHERE value >= 'p' AND value < 'q'
 
    Since sqlite supports closed and open ended ranges, we don't have to play
@@ -168,7 +168,7 @@
 -----------------
 
 The same schema as defined above, except you always put every field into the
-document_fields table. 
+document_fields table.
 
 Discussion
 ~~~~~~~~~~
 
=== modified file 'html-docs/conflicts.rst'
--- html-docs/conflicts.rst	2011-12-21 16:09:22 +0000
+++ html-docs/conflicts.rst	2012-07-16 17:22:17 +0000
@@ -7,26 +7,26 @@
 Conflicts
 -------------
 
-If two u1dbs are synced, and then the same document is changed in different ways
-in each u1db, and then they are synced again, there will be a *conflict*. This
-does not block synchronisation: the document is registered as being in conflict,
-and resolving that is up to the u1db-using application.
+If two u1dbs are synced, and then the same document is changed in different
+ways in each u1db, and then they are synced again, there will be a *conflict*.
+This does not block synchronisation: the document is registered as being in
+conflict, and resolving that is up to the u1db-using application.
 
 Importantly, **conflicts are not synced**. If *machine A* initiates a sync with
 *machine B*, and this sync results in a conflict, the conflict **only registers
 on machine A**. This policy is sometimes called "other wins": the machine you
 synced *to* wins conflicts, and the document will have machine B's content on
-both machine A and machine B. However, on machine A the document is marked
-as having conflicts, and must be resolved there:
+both machine A and machine B. However, on machine A the document is marked as
+having conflicts, and must be resolved there:
 
 .. testsetup ::
 
     import u1db, json
     db=u1db.open(':memory:', True)
     docFromA=u1db.Document('test','machineA:1',json.dumps({'camefrom':'machineA'}))
-    db.put_doc_if_newer(docFromA, save_conflict=True)
+    db._put_doc_if_newer(docFromA, save_conflict=True, replica_uid='machineA', replica_gen=1)
     docFromB=u1db.Document('test','machineB:1',json.dumps({'camefrom':'machineB'}))
-    db.put_doc_if_newer(docFromB, save_conflict=True)
+    db._put_doc_if_newer(docFromB, save_conflict=True, replica_uid='machineB', replica_gen=1)
 
 .. doctest ::
 
@@ -35,66 +35,67 @@
     >>> docFromB.has_conflicts # the document is in conflict
     True
     >>> conflicts = db.get_doc_conflicts(docFromB.doc_id)
-    >>> print conflicts
-    [(u'machineB:1', u'{"camefrom": "machineB"}'), (u'machineA:1', u'{"camefrom": "machineA"}')]
-    >>> db.resolve_doc(docFromB, [x[0] for x in conflicts]) # resolve in favour of B
+    >>> conflicts
+    [Document(test, machineB:1, conflicted, u'{"camefrom": "machineB"}'), Document(test, machineA:1, u'{"camefrom": "machineA"}')]
+    >>> db.resolve_doc(docFromB, [d.rev for d in conflicts]) # resolve in favour of B
     >>> doc_is_now = db.get_doc("test")
     >>> doc_is_now.content # the content has been updated to doc's content
-    u'{"camefrom": "machineB"}'
+    {u'camefrom': u'machineB'}
+    >>> db.get_doc_conflicts(docFromB.doc_id)
+    []
     >>> doc_is_now.has_conflicts # and is no longer in conflict
     False
 
 Note that ``put_doc`` will fail because we got conflicts from a sync, but it
-may also fail for another reason. If you acquire a document before a sync and 
-then sync, and the sync updates that document, then re-putting that document 
-with modified content will also fail, because the revision is not the current 
+may also fail for another reason. If you acquire a document before a sync and
+then sync, and the sync updates that document, then re-putting that document
+with modified content will also fail, because the revision is not the current
 one. This will raise a ``RevisionConflict`` error.
 
 Revisions
 ----------
 
-As an app developer, you should treat a ``Document``'s ``revision`` as an opaque
-cookie; do not try and deconstruct it or edit it. It is for your u1db 
+As an app developer, you should treat a ``Document``'s ``revision`` as an
+opaque cookie; do not try and deconstruct it or edit it. It is for your u1db
 implementation's use. You can therefore ignore the rest of this section.
 
-If you are writing a new u1db implementation, understanding revisions is 
+If you are writing a new u1db implementation, understanding revisions is
 important, and this is where you find out about them.
 
 To keep track of document revisions u1db uses vector versions. Each
-synchronized instance of the same database is called a replica and has
-a unique identifier (``replica uid``) assigned to it (currently the
-reference implementation by default uses UUID4s for that); a
-revision is a mapping between ``replica uids`` and ``edit numbers``: ``rev =
-<replica_uid:edit_num...>``, or using a functional notation
-``rev(replica_uid) = edit_num``. The current concrete format is a string
-built out of each ``replica_uid`` concatenated with ``':'`` and with its edit
-number in decimal, sorted lexicographically by ``replica_uid`` and then
-all joined with ``'|'``, for example: ``'replicaA:1|replicaB:3'`` . Absent
-``replica uids`` in a revision mapping are implicitly mapped to edit
-number 0.
+synchronized instance of the same database is called a replica and has a unique
+identifier (``replica uid``) assigned to it (currently the reference
+implementation by default uses UUID4s for that); a revision is a mapping
+between ``replica uids`` and ``edit numbers``: ``rev
+= <replica_uid:edit_num...>``, or using a functional notation
+``rev(replica_uid) = edit_num``. The current concrete format is a string built
+out of each ``replica_uid`` concatenated with ``':'`` and with its edit number
+in decimal, sorted lexicographically by ``replica_uid`` and then all joined
+with ``'|'``, for example: ``'replicaA:1|replicaB:3'`` . Absent ``replica
+uids`` in a revision mapping are implicitly mapped to edit number 0.
 
 The new revision of a document modified locally in a replica, is the
-modification of the old revision where the edit number mapped for the
-editing ``replica uid`` is increased by 1.
+modification of the old revision where the edit number mapped for the editing
+``replica uid`` is increased by 1.
 
-When syncing one needs to establish whether an incoming revision is
-newer than the current one or in conflict. A revision 
+When syncing one needs to establish whether an incoming revision is newer than
+the current one or in conflict. A revision
 
 ``rev1 = <replica_1i:edit_num1i|i=1..n>``
 
-is newer than a different 
+is newer than a different
 
 ``rev2 = <replica_2j:edit_num2j|j=1..m>``
 
-if for all ``i=1..n``, ``rev2(replica_1i) <= edit_num1i`` 
-
-and for all ``j=1..m``, ``rev1(replica_2j) >= edit_num2j``. 
-
-Two revisions which are not equal nor one newer than the
-other are in conflict.
-
-When resolving a conflict locally in a replica ``replica_resol``, starting from 
-``rev1...revN`` in conflict, the resulting revision ``rev_resol`` is obtained by:
+if for all ``i=1..n``, ``rev2(replica_1i) <= edit_num1i``
+
+and for all ``j=1..m``, ``rev1(replica_2j) >= edit_num2j``.
+
+Two revisions which are not equal nor one newer than the other are in conflict.
+
+When resolving a conflict locally in a replica ``replica_resol``, starting from
+``rev1...revN`` in conflict, the resulting revision ``rev_resol`` is obtained
+by:
 
      ``R`` is the set the of all replicas explicitly mentioned in ``rev1..revN``
 
 
=== modified file 'html-docs/high-level-api.rst'
--- html-docs/high-level-api.rst	2011-12-21 11:09:04 +0000
+++ html-docs/high-level-api.rst	2012-07-16 17:22:17 +0000
@@ -4,23 +4,22 @@
 ##################
 
 The U1DB API has three separate sections: document storage and retrieval,
-querying, and sync. Here we describe the high-level API. Remember that you
-will need to choose an implementation, and exactly how this API is defined
-is implementation-specific, in order that it fits with the language's 
-conventions.
+querying, and sync. Here we describe the high-level API. Remember that you will
+need to choose an implementation, and exactly how this API is defined is
+implementation-specific, in order that it fits with the language's conventions.
 
 Document storage and retrieval
 ##############################
 
 U1DB stores documents. A document is a set of nested key-values; basically,
-anything you can express with JSON. Implementations are likely to provide a 
-Document object "wrapper" for these documents; exactly how the wrapper works
+anything you can express with JSON. Implementations are likely to provide
+a Document object "wrapper" for these documents; exactly how the wrapper works
 is implementation-defined.
 
 Creating and editing documents
 ------------------------------
 
-To create a document, use ``create_doc()``. Code examples below are from 
+To create a document, use ``create_doc()``. Code examples below are from
 :ref:`reference-implementation` in Python.
 
 .. testcode ::
@@ -33,12 +32,12 @@
 
 .. testoutput ::
 
-    {"key": "value"}
+    {'key': 'value'}
     testdoc
 
-Editing an *existing* document is done with ``put_doc()``. This is separate from
-``create_doc()`` so as to avoid accidental overwrites. ``put_doc()`` takes a
-``Document`` object, because the object encapsulates revision information for
+Editing an *existing* document is done with ``put_doc()``. This is separate
+from ``create_doc()`` so as to avoid accidental overwrites. ``put_doc()`` takes
+a ``Document`` object, because the object encapsulates revision information for
 a particular document.
 
 .. testcode ::
@@ -52,15 +51,16 @@
     except u1db.errors.RevisionConflict:
         print "There was a conflict when creating the doc!"
     print "Now editing the doc with the doc object we got back..."
-    data = json.loads(doc1.content)
-    data["key1"] = "edited"
-    doc1.content = json.dumps(data)
+    doc1.content["key1"] = "edited"
     db.put_doc(doc1)
+    doc2 = db.get_doc(doc1.doc_id)
+    print doc2.content
 
 .. testoutput ::
 
     There was a conflict when creating the doc!
     Now editing the doc with the doc object we got back...
+    {u'key1': u'edited'}
 
 Finally, deleting a document is done with ``delete_doc()``.
 
@@ -70,9 +70,14 @@
     db = u1db.open(":memory:", create=True)
     doc = db.create_doc(json.dumps({"key": "value"}))
     db.delete_doc(doc)
+    print db.get_doc(doc.doc_id)
+    doc = db.get_doc(doc.doc_id, include_deleted=True)
+    print doc.content
 
 .. testoutput ::
 
+    None
+    None
 
 Retrieving documents
 --------------------
@@ -90,7 +95,7 @@
 
 .. testoutput ::
 
-    {"key": "value"}
+    {u'key': u'value'}
     testdoc
 
 And it's also possible to retrieve many documents by ``doc_id``.
@@ -140,7 +145,7 @@
     {"firstname": "Alan", "surname", "Hansen", "position": "defence"} ID ah
     {"firstname": "John", "surname", "Wayne", "position": "filmstar"} ID jw
 
-an index expression of ``["firstname"]`` will create an index that looks 
+an index expression of ``["firstname"]`` will create an index that looks
 (conceptually) like this
 
  ====================== ===========
@@ -152,25 +157,25 @@
  John                   jw
  ====================== ===========
 
-and that index is created with ``create_index("by-firstname", ["firstname"])`` - that is,
-create an index with a name and a list of index expressions. (Exactly how to
-pass the name and the list of index expressions is something specific to
-each implementation.)
+and that index is created with ``create_index("by-firstname", "firstname")``
+-- that is, create an index with a name and a list of index expressions.
+(Exactly how to pass the name and the list of index expressions is something
+specific to each implementation.)
 
 Index expressions
 ^^^^^^^^^^^^^^^^^
 
-An index expression describes how to get data from a document; you can think
-of it as describing a function which, when given a document, returns a value,
+An index expression describes how to get data from a document; you can think of
+it as describing a function which, when given a document, returns a value,
 which is then used as the index key.
 
 **Name a field.** A basic index expression is a dot-delimited list of nesting
-fieldnames, so the index expression ``field.sub1.sub2`` applied to a document 
+fieldnames, so the index expression ``field.sub1.sub2`` applied to a document
 with ID ``doc1`` and content::
 
   {
-      "field": { 
-          "sub1": { 
+      "field": {
+          "sub1": {
               "sub2": "hello"
               "sub3": "not selected"
           }
@@ -187,11 +192,11 @@
 
 **Name a list.** If an index expression names a field whose contents is a list
 of strings, the doc will have multiple entries in the index, one per entry in
-the list. So, the index expression ``field.tags`` applied to a document with 
-ID "doc2" and content::
+the list. So, the index expression ``field.tags`` applied to a document with ID
+"doc2" and content::
 
   {
-      "field": { 
+      "field": {
           "tags": [ "tag1", "tag2", "tag3" ]
       }
   }
@@ -206,25 +211,30 @@
  tag3      doc2
  ========= ======
 
-**Transformation functions.** An index expression may be wrapped in any number of
-transformation functions. A function transforms the result of the contained
-index expression: for example, if an expression ``name.firstname`` generates 
-"John" when applied to a document, then ``lower(name.firstname)`` generates 
+**Transformation functions.** An index expression may be wrapped in any number
+of transformation functions. A function transforms the result of the contained
+index expression: for example, if an expression ``name.firstname`` generates
+"John" when applied to a document, then ``lower(name.firstname)`` generates
 "john".
 
 Available transformation functions are:
 
  * ``lower(index_expression)`` - lowercase the value
- * ``splitwords(index_expression)`` - split the value on whitespace; will act like a 
-   list and add multiple entries to the index
- * ``is_null(index_expression)`` - True if value is null or not a string or the field 
-   is absent, otherwise false
+ * ``splitwords(index_expression)`` - split the value on whitespace; will act
+   like a list and add multiple entries to the index
+ * ``number(index_expression, width)`` - takes an integer value, and turns it
+   into a string, left padded with zeroes, to make it at least as wide as
+   width.
+ * ``bool(index_expression)`` - takes a boolean value and turns it into '0' if
+   false and '1' if true.
+ * ``is_null(index_expression)`` - True if value is null or not a string or the
+   field is absent, otherwise false
 
-So, the index expression ``splitwords(lower(field.name))`` applied to a document with 
-ID "doc3" and content::
+So, the index expression ``splitwords(lower(field.name))`` applied to
+a document with ID "doc3" and content::
 
   {
-      "field": { 
+      "field": {
           "name": "Bruce David Grobbelaar"
       }
   }
@@ -243,25 +253,18 @@
 Querying an index
 -----------------
 
-Pass a list of tuples of index keys to ``get_from_index``; the last index key in
-each tuple (and *only* the last one) can end with an asterisk, which matches 
-initial substrings. So, querying our ``by-firstname`` index from above::
-
-    get_from_index(
-        "by-firstname",                     # name of index
-            [                               # begin the list of index keys
-                ("John", )                  # an index key
-            ]                               # end the list
-    )
-
-
-will return ``[ 'jw', 'jb' ]`` - that is, a list of document IDs.
-
-``get_from_index("by_firstname", [("J*")])`` will match all index keys beginning
-with "J", and so will return ``[ 'jw', 'jb', 'jm' ]``.
-
-``get_from_index("by_firstname", [("Jan"), ("Alan")])`` will match both the
-queried index keys, and so will return ``[ 'jm', 'ah' ]``.
+Pass an index key or a tuple of index keys (if the index is on multiple fields)
+to ``get_from_index``; the last index key in each tuple (and *only* the last
+one) can end with an asterisk, which matches initial substrings. So, querying
+our ``by-firstname`` index from above::
+
+    get_from_index("by-firstname", "John")
+
+
+will return the documents with ids: 'jw', 'jb'.
+
+``get_from_index("by_firstname", "J*")`` will match all index keys beginning
+with "J", and so will return the documents with ids: 'jw', 'jb', 'jm'.
 
 
 Index functions
@@ -277,30 +280,30 @@
 #######
 
 U1DB is a syncable database. Any U1DB can be synced with any U1DB server; most
-U1DB implementations are capable of being run as a server. Syncing brings
-both the server and the client up to date with one another; save data into a
-local U1DB whether online or offline, and then sync when online.
+U1DB implementations are capable of being run as a server. Syncing brings both
+the server and the client up to date with one another; save data into a local
+U1DB whether online or offline, and then sync when online.
 
 Pass an HTTP URL to sync with that server.
 
 Syncing databases which have been independently changed may produce conflicts.
 Read about the U1DB conflict policy and more about syncing at :ref:`conflicts`.
 
-Running your own U1DB server is implementation-specific. :ref:`reference-implementation` 
-is able to be run as a server.
+Running your own U1DB server is implementation-specific.
+:ref:`reference-implementation` is able to be run as a server.
 
 Dealing with conflicts
 ----------------------
 
-Syncing a database can result in conflicts; if your user changes the same 
+Syncing a database can result in conflicts; if your user changes the same
 document in two different places and then syncs again, that document will be
 ''in conflict'', meaning that it has incompatible changes. If this is the case,
-``doc.has_conflicts`` will be true, and put_doc to a conflicted doc will give a
-``ConflictedDoc`` error. To get a list of conflicted versions of the
-document, do ``get_doc_conflicts(doc_id)``. Deciding what the final unconflicted
-document should look like is obviously specific to the user's application; once
-decided, call ``resolve_doc(doc, list_of_conflicted_revisions)`` to resolve and
-set the final resolved content.
+``doc.has_conflicts`` will be true, and put_doc to a conflicted doc will give
+a ``ConflictedDoc`` error. To get a list of conflicted versions of the
+document, do ``get_doc_conflicts(doc_id)``. Deciding what the final
+unconflicted document should look like is obviously specific to the user's
+application; once decided, call ``resolve_doc(doc, list_of_conflicted_revisions)``
+to resolve and set the final resolved content.
 
 Syncing functions
 ^^^^^^^^^^^^^^^^^
 
=== modified file 'html-docs/index.rst'
--- html-docs/index.rst	2011-12-21 13:49:41 +0000
+++ html-docs/index.rst	2012-07-16 17:22:17 +0000
@@ -1,29 +1,29 @@
 U1DB
 ####
 
-U1DB is a database API for synchronised databases of JSON documents. It's 
-simple to use in applications, and allows apps to store documents and 
-synchronise them between machines and devices. U1DB itself is not a database: 
-instead, it's an API which can be backed by any database for storage. This means that you 
-can use u1db on different platforms, from different languages, and backed 
-on to different databases, and sync between all of them.
+U1DB is a database API for synchronised databases of JSON documents. It's
+simple to use in applications, and allows apps to store documents and
+synchronise them between machines and devices. U1DB itself is not a database:
+instead, it's an API which can be backed by any database for storage. This
+means that you can use u1db on different platforms, from different languages,
+and backed on to different databases, and sync between all of them.
 
 The API for U1DB looks similar across all different implementations. This API
-is described at :ref:`high-level-api`. To actually use U1DB you'll need an 
-implementation; a version of U1DB made available on your choice of platform, 
-in your choice of language, and on your choice of backend database.
+is described at :ref:`high-level-api`. To actually use U1DB you'll need an
+implementation; a version of U1DB made available on your choice of platform, in
+your choice of language, and on your choice of backend database.
 
-If you're interested in using U1DB in an application, look at 
-:ref:`high-level-api` first, and then choose one of the :ref:`implementations` 
-and read about exactly how the U1DB API is made available in that 
+If you're interested in using U1DB in an application, look at
+:ref:`high-level-api` first, and then choose one of the :ref:`implementations`
+and read about exactly how the U1DB API is made available in that
 implementation. Get going quickly with the :ref:`quickstart`.
 
-If you're interested in hacking on U1DB itself, read about the 
+If you're interested in hacking on U1DB itself, read about the
 :ref:`rules for U1DB <philosophy>` and :ref:`reference-implementation`.
 
 .. toctree::
    :maxdepth: 1
-   
+
    quickstart
    high-level-api
    reference-implementation
 
=== modified file 'html-docs/philosophy.rst'
--- html-docs/philosophy.rst	2011-12-21 13:11:20 +0000
+++ html-docs/philosophy.rst	2012-07-16 17:22:17 +0000
@@ -5,52 +5,51 @@
 
 Some notes on what u1db is for, how it works, and how it should be used.
 
-U1DB is a cross-platform, cross-device, syncable database API. In order to be this
-way, there's a philosophy behind it. Key to this philosophy is that u1db can
-be implemented in many languages and on top of many back ends: this means that
-the API needs to be, as much as possible, portable between very different
+U1DB is a cross-platform, cross-device, syncable database API. In order to be
+this way, there's a philosophy behind it. Key to this philosophy is that u1db
+can be implemented in many languages and on top of many back ends: this means
+that the API needs to be, as much as possible, portable between very different
 languages. Each implementation should implement :ref:`high-level-api` in the
-way appropriate to that language (Python uses tuples all over the place,
-Vala/C use a Document object for most things, and so on), but it's important
-that an implementation not diverge from the API. Because u1db is a syncable
-database, it's quite likely that an app developer using it will be building their
-app on multiple platforms at once. Knowledge that an app developer has from
-having built a u1db app on one platform should be transferable to another
-platform. This means that querying is the same across platforms; storing and
-retrieving docs is the same across platforms; syncing is the same across
-platforms. U1DB is also syncable to Ubuntu One, which is a very large 
-server installation; the API needs to be suitable to run at scales from a
-mobile phone up to a large server installation.
-
-For similar reasons, u1db is *schemaless*. Documents stored in u1db do not
-need to contain any pre-defined list of fields; this way, an application can
-store whatever it wants, however it wants; development is faster and changing
-how data is stored is simpler.
-
-What this means is that u1db is for user-specific data. A desktop app or a 
-mobile app storing data for a user is the ideal use case. A web app which 
-holds data for many users should be using and syncing a separate u1db for
-each user. U1DB isn't designed to be the backend database for the next 
-Facebook.
+way appropriate to that language (Python uses tuples all over the place, Vala/C
+use a Document object for most things, and so on), but it's important that an
+implementation not diverge from the API. Because u1db is a syncable database,
+it's quite likely that an app developer using it will be building their app on
+multiple platforms at once. Knowledge that an app developer has from having
+built a u1db app on one platform should be transferable to another platform.
+This means that querying is the same across platforms; storing and retrieving
+docs is the same across platforms; syncing is the same across platforms. U1DB
+is also syncable to Ubuntu One, which is a very large server installation; the
+API needs to be suitable to run at scales from a mobile phone up to a large
+server installation.
+
+For similar reasons, u1db is *schemaless*. Documents stored in u1db do not need
+to contain any pre-defined list of fields; this way, an application can store
+whatever it wants, however it wants; development is faster and changing how
+data is stored is simpler.
+
+What this means is that u1db is for user-specific data. A desktop app or
+a mobile app storing data for a user is the ideal use case. A web app which
+holds data for many users should be using and syncing a separate u1db for each
+user. U1DB isn't designed to be the backend database for the next Facebook.
 
 To this end, there are a few guidelines. Primarily, the guideline the u1db team
 used for the largest u1db is somewhere around 10,000 documents. It's important
 to note that this is not an *enforced* limit; an app dev can store a zillion
 documents in a u1db if they want. However, the implementations are allowed to
 assume that there aren't a zillion documents; in particular, suggestions for
-API changes which make things more annoying for a 1,000 documents use-case
-in order to help with a zillion documents are not likely to be adopted.
+API changes which make things more annoying for a 1,000 documents use-case in
+order to help with a zillion documents are not likely to be adopted.
 
 Similarly, suggested changes to the high-level API which are very difficult to
 implement in static languages like C are also unlikely to be adopted, in order
 to maintain the goal of knowledge on one platform transferring to another.
 
-U1DB is designed so that implementations are built by creating small layers on 
+U1DB is designed so that implementations are built by creating small layers on
 top of existing storage solutions. It isn't a database in itself; it's an API
 layer which sits on top of a native database to that platform. This means that
-the platform provides the actual database functionality and u1db takes advantage
-of it. SQLite where available, localStorage for JavaScript in the web browser;
-u1db should work with the platform, not be ported to it.
+the platform provides the actual database functionality and u1db takes
+advantage of it. SQLite where available, localStorage for JavaScript in the web
+browser; u1db should work with the platform, not be ported to it.
 
 It should be easy to sync a u1db from place to place. There is a direct server
 HTTP API, which allows an app to work with a u1db on the server without any
 
=== modified file 'html-docs/quickstart.rst'
--- html-docs/quickstart.rst	2011-12-21 11:09:04 +0000
+++ html-docs/quickstart.rst	2012-07-16 17:22:17 +0000
@@ -18,8 +18,8 @@
 Use from source control
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-u1db is `maintained in bazaar in Launchpad <http://launchpad.net/u1db/>`_. To fetch the latest version,
-`bzr branch lp:u1db`.
+u1db is `maintained in bazaar in Launchpad <http://launchpad.net/u1db/>`_. To
+fetch the latest version, `bzr branch lp:u1db`.
 
 Starting u1db
 -------------
@@ -28,29 +28,29 @@
 
     >>> import u1db, json, tempfile
     >>> db = u1db.open(":memory:", create=True)
-    
+
     >>> content = json.dumps({"name": "Alan Hansen"}) # create a document
     >>> doc = db.create_doc(content)
-    >>> print doc.content
-    {"name": "Alan Hansen"}
+    >>> doc.content
+    {'name': 'Alan Hansen'}
     >>> doc.content = json.dumps({"name": "Alan Hansen", "position": "defence"}) # update the document's content
     >>> rev = db.put_doc(doc)
-    
+
     >>> content = json.dumps({"name": "John Barnes", "position": "forward"}) # create more documents
     >>> doc2 = db.create_doc(content)
     >>> content = json.dumps({"name": "Ian Rush", "position": "forward"})
     >>> doc2 = db.create_doc(content)
-    
-    >>> db.create_index("by-position", ("position",)) # create an index by passing an index expression
-    
-    >>> results = db.get_from_index("by-position", [("forward",)]) # query that index by passing a list of tuples of queries
+
+    >>> db.create_index("by-position", "position") # create an index by passing a field name
+
+    >>> results = db.get_from_index("by-position", "forward") # query that index by passing a value
     >>> len(results)
     2
-    >>> data = [json.loads(result.content) for result in results]
+    >>> data = [result.content for result in results]
     >>> names = [item["name"] for item in data]
     >>> sorted(names)
     [u'Ian Rush', u'John Barnes']
-    
+
 Running a server
 ----------------
 
@@ -80,7 +80,7 @@
     >>> import u1db
     >>> db = u1db.open(":memory:", create=True)
     >>> generation = db.sync("http://127.0.0.1:43632/example.u1db")
-    
+
 or from the command line
 
 .. code-block:: bash
@@ -88,4 +88,4 @@
     ~/u1db/trunk$ ./u1db-client init-db someother.u1db
     ~/u1db/trunk$ ./u1db-client sync someother.u1db http://127.0.0.1:43632/example.u1db
 
-    
+
 
=== modified file 'html-docs/reference-implementation.rst'
--- html-docs/reference-implementation.rst	2011-12-21 11:09:04 +0000
+++ html-docs/reference-implementation.rst	2012-07-16 17:22:17 +0000
@@ -4,10 +4,10 @@
 #############################
 
 The u1db reference implementation is written in Python, with a SQLite back end.
-It can be used as a real working implementation by Python code. It is also used 
-to document and test how u1db should work; it has a comprehensive test suite. 
-Implementation authors should port the u1db reference test suite in order to 
-test that their implementation is correct; in particular, sync conformance is 
+It can be used as a real working implementation by Python code. It is also used
+to document and test how u1db should work; it has a comprehensive test suite.
+Implementation authors should port the u1db reference test suite in order to
+test that their implementation is correct; in particular, sync conformance is
 defined as being able to sync with the reference implementation.
 
 Fetch with ``bzr branch lp:u1db`` or from `Launchpad <http://launchpad.net/u1db>`_.
 
=== modified file 'u1db/__init__.py'
--- u1db/__init__.py	2012-07-12 17:21:15 +0000
+++ u1db/__init__.py	2012-07-16 17:22:17 +0000
@@ -60,8 +60,9 @@
         returned as documents by the database.
 
         :param factory: A function that returns an object which at minimum must
-        satisfy the same interface as does the class DocumentBase. Subclassing
-        that class is the easiest way to create such a function.
+            satisfy the same interface as does the class DocumentBase.
+            Subclassing that class is the easiest way to create such
+            a function.
         """
         raise NotImplementedError(self.set_document_factory)
 
@@ -169,11 +170,11 @@
         and the index generated.
 
         :name: A unique name which can be used as a key prefix
-        :index_expressions: index expressions defining the index
-            information. Examples:
-                "fieldname" to index alphabetically sorted on field.
-                "number(fieldname, width)", "lower(fieldname)",
-                "fieldname.subfieldname"
+        :index_expressions: index expressions defining the index information.
+            Examples:
+            "fieldname" to index alphabetically sorted on field.
+            "number(fieldname, width)", "lower(fieldname)",
+            "fieldname.subfieldname"
         """
         raise NotImplementedError(self.create_index)
 
@@ -243,7 +244,7 @@
         raise NotImplementedError(self.get_index_keys)
 
     def get_doc_conflicts(self, doc_id):
-        """Get the list of conflict texts for the given document.
+        """Get the list of conflicts for the given document.
 
         The order of the conflicts is such that the first entry is the value
         that would be returned by "get_doc".