Documentation improvements

Documentation/Books/AQL/Examples/README.mdpp

@@ -36,76 +36,76 @@ for brevity as well.
 Some of the following example queries are executed on a collection *users*
 with the following initial data:
 
-```js
+```json
 [ 
-  { "id" : 100, "name" : "John", "age" : 37, "active" : true, "gender" : "m" },
+  { "id": 100, "name": "John", "age": 37, "active": true, "gender": "m" },
-  { "id" : 101, "name" : "Fred", "age" : 36, "active" : true, "gender" : "m" },
+  { "id": 101, "name": "Fred", "age": 36, "active": true, "gender": "m" },
-  { "id" : 102, "name" : "Jacob", "age" : 35, "active" : false, "gender" : "m" },
+  { "id": 102, "name": "Jacob", "age": 35, "active": false, "gender": "m" },
-  { "id" : 103, "name" : "Ethan", "age" : 34, "active" : false, "gender" : "m" },
+  { "id": 103, "name": "Ethan", "age": 34, "active": false, "gender": "m" },
-  { "id" : 104, "name" : "Michael", "age" : 33, "active" : true, "gender" : "m" },
+  { "id": 104, "name": "Michael", "age": 33, "active": true, "gender": "m" },
-  { "id" : 105, "name" : "Alexander", "age" : 32, "active" : true, "gender" : "m" },
+  { "id": 105, "name": "Alexander", "age": 32, "active": true, "gender": "m" },
-  { "id" : 106, "name" : "Daniel", "age" : 31, "active" : true, "gender" : "m" },
+  { "id": 106, "name": "Daniel", "age": 31, "active": true, "gender": "m" },
-  { "id" : 107, "name" : "Anthony", "age" : 30, "active" : true, "gender" : "m" },
+  { "id": 107, "name": "Anthony", "age": 30, "active": true, "gender": "m" },
-  { "id" : 108, "name" : "Jim", "age" : 29, "active" : true, "gender" : "m" },
+  { "id": 108, "name": "Jim", "age": 29, "active": true, "gender": "m" },
-  { "id" : 109, "name" : "Diego", "age" : 28, "active" : true, "gender" : "m" },
+  { "id": 109, "name": "Diego", "age": 28, "active": true, "gender": "m" },
-  { "id" : 200, "name" : "Sophia", "age" : 37, "active" : true, "gender" : "f" },
+  { "id": 200, "name": "Sophia", "age": 37, "active": true, "gender": "f" },
-  { "id" : 201, "name" : "Emma", "age" : 36,  "active" : true, "gender" : "f" },
+  { "id": 201, "name": "Emma", "age": 36,  "active": true, "gender": "f" },
-  { "id" : 202, "name" : "Olivia", "age" : 35, "active" : false, "gender" : "f" },
+  { "id": 202, "name": "Olivia", "age": 35, "active": false, "gender": "f" },
-  { "id" : 203, "name" : "Madison", "age" : 34, "active" : true, "gender": "f" },
+  { "id": 203, "name": "Madison", "age": 34, "active": true, "gender": "f" },
-  { "id" : 204, "name" : "Chloe", "age" : 33, "active" : true, "gender" : "f" },
+  { "id": 204, "name": "Chloe", "age": 33, "active": true, "gender": "f" },
-  { "id" : 205, "name" : "Eva", "age" : 32, "active" : false, "gender" : "f" },
+  { "id": 205, "name": "Eva", "age": 32, "active": false, "gender": "f" },
-  { "id" : 206, "name" : "Abigail", "age" : 31, "active" : true, "gender" : "f" },
+  { "id": 206, "name": "Abigail", "age": 31, "active": true, "gender": "f" },
-  { "id" : 207, "name" : "Isabella", "age" : 30, "active" : true, "gender" : "f" },
+  { "id": 207, "name": "Isabella", "age": 30, "active": true, "gender": "f" },
-  { "id" : 208, "name" : "Mary", "age" : 29, "active" : true, "gender" : "f" },
+  { "id": 208, "name": "Mary", "age": 29, "active": true, "gender": "f" },
-  { "id" : 209, "name" : "Mariah", "age" : 28, "active" : true, "gender" : "f" }
+  { "id": 209, "name": "Mariah", "age": 28, "active": true, "gender": "f" }
 ]
 ```
 
 For some of the examples, we'll also use a collection *relations* to store
 relationships between users. The example data for *relations* are as follows:
 
-```js
+```json
 [
-  { "from" : 209, "to" : 205, "type" : "friend" },
+  { "from": 209, "to": 205, "type": "friend" },
-  { "from" : 206, "to" : 108, "type" : "friend" },
+  { "from": 206, "to": 108, "type": "friend" },
-  { "from" : 202, "to" : 204, "type" : "friend" },
+  { "from": 202, "to": 204, "type": "friend" },
-  { "from" : 200, "to" : 100, "type" : "friend" },
+  { "from": 200, "to": 100, "type": "friend" },
-  { "from" : 205, "to" : 101, "type" : "friend" },
+  { "from": 205, "to": 101, "type": "friend" },
-  { "from" : 209, "to" : 203, "type" : "friend" },
+  { "from": 209, "to": 203, "type": "friend" },
-  { "from" : 200, "to" : 203, "type" : "friend" },
+  { "from": 200, "to": 203, "type": "friend" },
-  { "from" : 100, "to" : 208, "type" : "friend" },
+  { "from": 100, "to": 208, "type": "friend" },
-  { "from" : 101, "to" : 209, "type" : "friend" },
+  { "from": 101, "to": 209, "type": "friend" },
-  { "from" : 206, "to" : 102, "type" : "friend" },
+  { "from": 206, "to": 102, "type": "friend" },
-  { "from" : 104, "to" : 100, "type" : "friend" },
+  { "from": 104, "to": 100, "type": "friend" },
-  { "from" : 104, "to" : 108, "type" : "friend" },
+  { "from": 104, "to": 108, "type": "friend" },
-  { "from" : 108, "to" : 209, "type" : "friend" },
+  { "from": 108, "to": 209, "type": "friend" },
-  { "from" : 206, "to" : 106, "type" : "friend" },
+  { "from": 206, "to": 106, "type": "friend" },
-  { "from" : 204, "to" : 105, "type" : "friend" },
+  { "from": 204, "to": 105, "type": "friend" },
-  { "from" : 208, "to" : 207, "type" : "friend" },
+  { "from": 208, "to": 207, "type": "friend" },
-  { "from" : 102, "to" : 108, "type" : "friend" },
+  { "from": 102, "to": 108, "type": "friend" },
-  { "from" : 207, "to" : 203, "type" : "friend" },
+  { "from": 207, "to": 203, "type": "friend" },
-  { "from" : 203, "to" : 106, "type" : "friend" },
+  { "from": 203, "to": 106, "type": "friend" },
-  { "from" : 202, "to" : 108, "type" : "friend" },
+  { "from": 202, "to": 108, "type": "friend" },
-  { "from" : 201, "to" : 203, "type" : "friend" },
+  { "from": 201, "to": 203, "type": "friend" },
-  { "from" : 105, "to" : 100, "type" : "friend" },
+  { "from": 105, "to": 100, "type": "friend" },
-  { "from" : 100, "to" : 109, "type" : "friend" },
+  { "from": 100, "to": 109, "type": "friend" },
-  { "from" : 207, "to" : 109, "type" : "friend" },
+  { "from": 207, "to": 109, "type": "friend" },
-  { "from" : 103, "to" : 203, "type" : "friend" },
+  { "from": 103, "to": 203, "type": "friend" },
-  { "from" : 208, "to" : 104, "type" : "friend" },
+  { "from": 208, "to": 104, "type": "friend" },
-  { "from" : 105, "to" : 104, "type" : "friend" },
+  { "from": 105, "to": 104, "type": "friend" },
-  { "from" : 103, "to" : 208, "type" : "friend" },
+  { "from": 103, "to": 208, "type": "friend" },
-  { "from" : 203, "to" : 107, "type" : "boyfriend" },
+  { "from": 203, "to": 107, "type": "boyfriend" },
-  { "from" : 107, "to" : 203, "type" : "girlfriend" },
+  { "from": 107, "to": 203, "type": "girlfriend" },
-  { "from" : 208, "to" : 109, "type" : "boyfriend" },
+  { "from": 208, "to": 109, "type": "boyfriend" },
-  { "from" : 109, "to" : 208, "type" : "girlfriend" },
+  { "from": 109, "to": 208, "type": "girlfriend" },
-  { "from" : 106, "to" : 205, "type" : "girlfriend" },
+  { "from": 106, "to": 205, "type": "girlfriend" },
-  { "from" : 205, "to" : 106, "type" : "boyfriend" },
+  { "from": 205, "to": 106, "type": "boyfriend" },
-  { "from" : 103, "to" : 209, "type" : "girlfriend" },
+  { "from": 103, "to": 209, "type": "girlfriend" },
-  { "from" : 209, "to" : 103, "type" : "boyfriend" },
+  { "from": 209, "to": 103, "type": "boyfriend" },
-  { "from" : 201, "to" : 102, "type" : "boyfriend" },
+  { "from": 201, "to": 102, "type": "boyfriend" },
-  { "from" : 102, "to" : 201, "type" : "girlfriend" },
+  { "from": 102, "to": 201, "type": "girlfriend" },
-  { "from" : 206, "to" : 100, "type" : "boyfriend" },
+  { "from": 206, "to": 100, "type": "boyfriend" },
-  { "from" : 100, "to" : 206, "type" : "girlfriend" }
+  { "from": 100, "to": 206, "type": "girlfriend" }
 ]
 ```
 

