Documentation Pass

Reported-by: Matt Klinger

Author: rescrv

Diff for: doc/async-ops.tex

@@ -1,12 +1,12 @@
 \chapter{Asynchronous Operations}
 \label{chap:async-ops}
 
-Thus far, all HyperDex operations we've seen are {\em synchronous}, that is, the
-application calls the HyperDex operation and blocks until the operation is
-complete.  HyperDex is very fast, but even so, clients may spend a non-trivial
+Thus far, all HyperDex operations we've seen are {\em synchronous}.  That is,
+the application calls the HyperDex operation and blocks until the operation is
+complete.  HyperDex is very fast.  But even so, clients may spend a non-trivial
 amount of time waiting on HyperDex operations.  For each operation in HyperDex,
-there is an {\em asynchronous} variant that accomplishes the same task, but
-allows the client to perform other work while the operation completes.
+there is an {\em asynchronous} variant that accomplishes the same task, while
+allowing the client to perform other work during operation completion.
 
 In this chapter, we'll look at the asynchronous operations HyperDex supports,
 and see different ways to use them to increase concurrency in the system.
@@ -70,7 +70,7 @@ \section{Asynchronous Operations}
 \label{sec:async-ops:ops}
 
 Asynchronous operations permit applications to retrieve or modify multiple
-objects simultaneously and to perform local computation while doing the same.
+objects simultaneously, and to perform local computation while doing the same.
 In previous chapters, we submitted synchronous operations to the key-value
 store, where each client had just a single outstanding request, and waited
 patiently for that request to complete.  In high-throughput applications,
@@ -186,7 +186,8 @@ \section{Asynchronous Operations}
 
 Using the \code{loop()} method, it is possible to issue thousands of requests
 and then wait for each one in turn without having to serialize the round trips
-to the server.
+to the server.  Each call to loop returns a \code{Deferred} object represents
+one outstanding operation.
 
 \section{Potential Pitfalls}
 \label{sec:async-ops:pitfalls}

Diff for: doc/atomic-ops.tex

@@ -324,7 +324,7 @@ \section{A Comprehensive Walk}
 '->some string<-'
 \end{pythoncode}
 
-Lists provide atomic operations as well, to push new items on the left or the
+Atomic operations on lists allow the client to push new items on the left or
 right of the list:
 
 \begin{pythoncode}
@@ -449,7 +449,8 @@ \section{A Comprehensive Walk}
 \end{pythoncode}
 
 \subsection{Atomic Operations on Documents}
