Fix typos and simplify & clarify some phrases in the documentation.

Documentation/Books/Users/Aql/Advanced.mdpp

@@ -27,7 +27,7 @@ explicitly mark their start and end points:
 	  RETURN r.user.rating
       ) }
 
-Subqueries might also include other subqueries themselves.
+Subqueries may also include other subqueries themselves.
 
 !SUBSECTION Variable expansion
 

Documentation/Books/Users/Aql/Basics.mdpp

@@ -9,24 +9,23 @@ parser will return an error if it detects more than one data-modification
 operation in the same query or if it cannot figure out if the query is meant
 to be a data retrieval or a modification operation.
 
-In SQL, the semicolon can be used to indicate the end of a query and to separate
+AQL only allows *one* query in a single query string; Thus semicolons to
-multiple queries. This is not supported in AQL. Using a semicolon to terminate
+indicate the end of one query and separate multiple queries (as seen in SQL) are
-a query string is not allowed in AQL. Specifying more than one AQL query in
+not allowed.
-a single query string is disallowed, too. 
 
 !SUBSECTION Whitespace 
 
-Whitespace can be used in the query text to increase its readability.  However,
+Whitespaces (blanks, carriage returns, line feeds, and tab stops) can be used
-for the parser any whitespace (spaces, carriage returns, line feeds, and tab
+in the query text to increase its readability. Tokens have to be separated by
-stops) does not have any special meaning except that it separates individual
+any number of whitespaces. Whitespace within strings or names must be enclosed
-tokens in the query. Whitespace within strings or names must be enclosed in
+in quotes in order to be preserved.
-quotes in order to be preserved.
 
 !SUBSECTION Comments 
 
 Comments can be embedded at any position in a query. The text contained in the
-comment is ignored by the AQL parser. Comments cannot be nested, meaning
+comment is ignored by the AQL parser.
-the comment text may not contain another comment.
+Multi-line Comments cannot be nested. -> Subsequent comment starts within
+comments are ignored, ends will end the comment.
 
 AQL supports two types of comments:
 - Single line comments: These start with a double forward slash and end at
@@ -62,7 +61,7 @@ Each of the above operations can be initiated in a query by using a keyword of
 the same name. An AQL query can (and typically does) consist of multiple of the
 above operations.
 
-An example AQL query might look like this:
+An example AQL query may look like this:
 
     FOR u IN users
       FILTER u.type == "newbie" && u.active == true
@@ -108,7 +107,7 @@ The current list of keywords is:
 - TRUE
 - FALSE
 
-Additional keywords might be added in future versions of ArangoDB. 
+Additional keywords may be added in future versions of ArangoDB. 
 
 !SUBSECTION Names
 
@@ -140,7 +139,7 @@ conventions.
 
 When referring to attributes of documents from a collection, the fully qualified
 attribute name must be used. This is because multiple collections with ambiguous
-attribute names might be used in a query.  To avoid any ambiguity, it is not
+attribute names may be used in a query.  To avoid any ambiguity, it is not
 allowed to refer to an unqualified attribute name.
 
 Please refer to the [Naming Conventions in ArangoDB](../NamingConventions/AttributeNames.md) for more information about the
@@ -313,7 +312,7 @@ AQL supports the usage of bind parameters, thus allowing to separate the query
 text from literal values used in the query. It is good practice to separate the
 query text from the literal values because this will prevent (malicious)
 injection of keywords and other collection names into an existing query. This
-injection would be dangerous because it might change the meaning of an existing
+injection would be dangerous because it may change the meaning of an existing
 query.
 
 Using bind parameters, the meaning of an existing query cannot be changed. Bind
@@ -491,7 +490,7 @@ from *users* that do not have the *name* attribute at all:
       RETURN u
 
 Furthermore, *null* is less than any other value (excluding *null* itself). That
-means documents with non-existing attributes might be included in the result
+means documents with non-existing attributes may be included in the result
 when comparing attribute values with the less than or less equal operators.
 
 For example, the following query will return all documents from the collection

Documentation/Books/Users/Aql/DataModification.mdpp