Documentation/Books/AQL/Functions/Array.mdpp

@@ -39,17 +39,6 @@ APPEND([ 1, 2, 3 ], [ 3, 4, 5, 2, 9 ], true)
 
 This is an alias for [LENGTH()](#length).
 
-!SUBSECTION OUTERSECTION()
-
-`OUTERSECTION(array1, array2, ... arrayN) → newArray`
-
-Return the values that occur only once across all arrays specified.
-
-- **arrays** (array, *repeatable*): an arbitrary number of arrays as multiple arguments
-  (at least 2)
-- returns **newArray** (array): a single array with only the elements that exist only once
-  across all provided arrays. The element order is random.
-
 !SUBSECTION FIRST()
 
 `FIRST(anyArray) → firstElement`
@@ -125,8 +114,8 @@ collection and the [character length](String.md#length) of a string.
 
 Return the difference of all arrays specified.
 
-- **arrays** (array, *repeatable*): an arbitrary of arrays as multiple arguments,
+- **arrays** (array, *repeatable*): an arbitrary number of arrays as multiple
-  at least two
+  arguments (at least 2)
 - returns **newArray** (array): an array of values that occur in the first array,
   but not in any of the subsequent arrays. The order of the result array is undefined
   and should not be relied on. Duplicates will be removed.
@@ -144,6 +133,28 @@ for positive positions, but does not support negative positions.
   If *position* is negative or beyond the upper bound of the array,
   then *null* will be returned.
 
+```js
+NTH( [ "foo", "bar", "baz" ], 2 )  // "baz"
+NTH( [ "foo", "bar", "baz" ], 3 )  // null
+NTH( [ "foo", "bar", "baz" ], -1 ) // null
+```
+
+!SUBSECTION OUTERSECTION()
+
+`OUTERSECTION(array1, array2, ... arrayN) → newArray`
+
+Return the values that occur only once across all arrays specified.
+
+- **arrays** (array, *repeatable*): an arbitrary number of arrays as multiple arguments
+  (at least 2)
+- returns **newArray** (array): a single array with only the elements that exist only once
+  across all provided arrays. The element order is random.
+
+```js
+OUTERSECTION( [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4, 5 ] )
+// [ 1, 5 ]
+```
+
 !SUBSECTION POP()
 
 `POP(anyArray) → newArray`
@@ -309,7 +320,7 @@ SLICE( [ 1, 2, 3, 4, 5 ], -3, 2 ) // [ 3, 4 ]
 Return the union of all arrays specified.
 
 - **arrays** (array, *repeatable*): an arbitrary number of arrays as multiple
-  arguments, at least 2
+  arguments (at least 2)
 - returns **newArray** (array): all array elements combined in a single array,
   in any order
 
@@ -342,7 +353,7 @@ UNIQUE(
 Return the union of distinct values of all arrays specified.
 
 - **arrays** (array, *repeatable*): an arbitrary number of arrays as multiple
-  arguments, at least 2
+  arguments (at least 2)
 - returns **newArray** (array): the elements of all given arrays in a single
   array, without duplicates, in any order
 

Documentation/Books/AQL/Functions/Document.mdpp

@@ -208,7 +208,7 @@ of the documents contained later in the argument list.
 
 
 - **documents** (object, *repeatable*): an arbitrary number of documents as
-  multiple arguments, at least 2
+  multiple arguments (at least 2)
 - returns **mergedDocument** (object): a combined document
 
 Note that merging will only be done for top-level attributes. If you wish to
@@ -273,7 +273,7 @@ If document attribute keys are ambiguous, the merged result will contain the val
 of the documents contained later in the argument list.
 
 - **documents** (object, *repeatable*): an arbitrary number of documents as
-  multiple arguments, at least 2
+  multiple arguments (at least 2)
 - returns **mergedDocument** (object): a combined document
 
 For example, two documents with distinct attribute names can easily be merged into one:
@@ -346,7 +346,7 @@ All other attributes will be preserved.
 
 - **document** (object): a document / object
 - **attributeNames** (string, *repeatable*): an arbitrary number of attribute
-  names as multiple arguments, at least 1
+  names as multiple arguments (at least 1)
 - returns **doc** (object): *document* without the specified attributes on the
   top-level
 
@@ -374,7 +374,7 @@ Recursively remove the attributes *attributeName1* to *attributeNameN* from
 
 - **document** (object): a document / object
 - **attributeNames** (string, *repeatable*): an arbitrary number of attribute
-  names as multiple arguments, at least 1
+  names as multiple arguments (at least 1)
 - returns **doc** (object): *document* without the specified attributes on
   all levels (top-level as well as nested objects)
 

Documentation/Books/AQL/Functions/README.mdpp

@@ -27,11 +27,9 @@ i.e. *LENGTH(foo)* and *length(foo)* are equivalent.
 
 !SUBSUBSECTION Extending AQL
  
-Since ArangoDB 1.3, it is possible to extend AQL with user-defined functions. 
+It is possible to extend AQL with user-defined functions. These functions need to
-These functions need to be written in JavaScript, and be registered before usage
+be written in JavaScript, and be registered before usage in a query. Please refer
-in a query.
+to [Extending AQL](../Extending/index.html) for more details on this.
-
-Please refer to [Extending AQL](../Extending/index.html) for more details on this.
 
 By default, any function used in an AQL query will be sought in the built-in 
 function namespace *_aql*. This is the default namespace that contains all AQL

Documentation/Books/AQL/Functions/String.mdpp

@@ -15,7 +15,7 @@ This is a synonym for [LENGTH()](#length).
 
 Concatenate the values passed as *value1* to *valueN*.
 
-- **values** (any, *repeatable*): elements of arbitrary type, at least one
+- **values** (any, *repeatable*): elements of arbitrary type (at least 1)
 - returns **str** (string): a concatenation of the elements. *null* values
   are ignored.
 
@@ -47,7 +47,7 @@ Concatenate the strings passed as arguments *value1* to *valueN* using the
 
 - **separator** (string): an arbitrary separator string
 - **values** (string|array, *repeatable*): strings or arrays of strings as multiple
-  arguments, at least one
+  arguments (at least 1)
 - returns **joinedString** (string): a concatenated string of the elements, using
   *separator* as separator string. *null* values are ignored. Array value arguments
   are expanded automatically, and their individual members will be concatenated.

Documentation/Books/AQL/Operations/Filter.mdpp

@@ -1,7 +1,9 @@
 !CHAPTER FILTER
 
 The *FILTER* statement can be used to restrict the results to elements that
-match an arbitrary logical condition. The general syntax is:
+match an arbitrary logical condition.
+
+!SECTION General syntax
 
 ```
 FILTER condition
@@ -22,7 +24,7 @@ FOR u IN users
 
 It is allowed to specify multiple *FILTER* statements in a query, even in
 the same block. If multiple *FILTER* statements are used, their results will be
-combined with a logical and, meaning all filter conditions must be true to
+combined with a logical AND, meaning all filter conditions must be true to
 include an element.
 
 ```
@@ -32,29 +34,32 @@ FOR u IN users
   RETURN u
 ```
 
-In the above example, will be included in the result all array elements from *users*  that have
+In the above example, all array elements of *users*  that have an attribute
-an attribute *active* with value *true* and that have an attribute *age* with a
+*active* with value *true* and that have an attribute *age* with a value less
-value less than *39* (including *null* ones). All other elements from *users* 
+than *39* (including *null* ones) will be included in the result. All other
-will be skipped and not be included in the result produced by *RETURN*.
+elements of *users* will be skipped and not be included in the result produced
-You may refer to the chapter [Accessing Data from Collections](../Fundamentals/DocumentData.md) for 
+by *RETURN*. You may refer to the chapter [Accessing Data from Collections](../Fundamentals/DocumentData.md)
-a description of the impact of non-existent or null attributes. 
+for a description of the impact of non-existent or null attributes.
+
+!SECTION Order of operations
 
 Note that the positions of *FILTER* statements can influence the result of a query.
-There are 16 active users in the test data for instance:
+There are 16 active users in the [test data](../Examples/README.md#example-data)
+for instance:
 
 ```js
 FOR u IN users
-    FILTER u.active == true
+  FILTER u.active == true
-    RETURN u
+  RETURN u
 ```
 
 We can limit the result set to 5 users at most:
 
 ```js
 FOR u IN users
-    FILTER u.active == true
+  FILTER u.active == true
-    LIMIT 5
+  LIMIT 5
-    RETURN u
+  RETURN u
 ```
 
 This may return the user documents of Jim, Diego, Anthony, Michael and Chloe for
@@ -64,10 +69,10 @@ women...
 
 ```js
 FOR u IN users
-    FILTER u.active == true
+  FILTER u.active == true
-    LIMIT 5
+  LIMIT 5
-    FILTER u.gender == "f"
+  FILTER u.gender == "f"
-    RETURN u
+  RETURN u
 ```
 
 ... it might just return the Chloe document, because the *LIMIT* is applied before
@@ -78,11 +83,11 @@ by adding a *SORT* block:
 
 ```js
 FOR u IN users
-    FILTER u.active == true
+  FILTER u.active == true
-    SORT u.age ASC
+  SORT u.age ASC
-    LIMIT 5
+  LIMIT 5
-    FILTER u.gender == "f"
+  FILTER u.gender == "f"
-    RETURN u
+  RETURN u
 ```
 
 This will return the users Mariah and Mary. If sorted by age in *DESC* order,
@@ -91,10 +96,10 @@ then the Sophia, Emma and Madison documents are returned. A *FILTER* after a
 
 ```js
 FOR u IN users
-    FILTER u.active == true AND u.gender == "f"
+  FILTER u.active == true AND u.gender == "f"
-    SORT u.age ASC
+  SORT u.age ASC
-    LIMIT 5
+  LIMIT 5
-    RETURN u
+  RETURN u
 ```
 
 The significance of where *FILTER* blocks are placed allows that this single

Documentation/Books/AQL/Operations/Limit.mdpp

@@ -2,9 +2,9 @@
 
 The *LIMIT* statement allows slicing the result array using an
 offset and a count. It reduces the number of elements in the result to at most
-the specified number.  Two general forms of *LIMIT* are followed:
+the specified number. Two general forms of *LIMIT* are followed:
 
-```
+```js
 LIMIT count
 LIMIT offset, count
 ```
@@ -14,13 +14,23 @@ allows specifying both *offset* and *count*. The first form is identical using
 the second form with an *offset* value of *0*.
 
 The *offset* value specifies how many elements from the result shall be
-discarded.  It must be 0 or greater. The *count* value specifies how many
+skipped. It must be 0 or greater. The *count* value specifies how many
 elements should be at most included in the result.
 
-```
+```js
 FOR u IN users
   SORT u.firstName, u.lastName, u.id DESC
   LIMIT 0, 5
   RETURN u
 ```
 
+Note that variables and expressions can not be used for *offset* and *count*.
+Their values must be known at query compile time, which means that you can
+use number literals and bind parameters only.
+
+Where a *LIMIT* is used in relation to other operations in a query has meaning.
+*LIMIT* operations before *FILTER*s in particular can change the result
+significantly, because the operations are executed in the order in which they
+are written in the query. See [FILTER](Filter.md#order-of-operations) for a
+detailed example.
+ 

Documentation/Books/AQL/Operators.mdpp

@@ -182,7 +182,6 @@ true && 23                                 // 23
 
 Arithmetic operators perform an arithmetic operation on two numeric
 operands. The result of an arithmetic operation is again a numeric value.
-Operators are supported.
 
 AQL supports the following arithmetic operators:
 
@@ -236,7 +235,8 @@ applied by the [TO_NUMBER()](Functions/TypeCast.md#tonumber) function:
 - objects / documents are converted to the number `0`.
 
 An arithmetic operation that produces an invalid value, such as `1 / 0` (division by zero)
-will also produce a result value of `null`.
+will also produce a result value of `null`. The query is not aborted, but you may see a
+warning.
 
 Here are a few examples:
 

Documentation/Books/HTTP/Document/README.mdpp

@@ -1,13 +1,6 @@
 !CHAPTER HTTP Interface for Documents
 
 In this chapter we describe the REST API of ArangoDB for documents.
-We begin with a 
-
-  - [section on the basic approach](AddressAndEtag.md)
-
-before we proceed with
-
-  - [the detailed API description](WorkingWithDocuments.md),
-
-which has all the gory details.
 
+  - [Basic approach](AddressAndEtag.md)
+  - [Detailed API description](WorkingWithDocuments.md)

Documentation/Books/HTTP/General/README.mdpp

@@ -76,7 +76,7 @@ response to the client instantly and thus finish this HTTP-request.
 The server will execute the tasks from the queue asynchronously as fast
 as possible, while clients can continue to do other work.
 If the server queue is full (i.e. contains as many tasks as specified by the
-option ["--scheduler.maximal-queue-size"](../../Manual/Administration/Configuration/Communication.html),
+option ["--scheduler.maximal-queue-size"](../../Manual/Administration/Configuration/Communication.html)),
 then the request will be rejected instantly with an *HTTP 500* (internal
 server error) response.