-Note that Hyperdex also supports atomic operations on documents. To do this, we first have to create a space that has a field of the type document.
+Note that Hyperdex also supports atomic operations on documents. To do this, we
+first have to create a space that has a field of the type document.
 
 \begin{pythoncode}
 >>> a.add_space('''
@@ -468,8 +469,11 @@ \subsection{Atomic Operations on Documents}
 True
 \end{pythoncode}
 
-We might now want to modify the information of this person without rewriting the whole document. For example, it might be Jane Doe's birthday and we want to increment the age.
-Fortunately, atomic operations also work on this kind of data. Hyperdex is able to add up two documents as long as the argument is a subset of the original data and only has numerical values.
+We might now want to modify this information of this person without rewriting
+the whole document. For example, it might be Jane Doe's birthday and we want to
+increment the age.  Fortunately, atomic operations also work on this kind of
+data.  HyperDex is able to increment integers within documents by providing the
+full path to the integer within the document.
 
 \begin{pythoncode}
 >>> c.atomic_add('people', 'jane', {'info.age' : 1})
@@ -514,7 +518,7 @@ \subsection{Atomic Operations on Documents}
 
 
 
-HyperDex's atomic operations are extensive and very expressive. And they are
+HyperDex's atomic operations are extensive and very expressive.  They are
 guaranteed to be applied in the same order on all replicas, so the state of the
 object you are operating on is guaranteed to be the same, regardless of
 failovers.

Diff for: doc/backups.tex

@@ -135,9 +135,8 @@ \section{Simple Backup Strategies}
 
 \section{Backup Efficiency}
 
-HyperDex's backups are extremely efficient, because they leverage the structure
-of the on-disk format to take snapshots quickly, which may then be copied in the
-background.
+HyperDex's backups are extremely efficient, because its architecture enables
+quick snapshots, which may then be copied in the background.
 
 HyperDex uses HyperLevelDB as its storage backend, which, in turn, constructs an
 LSM-tree on disk.  The majority of data stored within HyperLevelDB is stored
@@ -190,7 +189,7 @@ \section{Advanced Backup Techniques}
 passing to the \code{--data} parameter of HyperDex's daemon.
 
 In addition to the per-daemon state backups, the backup command above also
-creates a file in the curren directory called \code{my-backup.coordinator.bin}.
+creates a file in the current directory called \code{my-backup.coordinator.bin}.
 This file contains the coordinator's state, suitable for using to bootstrap a
 new coordinator cluster as shown above.
 
@@ -232,8 +231,8 @@ \section{Incremental Backups with Rsync}
 into place and not copied over the network.
 
 Assuming an existing backup exists in the directory
-\code{13036267341651542609-1},
-we can create an incremental backup in \code{13036267341651542609-2} by issuing:
+\code{13036267341651542609-1}, we can create an incremental backup in
+\code{13036267341651542609-2} by issuing:
 
 \begin{consolecode}
 % rsync -a --delete --link-dest=13036267341651542609-1 -- \

Diff for: doc/c/client.tex

@@ -84,7 +84,7 @@ \section{Hello World}
 transient problems with the cluster.  Until the operation's id is returned from
 loop, the operation is still outstanding and incomplete.
 
-The stored value is passed via \code{struct hyperdex\_client\_attribute} which
+The stored value is passed via \code{struct hyperdex\_client\_attribute}, which
 specifies both the value of the string "Hello World!" and that this value is, in
 fact, a string.  All HyperDex datatypes are passed to HyperDex as bytestrings
 via this interface.
@@ -433,10 +433,10 @@ \subsection{Bytestring Format}
 
 \paragraph{map(string, float) format}
 
-Maps from strings to ints are formed by encoding the individual elements, where
-keys are prefixed by an unsigned 4-byte little endian integer indicating their
-length.  The pairs of elements are stored in sorted order according to the first
-element of the pair (the map's key).  For example:
+Maps from strings to floats are formed by encoding the individual elements,
+where keys are prefixed by an unsigned 4-byte little endian integer indicating
+their length.  The pairs of elements are stored in sorted order according to the
+first element of the pair (the map's key).  For example:
 
 \begin{pythoncode}
 >>> encode_map_string_float({})
@@ -610,7 +610,7 @@ \subsection{Serialization API}
 \end{ccode}
 Encode \code{num} into memory allocated via \code{arena} and return
 the value via \code{value} and \code{value\_sz}.  This function will fail and
-return -1 if there is insufficient memory available for encoding the nubmer.
+return -1 if there is insufficient memory available for encoding the number.
 All pointers returned by this function remain valid until \code{arena} is
 destroyed.  The client should not attempt to free the returned copy.
 
@@ -771,7 +771,7 @@ \subsection{Serialization API}
 \end{ccode}
 Set the key of the next pair to be inserted into \code{map} to the
 integer specified by \code{num}.  This function will fail and return -1 if
-memory allocation fails, or the map does not nuse integers for keys.
+memory allocation fails, or the map does not use integers for keys.
 
 \begin{ccode}
 int hyperdex_ds_map_insert_val_int(struct hyperdex_ds_map* map,
@@ -872,7 +872,7 @@ \subsection{Deserialization API}
 \end{ccode}
 Return the next string element in the list.  This function will return
 1 if an element is returned, 0 if there are no elements to return, and -1 if the
-list of strings is malformed.  The falue stored in \code{*str} is a pointer into
+list of strings is malformed.  The value stored in \code{*str} is a pointer into
 the list of strings and should not be free'd by the application.
 
 \begin{ccode}
@@ -1038,7 +1038,7 @@ \subsection{Memory Management Utilties}
 \section{Attributes}
 \label{sec:api:c:client:attributes}
 
-In HyperDex, {\em attributes} specified named values that comprise an object.
+In HyperDex, {\em attributes} specify named values that comprise an object.
 For instance, in Chapter~\nameref{chap:quick-start}, the phonebook space has
 attributes ``username'', ``first'', ``last'', and ``phone''.  The C API
 represents such attributes using \code{struct hyperdex\_client\_attribute}.  The
@@ -1113,7 +1113,7 @@ \section{Predicates}
 };
 \end{ccode}
 
-Note that this struct closely resembes \code{struct
+Note that this struct closely resembles \code{struct
 hyperdex\_client\_attribute}, with the addition of a field named
 \code{predicate}.  This field is an enum with the following values:
 
@@ -1256,7 +1256,7 @@ \section{Error Handling}
 
 Local errors are always returned via the \code{enum
 hyperdex\_client\_returncode*} pointer passed at the time the application
-initated the operation.  These errors may either result from the application
+initiated the operation.  These errors may either result from the application
 returning a negative operation id, in which case the operation immediately
 completes, or from the result of a successful \code{hyperdex\_client\_loop}
 call.  In either case, the error has no impact on the result of any other

Diff for: doc/client/fragments/cond_put.tex

@@ -1,5 +1,5 @@
 Conditionally update an the object stored under \code{key} in \code{space}.
-Existing values will be overwitten with the values specified by \code{attrs}.
+Existing values will be overwritten with the values specified by \code{attrs}.
 Values not specified by \code{attrs} will remain unchanged.
 \input{\topdir/client/fragments/fail_if_not_found}
 

Diff for: doc/client/fragments/cond_put_or_create.tex

@@ -1,5 +1,5 @@
 Conditionally update an the object stored under \code{key} in \code{space}.
-Existing values will be overwitten with the values specified by \code{attrs}.
+Existing values will be overwritten with the values specified by \code{attrs}.
 Values not specified by \code{attrs} will remain unchanged.  If the object
 exists, this is equivalent to a \code{cond\_put}.  If the object does not exist,
 this is equivalent to a \code{put}

Diff for: doc/client/fragments/conditional.tex

@@ -5,4 +5,4 @@
 
 All checks are atomic with the write.  HyperDex guarantees that no other
 operation will come between validating the checks, and writing the new version
-of the object..
+of the object.

Diff for: doc/client/fragments/group_put.tex

@@ -1,5 +1,5 @@
 Update all objects stored in \code{space} that match \code{checks}.  Existing
-values will be overwitten with the values specified by \code{attrs}.  Values not
+values will be overwritten with the values specified by \code{attrs}.  Values not
 specified by \code{attrs} will remain unchanged.
 
 \input{\topdir/client/fragments/group_operation}

Diff for: doc/data-types.tex

@@ -161,7 +161,7 @@ \section{Floats}
 \section{Lists}
 \label{sec:data-types:lists}
 
-Let's add support for friend requests using HyperDex lists the basis of the
+Let's add support for friend requests using HyperDex lists as the basis of the
 feature.  For this we'll use the \code{pending\_requests} attribute in the
 \code{profiles} space.
 
@@ -240,9 +240,9 @@ \section{Maps}
 
 Lastly, our social networking system needs a means for allowing users to
 exchange messages.  Let's demonstrate how we can accomplish this with the
-\code{unread\_messages} attribute. In this contrived example, we're going to use
-an object attribute as a map (aka dictionary) to map from a user name to a
-string that contains the message from that user, as follows:
+\code{unread\_messages} attribute. In this contrived example, the
+\code{unread\_messages} attribute is a map of usernames to unread messages from
+that user.  For example:
 
 \begin{pythoncode}
 >>> c.map_add('profiles', 'jsmith1',
@@ -257,7 +257,7 @@ \section{Maps}
 
 HyperDex enables map contents to be modified in-place within the map.  For
 example, if Brian sent another message to John, we could separate the messages
-with "|" and just append the new message:
+with ``\code{|}'' and just append the new message:
 
 \begin{pythoncode}
 >>> c.map_string_append('profiles', 'jsmith1',
@@ -272,8 +272,7 @@ \section{Maps}
 operating on the values of the map.
 
 For the sake of illustrating maps involving integers, let's imagine that we will
-use a map to keep track of the plus-one's and like/dislike's on John's status
-updates. 
+use a map to keep track of the like/dislike's on John's status updates. 
 
 First, let's create some counters that will keep the net count of up and down
 votes corresponding to John's link posts, with ids "http://url1.com" and
@@ -287,7 +286,7 @@ \section{Maps}
 True
 \end{pythoncode}
 
-So John's posts start out with a counter set to 1, as shown above. 
+So, John's posts start out with a counter set to 1, as shown above. 
 
 Imagine that two other users, Jane and Elaine, upvote John's first link post, we
 would implement it like this:
@@ -340,7 +339,7 @@ \section{Timestamps}
 In this space, the key-space will be broken into one second intervals, and
 timestamps that fall within the same interval will be hashed to nearby to each
 other, while timestamps that map to different intervals will be hashed further
-apart in the key space.
+apart in the key space.  Each object is stored under the \code{when} attribute.
 
 The HyperDex timestamp type appears to our application as a normal Python
 \code{datetime.datetime} object, and will be converted to and from this type by

Diff for: doc/documents.tex

@@ -124,3 +124,5 @@ \section{Indexing Documents}
 This will instruct HyperDex to add the new index, and will index all existing
 data using the new index.  You can add and remove indices at any time as your
 documents change.
+
+HyperDex will automatically make use of the new index upon its creation.

Diff for: doc/installation.tex

@@ -1,14 +1,13 @@
 \chapter{Installing HyperDex}
 \label{chap:installation}
 
-HyperDex provides multiple installation methods that provide easy access to
-HyperDex in a variety of environments.  Those looking to play around with
-HyperDex and go through the tutorials may find it easiest to start with the
-quickstart Docker container.  For Linux users, the easiest and most convenient
-way to install HyperDex is to use pre-compiled binary packages.  Users of OS X
-have the option to install using Homebrew packages.  Finally, HyperDex is also
-distributed as a set of tarballs so that power users may install HyperDex in a
-custom manner on their platform of choice.
+HyperDex provides multiple installation methods for a variety of environments.
+Those looking to play around with HyperDex and go through the tutorials may find
+it easiest to start with the quickstart Docker container.  For Linux users, the
+easiest and most convenient way to install HyperDex is to use pre-compiled
+binary packages.  OS X users have the option to install using Homebrew
+packages.  Finally, HyperDex is also distributed as a set of tarballs so that
+power users may install HyperDex in a custom manner on their platform of choice.
 
 \section{Quick Installation with Docker}
 
@@ -50,8 +49,8 @@ \section{Quick Installation with Docker}
 \end{enumerate}
 
 With this quickstart cluster, both the coordinator and daemon logs will be
-displayed on stdout.  You can connect to the cluster at athe address and port
-listed, and can stop the cluster at any time using the command displayed on your
+displayed on stdout.  You can connect to the cluster at the address and port
+listed and can stop the cluster at any time using the command displayed on your
 console.  When you stop the cluster, the HyperDex cluster will be destroyed, and
 taken offline automatically.  To fully clean up any disk space in use by the
 cluster, run \code{docker rm b6ae7c60c275}, where b6ae7c60c275 is the ID of your
@@ -156,7 +155,7 @@ \section{Installing From Source}
 \subsubsection{Changing the Installation Directory}
 \label{sec:installation:source:prefix}
 
-By default HyperDex installs files in \texttt{/usr/local}.  If you'd like to
+By default, HyperDex installs files in \texttt{/usr/local}.  If you'd like to
 install HyperDex elsewhere, you can specify the installation prefix at configure
 time.  For example, to install HyperDex in \texttt{/opt/hyperdex}:
 
@@ -384,7 +383,7 @@ \section{Upgrading to 1.4}
 backup.  This will upgrade the coordinator to 1.4, and the daemons will work
 with the old data directory.
 
-Alternatively, take a backup, and restart the coordinator from the backed-up
+Alternatively take a backup, and restart the coordinator from the backed-up
 coordinator state on the same address.  Then do a rolling restart of the
 daemons.
 
@@ -400,7 +399,7 @@ \section{Upgrading to 1.3}
 backup.  This will upgrade the coordinator to 1.3, and the daemons will work
 with the old data directory.
 
-Alternatively, take a backup, and restart the coordinator from the backed-up
+Alternatively take a backup, and restart the coordinator from the backed-up
 coordinator state on the same address.  Then do a rolling restart of the
 daemons.
 

Diff for: doc/introduction.tex

@@ -12,8 +12,8 @@ \section{Why HyperDex?}
 
 \begin{description}
 \item[Performance:]  HyperDex achieves lower latency and higher throughput than
-many other key-value stores.  Deploy fewer machines to support your application,
-and save on operational costs.
+many other key-value stores.  Support your application with fewer machines and
+save on operational costs.
 
 \item[Consistency:]  HyperDex provides strongly-consistent reads, writes, and
 atomic operations, making strong guarantees to your application.  Other
@@ -81,10 +81,10 @@ \section{Help and Support}
 \label{sec:introduction:support}
 
 If you run into trouble while working with HyperDex, don't panic!  The HyperDex
-team have put together many support avenues to assist you with HyperDex.  Many
-of the available resources are freely available online.  When you need more
-support than that, the HyperDex team is on standby with commercial support
-options that ensure that you're never left in the dark.
+team have put together many support avenues to assist you.  Many of the
+resources are available online for free.  When you need more support than that,
+the HyperDex team is on standby with commercial support options that ensure that
+you're never left in the dark.
 
 \subsection{Online and Free Resources}
 \label{sec:introduction:support:free}
@@ -97,11 +97,11 @@ \subsection{Online and Free Resources}
     and assistance.  It serves as the canonical documentation of HyperDex and
     should be your first stop with any questions or problems.
 \item \href{https://groups.google.com/group/hyperdex-discuss}{HyperDex Mailing List}:
-    This open mailing list is most users' first resource solving problems.
-    Messages to the list are archived which makes it easy to search for
-    solutions to your problem.  If you don't find a solution in the archives,
-    start a new thread with your question and the HyperDex developers will try
-    to help answer your questions.
+    This open mailing list is the first resource most users turn to when solving
+    problems.  Messages to the list are archived which makes it easy to search
+    for solutions to your problem.  If you don't find a solution in the
+    archives, start a new thread with your question and the HyperDex developers
+    will try to help answer your questions.
 \item \href{http://webchat.freenode.net/?channels=hyperdex\&uio=d4}{HyperDex IRC Channel}:
     The \texttt{\#hyperdex} IRC channel on Freenode is a great place to ask
     questions and interact with the HyperDex developers in real-time.
@@ -123,7 +123,7 @@ \subsection{Online and Free Resources}
 \subsection{Commercial Support}
 \label{sec:introduction:support:commercial}
 
-The HyperDex team provides commercial support for HyperDex, which includes
-around-the-clock email support and consulting services.  If you're in need of
-support, you can contact the HyperDex developers directly at {\em support}@{\em
-hyperdex.org}.
+Should you require more support, the HyperDex team is always on standby with
+commercial support options to ensure you're never left in the dark.  If you're
+in need of support, you can contact the HyperDex developers directly at {\em
+support}@{\em hyperdex.org}.