@@ -1,7 +1,6 @@
 !CHAPTER Data modification queries
 
-Up to including version 2.1, AQL supported data retrieval operations only.
+As of ArangoDB version 2.2, AQL supports the following
-Starting with ArangoDB version 2.2, AQL also supports the following 
 data-modification operations:
 
 - INSERT: insert new documents into a collection
@@ -18,8 +17,8 @@ iterate over a given list of documents. They can optionally be combined with
       UPDATE u WITH { status: 'inactive' } IN users
 
 Though there is no need to combine a data-modification query with other
-AQL operations such a *FOR* and *FILTER*. For example, the following 
+AQL operations such as *FOR* and *FILTER*. For example, the following 
-stripped-down update query will work, too. It will update one document
+stripped-down *update* query will work, too. It will *update* one document
 (with key *foo*) in collection *users*:
 
     UPDATE "foo" WITH { status: 'inactive' } IN users
@@ -29,20 +28,20 @@ collection per query. That means a data-modification query cannot modify
 data in multiple collections with a single query, though it is possible
 to read from one collection and modify data in another with one query.
 
-For example, to copy the contents of collection "users" into collection
+For example, to copy the contents of the collection "users" into the collection
 "backup":
 
     FOR u IN users
       INSERT u IN backup
 
-To remove documents in collection "backup" that have the same key as some
+To remove documents in the collection "backup" that have the same key as some
 matching documents in collection "users":
 
     FOR u IN users
       FILTER u.status == 'inactive'
       REMOVE u._key IN backup
 
-The name of the modified collection ("backup" in th above cases) must be 
+The name of the modified collection ("backup" in the above cases) must be 
 known to the AQL executor at query-compile time and cannot change at 
 runtime. Using a bind parameter to specify the collection name is allowed.
   
@@ -51,7 +50,7 @@ If a data-modification operation fails, it will be rolled back automatically
 as if it never happened.
 
 In a cluster, AQL data-modification queries are not executed transactionally.
-Additionally, update, replace and remove AQL queries currently require the 
+Additionally, *update*, *replace* and *remove* AQL queries currently require the 
 *_key* attribute to be specified for all documents that should be modified or 
-removed, even if a shard key attribute other than *_key* was chosen for the
+removed, even if a shared key attribute other than *_key* was chosen for the
-collection. This restriction might be lifted in a future release of ArangoDB.
+collection. This restriction may be overcome in a future release of ArangoDB.

Documentation/Books/Users/Aql/Functions.mdpp

@@ -417,7 +417,7 @@ AQL supports the following functions to operate on list values:
 
 - *UNIQUE(list)*: Returns all unique elements in *list*. To determine
   uniqueness, the function will use the comparison order.
-  Calling this function might return the unique elements in any order.
+  Calling this function may return the unique elements in any order.
 
 - *UNION(list1, list2, ...)*: Returns the union of all lists specified.
   The function expects at least two list values as its arguments. The result is a list
@@ -714,7 +714,7 @@ Please use [Graph operations](../Aql/GraphOperations.md) instead.
   The result of the function is a list of paths. Paths of length 0 will also be returned. Each 
   path is a document consisting of the following attributes:
   - *vertices*: list of vertices visited along the path
-  - *edges*: list of edges visited along the path (might be empty)
+  - *edges*: list of edges visited along the path (may be empty)
   - *source*: start vertex of path
   - *destination*: destination vertex of path
 
@@ -892,8 +892,8 @@ Please use [Graph operations](../Aql/GraphOperations.md) instead.
 When using one of AQL's graph functions please make sure that the graph does not contain cycles,
 or that you at least specify some maximum depth or uniqueness criteria for a traversal. 
 
-If no bounds are set, a traversal might run into an endless loop in a cyclic graph or sub-graph,
+If no bounds are set, a traversal may run into an endless loop in a cyclic graph or sub-graph,
-and even in a non-cyclic graph, traversing far into the graph might consume a lot of processing
+and even in a non-cyclic graph, traversing far into the graph may consume a lot of processing
 time and memory for the result set.
 
 **Warning Deprecated**

Documentation/Books/Users/Aql/GraphOperations.mdpp

@@ -20,7 +20,7 @@ Hence the complexity of these functions depends of the chosen algorithm for this
 with *n* being the amount of vertices in the graph. For
 [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm) it would be **O(x\*y\*n^2)** with *n* being
 the amount of vertices in the graph, *x* the amount of start vertices and *y* the amount of
-target vertices. Hence a suggestion might be to use Dijkstra when x\*y < n and the functions supports choosing your algorithm.
+target vertices. Hence a suggestion may be to use Dijkstra when x\*y < n and the functions supports choosing your algorithm.
 
 !SUBSECTION Edges and Vertices related functions
 

Documentation/Books/Users/Aql/Invoke.mdpp

@@ -123,6 +123,6 @@ number of results and allow the server to apply optimizations.
 
 Please note that at the moment the server will always create the full result set for each query so 
 specifying or omitting the *count* attribute currently does not have any impact on query execution.
-This might change in the future. Future versions of ArangoDB might create result sets incrementally 
+This may change in the future. Future versions of ArangoDB may create result sets incrementally 
-on the server-side and might be able to apply optimizations if a result set is not fully fetched by 
+on the server-side and may be able to apply optimizations if a result set is not fully fetched by 
 a client.

Documentation/Books/Users/Aql/Operations.mdpp

@@ -106,8 +106,8 @@ FOR u IN users
 
 In the above example, all list elements from *users* will be included that have
 an attribute *active* with value *true* and that have an attribute *age* with a
-value less than *39*. All other elements from *users* will be skipped and not be
+value less than *39* (including *null* ones). All other elements from *users* 
-included the result produced by *RETURN*.
+will be skipped and not be included the result produced by *RETURN*.
 
 It is allowed to specify multiple *FILTER* statements in a query, and even in
 the same block. If multiple *FILTER* statements are used, their results will be
@@ -305,7 +305,7 @@ FOR u IN users
   REMOVE { _key: u._key } IN backup
 ```
 
-*options* can be used to suppress query errors that might occur when trying to
+*options* can be used to suppress query errors that may occur when trying to
 remove non-existing documents. For example, the following query will fail if one
 of the to-be-deleted documents does not exist:
 
@@ -322,7 +322,7 @@ FOR i IN 1..1000
   REMOVE { _key: CONCAT('test', TO_STRING(i)) } IN users OPTIONS { ignoreErrors: true }
 ```
 
-To make sure data are durable when a query returns, there is the *waitForSync* 
+To make sure data has been written to disk when a query returns, there is the *waitForSync* 
 query option:
 
 ```
@@ -394,7 +394,7 @@ FOR u IN users
   UPDATE u WITH { status: 'inactive' } IN backup
 ```
 
-*options* can be used to suppress query errors that might occur when trying to
+*options* can be used to suppress query errors that may occur when trying to
 update non-existing documents or violating unique key constraints:
 
 ```
@@ -497,7 +497,7 @@ FOR u IN users
   REPLACE u WITH { status: 'inactive', name: u.name } IN backup
 ```
 
-*options* can be used to suppress query errors that might occur when trying to
+*options* can be used to suppress query errors that may occur when trying to
 replace non-existing documents or when violating unique key constraints:
 
 ```
@@ -552,7 +552,7 @@ FOR u IN users
     INSERT { _from: u._id, _to: p._id } IN recommendations
 ```
 
-*options* can be used to suppress query errors that might occur when violating unique
+*options* can be used to suppress query errors that may occur when violating unique
 key constraints:
 
 ```

Documentation/Books/Users/Aql/Operators.mdpp

@@ -125,7 +125,7 @@ will produce the following result:
 
 !SUBSUBSECTION Operator precedence
 
-The operator precedence in AQL is as follows (lowest precedence first):
+The operator precedence in AQL is similar as in other familliar languages (lowest precedence first):
 
 - *? :* ternary operator
 - *||* logical or

Documentation/Books/Users/Aql/QueryResults.mdpp

@@ -54,9 +54,9 @@ will be opened. If any of the referenced collections is not present, query
 execution will again be aborted and an appropriate error message will be
 returned.
 
-Under some circumstances, executing a query might also produce run-time errors 
+Under some circumstances, executing a query may also produce run-time errors 
 that cannot be predicted from inspecting the query text alone. This is because
-queries might use data from collections that might also be inhomogeneous.  Some
+queries may use data from collections that may also be inhomogeneous.  Some
 examples that will cause run-time errors are:
 
 - Division by zero: Will be triggered when an attempt is made to use the value

Documentation/Books/Users/Aql/README.mdpp

@@ -14,7 +14,7 @@ AQL is mainly a declarative language, meaning that in a query it is expressed
 what result should be achieved and not how. AQL aims to be human- readable and
 therefore uses keywords from the English language. Another design goal of AQL
 was client independency, meaning that the language and syntax are the same for
-all clients, no matter what programming language the clients might use.  Further
+all clients, no matter what programming language the clients may use.  Further
 design goals of AQL were the support of complex query patterns and the different
 data models ArangoDB offers.
 

Documentation/Books/Users/AqlExamples/DataModificationQueries.mdpp

@@ -62,9 +62,10 @@ FOR u IN users
 ``` 
 
 To completely replace existing documents, use the *REPLACE* operation.
-The following query replaces all documents in collection backup with the documents
+The following query replaces all documents in the collection backup with
-found in collection users. Only those documents will be replaced that are present
+the documents found in collection users. Documents common to both
-in both collections. Documents are compared using their *_key* attributes:
+collections will be replaced. All other documents will remain unchanged.
+Documents are compared using their *_key* attributes:
 
 ```js
 FOR u IN users
@@ -82,8 +83,7 @@ FOR u IN users
 ``` 
 
 !SUBSECTION Removing documents
-
+Deleting documents can be achieved with the *REMOVE* operation.
-Removing documents can be achieved with the *REMOVE* operation.
 To remove all users within a certain age range, we can use the following query:
 
 ```js

Documentation/Books/Users/AqlExtending/Conventions.mdpp

@@ -24,8 +24,8 @@ User functions can take any number of input arguments and should
 provide one result. They should be kept purely functional and thus free of
 side effects and state. 
 
-Especially it is unsupported to modify any global variables, or to change 
+Modification of global variables is unsupported, as is changing
-data of a collection from inside an AQL user function. 
+the data of a collection from inside an AQL user function. 
 
 User function code is late-bound, and may thus not rely on any variables
 that existed at the time of declaration. If user function code requires

Documentation/Books/Users/AqlExtending/README.mdpp

@@ -1,7 +1,7 @@
 !CHAPTER Extending AQL with User Functions
 
 AQL comes with a built-in set of functions, but it is no
-full-feature programming language.
+full-featured programming language.
 
 To add missing functionality or to simplify queries, users
 may add own functions to AQL. These functions can be written

Documentation/Books/Users/NamingConventions/AttributeNames.mdpp

@@ -4,10 +4,15 @@ Users can pick attribute names for document attributes as desired, provided the
 following attribute naming constraints are not violated:
 - Attribute names starting with an underscore are considered to be system
   attributes for ArangoDB's internal use. Such attribute names are already used
-  by ArangoDB for special purposes, e.g. *_id* is used to contain a document's
+  by ArangoDB for special purposes:
-  handle, *_key* is used to contain a document's user-defined key, and *_rev* is
+  - *_id* is used to contain a document's handle
-  used to contain the document's revision number. In edge collections, the
+  - *_key* is used to contain a document's user-defined key
-  *_from* and *_to* attributes are used to reference other documents.
+  - *_rev* is used to contain the document's revision number
+  - In edge collections, the
+    - *_from*
+    - *_to*
+
+    attributes are used to reference other documents.
 
   More system attributes may be added in the future without further notice so
   end users should not use attribute names starting with an underscore for their
@@ -39,7 +44,7 @@ following attribute naming constraints are not violated:
   are removed from the document when saving it. 
 
   When the document is later requested, it will be returned without these 
-  attributes. For example, if this document is saved
+  attributes. For example, if this document is saved:
 
       { "a" : 1, "" : 2, "_test" : 3, "b": 4 }