Documentation improvements

Documentation/Books/AQL/Functions/String.mdpp

@@ -185,7 +185,8 @@ using wildcard matching.
 - **text** (string): the string to search in
 - **search** (string): a search pattern that can contain the wildcard characters
   `%` (meaning any sequence of characters, including none) and `_` (any single
-  character). Literal *%* and *:* must be escaped with two backslashes.
+  character). Literal *%* and *:* must be escaped with two backslashes (four
+  in arangosh).
   *search* cannot be a variable or a document attribute. The actual value must
   be present at query parse time already.
 - **caseInsensitive** (bool, *optional*): if set to *true*, the matching will be
@@ -306,8 +307,9 @@ characters and sequences:
 
 Note that the characters `.`, `*`, `?`, `[`, `]`, `(`, `)`, `{`, `}`, `^`, 
 and `$` have a special meaning in regular expressions and may need to be 
-escaped using a backslash (`\\`). A literal backslash should also be escaped
+escaped using a backslash, which requires escaping itself (`\\`). A literal
-using another backslash, i.e. `\\\\`.
+backslash needs to be escaped using another escaped backslash, i.e. `\\\\`.
+In arangosh, the amount of backslashes needs to be doubled.
 
 Characters and sequences may optionally be repeated using the following
 quantifiers:

Documentation/Books/AQL/Graphs/Traversals.mdpp

@@ -122,28 +122,28 @@ FOR vertex[, edge[, path]]
 - `OPTIONS` **options** (object, *optional*): used to modify the execution of the
   traversal. Only the following attributes have an effect, all others are ignored:
   - **uniqueVertices** (string): optionally ensure vertex uniqueness
-    - "path" → it is guaranteed that there is no path returned with a duplicate vertex
+    - "path" – it is guaranteed that there is no path returned with a duplicate vertex
-    - "global" → it is guaranteed that each vertex is visited at most once during
+    - "global" – it is guaranteed that each vertex is visited at most once during
       the traversal, no matter how many paths lead from the start vertex to this one.
       If you start with a `min depth > 1` a vertex that was found before *min* depth
       might not be returned at all (it still might be part of a path). **Note:**
       Using this configuration the result is not deterministic any more. If there
       are multiple paths from *startVertex* to *vertex*, one of those is picked.
-    - "none" (default) → no uniqueness check is applied on vertices
+    - "none" (default) – no uniqueness check is applied on vertices
   - **uniqueEdges** (string): optionally ensure edge uniqueness
-    - "path" → it is guaranteed that there is no path returned with a duplicate edge
+    - "path" – it is guaranteed that there is no path returned with a duplicate edge
-    - "global" → it is guaranteed that each edge is visited at most once during
+    - "global" – it is guaranteed that each edge is visited at most once during
       the traversal, no matter how many paths lead from the start vertex to this edge.
       If you start with a `min depth > 1`, an edge that was found before *min* depth
       might not be returned at all (it still might be part of a path). **Note:**
       Using this configuration the result is not deterministic any more. If there
       are multiple paths from *startVertex* over *edge* one of those is picked.
-    - "none" (default) → no uniqueness check is applied on edges. **Note:**
+    - "none" (default) – no uniqueness check is applied on edges. **Note:**
       Using this configuration the traversal will follow cycles in edges.
   - **bfs** (bool): optionally use the alternative breadth-first traversal algorithm
-    - true → the traversal will be executed breadth-first. The results will first
+    - true – the traversal will be executed breadth-first. The results will first
       contain all vertices at depth 1. Than all vertices at depth 2 and so on.
-    - false (default) → the traversal will be executed depth-first. It will first
+    - false (default) – the traversal will be executed depth-first. It will first
       return all paths from *min* depth to *max* depth for one vertex at depth 1.
       Than for the next vertex at depth 1 and so on.
 

Documentation/Books/AQL/Invocation/WithWebInterface.mdpp

@@ -18,9 +18,9 @@ application code.
 Here is an example: 
 
 ```js
-FOR doc IN @@collection 
+FOR doc IN @@collection
-FILTER CONTAINS(LOWER(doc.author), @search, false)
+  FILTER CONTAINS(LOWER(doc.author), @search, false)
-RETURN { "name": doc.name, "descr": doc.description, "author": doc.author }
+  RETURN { "name": doc.name, "descr": doc.description, "author": doc.author }
 ```
 
 Bind parameters (table view mode):

Documentation/Books/AQL/Operators.mdpp

@@ -58,7 +58,8 @@ The supported wildcards are *_* to match a single arbitrary character, and *%* t
 match any number of arbitrary characters. Literal *%* and *_* need to be escaped
 with a backslash. Backslashes need to be escaped themselves, which effectively
 means that two reverse solidus characters need to preceed a literal percent sign
-or underscore.
+or underscore. In arangosh, additional escaping is required, making it four
+backslashes in total preceeding the to-be-escaped character.
 
 ```
 "abc" LIKE "a%"              // true
@@ -140,10 +141,12 @@ The result of the logical operators in AQL is defined as follows:
 
 Some examples for logical operations in AQL:
 
-    u.age > 15 && u.address.city != ""
+```js
-    true || false
+u.age > 15 && u.address.city != ""
-    ! u.isInvalid
+true || false
-    1 || ! 0
+NOT u.isInvalid
+1 || ! 0
+```
 
 Passing non-boolean values to a logical operator is allowed. Any non-boolean operands 
 will be casted to boolean implicitly by the operator, without making the query abort.
@@ -160,17 +163,20 @@ type and is not necessarily a boolean value.
 
 For example, the following logical operations will return boolean values:
 
-    25 > 1 && 42 != 7                          // true
+```js
-    22 IN [ 23, 42 ] || 23 NOT IN [ 22, 7 ]    // true
+25 > 1 && 42 != 7                          // true
-    25 != 25                                   // false
+22 IN [ 23, 42 ] || 23 NOT IN [ 22, 7 ]    // true
+25 != 25                                   // false
+```
 
 whereas the following logical operations will not return boolean values:
 
-    1 || 7                                     // 1
+```js
-    null || "foo"                              // "foo"
+1 || 7                                     // 1
-    null && true                               // null
+null || "foo"                              // "foo"
-    true && 23                                 // 23
+null && true                               // null
-
+true && 23                                 // 23
+```
    
 !SUBSUBSECTION Arithmetic operators
 
@@ -196,6 +202,7 @@ RETURN [-x, +y]
 ```
 
 For exponentiation, there is a [numeric function](Functions/Numeric.md#pow) *POW()*.
+The syntax `base ** exp` is not supported.
 
 For string concatenation, you must use the [string function](Functions/String.md#concat)
 *CONCAT()*. Combining two strings with a plus operator (`"foo" + "bar"`) will not work!
@@ -203,13 +210,15 @@ Also see [Common Errors](CommonErrors.md).
 
 Some example arithmetic operations:
 
-    1 + 1
+```
-    33 - 99
+1 + 1
-    12.4 * 4.5
+33 - 99
-    13.0 / 0.1
+12.4 * 4.5
-    23 % 7
+13.0 / 0.1
-    -15
+23 % 7
-    +9.99
+-15
++9.99
+```
 
 The arithmetic operators accept operands of any type. Passing non-numeric values to an 
 arithmetic operator will cast the operands to numbers using the type casting rules 
@@ -231,20 +240,21 @@ will also produce a result value of `null`.
 
 Here are a few examples:
 
-    1 + "a"                 // 1
+```
-    1 + "99"                // 100
+1 + "a"                 // 1
-    1 + null                // 1
+1 + "99"                // 100
-    null + 1                // 1
+1 + null                // 1
-    3 + [ ]                 // 3
+null + 1                // 1
-    24 + [ 2 ]              // 26
+3 + [ ]                 // 3
-    24 + [ 2, 4 ]           // 0
+24 + [ 2 ]              // 26
-    25 - null               // 25
+24 + [ 2, 4 ]           // 0
-    17 - true               // 16
+25 - null               // 25
-    23 * { }                // 0
+17 - true               // 16
-    5 * [ 7 ]               // 35
+23 * { }                // 0
-    24 / "12"               // 2
+5 * [ 7 ]               // 35
-    1 / 0                   // 0
+24 / "12"               // 2
-
+1 / 0                   // 0
+```
 
 !SUBSUBSECTION Ternary operator
 
@@ -255,7 +265,9 @@ evaluates to true, and the third operand otherwise.
 
 *Examples*
 
-    u.age > 15 || u.active == true ? u.userId : null
+```js
+u.age > 15 || u.active == true ? u.userId : null
+```
 
 !SUBSUBSECTION Range operator
 
@@ -268,18 +280,23 @@ both bounding values included.
 
 *Examples*
 
-    2010..2013
+```
+2010..2013
+```
 
 will produce the following result:
 
-    [ 2010, 2011, 2012, 2013 ]
+```json
+[ 2010, 2011, 2012, 2013 ]
+```
 
+There is also a [RANGE() function](Functions/Numeric.md#range).
 
 !SUBSUBSECTION Array operators 
 
-AQL provides [array operators](Advanced/ArrayOperators.md) <i>[\*]</i> for
+AQL provides array operators <i>[\*]</i> for
-array variable expansion and <i>[\*\*]</i> for array contraction. 
+[array variable expansion](Advanced/ArrayOperators.md#array-expansion) and
-
+<i>[\*\*]</i> for [array contraction](Advanced/ArrayOperators.md#array-contraction).
 
 !SUBSUBSECTION Operator precedence
 

Documentation/Books/Manual/DataModeling/Documents/DocumentMethods.mdpp

@@ -63,20 +63,20 @@ An attribute name of the form *a.b* is interpreted as attribute path,
 not as attribute. If you use
 
 ```json
-{ a : { c : 1 } }
+{ "a" : { "c" : 1 } }
 ```
 
 as example, then you will find all documents, such that the attribute
 *a* contains a document of the form *{c : 1 }*. For example the document
 
 ```json
-{ a : { c : 1 }, b : 1 }
+{ "a" : { "c" : 1 }, "b" : 1 }
 ```
 
 will match, but the document
 
 ```json
-{ a : { c : 1, b : 1 } }
+{ "a" : { "c" : 1, "b" : 1 } }
 ```
 
 will not.
@@ -84,20 +84,20 @@ will not.
 However, if you use
 
 ```json
-{ a.c : 1 }
+{ "a.c" : 1 }
 ```
 
 then you will find all documents, which contain a sub-document in *a*
 that has an attribute *c* of value *1*. Both the following documents
 
 ```json
-{ a : { c : 1 }, b : 1 }
+{ "a" : { "c" : 1 }, "b" : 1 }
 ```
 
 and
 
 ```json
-{ a : { c : 1, b : 1 } }
+{ "a" : { "c" : 1, "b" : 1 } }
 ```
 
 will match.
@@ -194,15 +194,15 @@ The function may be removed in future versions of ArangoDB. The preferred
 way for retrieving documents from a collection within a specific range
 is to use an AQL query as follows: 
 
-    FOR doc IN @@collection
+```js
-      FILTER doc.value >= @left && doc.value < @right
+FOR doc IN @@collection
-      LIMIT @skip, @limit
+  FILTER doc.value >= @left && doc.value < @right
-      RETURN doc
+  LIMIT @skip, @limit
-
+  RETURN doc
+```
 
 **Examples**
 
-
 Use *toArray* to get all documents at once:
 
     @startDocuBlockInline 005_collectionRange
@@ -218,7 +218,6 @@ Use *toArray* to get all documents at once:
     @endDocuBlock 005_collectionRange
 
 
-
 !SUBSECTION Closed range
 <!-- js/common/modules/@arangodb/arango-collection-common.js-->
 
@@ -240,15 +239,15 @@ The function may be removed in future versions of ArangoDB. The preferred
 way for retrieving documents from a collection within a specific range
 is to use an AQL query as follows:
 
-    FOR doc IN @@collection
+```js
-      FILTER doc.value >= @left && doc.value <= @right
+FOR doc IN @@collection
-      LIMIT @skip, @limit
+  FILTER doc.value >= @left && doc.value <= @right
-      RETURN doc
+  LIMIT @skip, @limit
-
+  RETURN doc
+```
 
 **Examples**
 
-
 Use *toArray* to get all documents at once:
 
     @startDocuBlockInline 006_collectionClosedRange

Documentation/Books/Manual/DataModeling/GraphsVerticesEdges.mdpp

@@ -5,6 +5,6 @@ Graphs, vertices & edges are defined in the [Graphs](../Graphs/README.md) chapte
 Related blog posts:
 
 - [Graphs in data modeling - is the emperor naked?](
-  https://medium.com/@neunhoef/graphs-in-data-modeling-is-the-emperor-naked-2e65e2744413#.x0a5z66ji
+  https://medium.com/@neunhoef/graphs-in-data-modeling-is-the-emperor-naked-2e65e2744413#.x0a5z66ji)
 - [Index Free Adjacency or Hybrid Indexes for Graph Databases](
   https://www.arangodb.com/2016/04/index-free-adjacency-hybrid-indexes-graph-databases/)

Documentation/DocuBlocks/WalLogfileThrottling.md

@@ -5,10 +5,8 @@ waiting for garbage collection
 `--wal.throttle-when-pending`
 
 The maximum value for the number of write-ahead log garbage-collection
-queue
+queue elements. If set to *0*, the queue size is unbounded, and no
-elements. If set to *0*, the queue size is unbounded, and no
+write-throttling will occur. If set to a non-zero value, write-throttling
-writtle-throttling will occur. If set to a non-zero value,
-writte-throttling
 will automatically kick in when the garbage-collection queue contains at
 least as many elements as specified by this option.
 While write-throttling is active, data-modification operations will
@@ -28,8 +26,6 @@ specified amount of time for the write-ahead log garbage-collection queue
 size to fall below the throttling threshold. If the queue size decreases
 before the maximum wait time is over, the operation will be executed
 normally. If the queue size does not decrease before the wait time is
-over,
+over, the operation will be aborted with an error.
-the operation will be aborted with an error.
 This option only has an effect if `--wal.throttle-when-pending` has a
 non-zero value, which is not the default.
-

Documentation/DocuBlocks/collectionByExample.md

@@ -13,29 +13,44 @@ operator.
 An attribute name of the form *a.b* is interpreted as attribute path,
 not as attribute. If you use
 
-*{ a : { c : 1 } }*
+```json
+{ "a": { "c": 1 } }
+```
 
 as example, then you will find all documents, such that the attribute
-*a* contains a document of the form *{c : 1 }*. For example the document
+*a* contains a document of the form *{ "c": 1 }*. For example the document
 
-*{ a : { c : 1 }, b : 1 }*
+```json
+{ "a" : { "c" : 1 }, "b" : 1 }
+```
 
 will match, but the document
 
-*{ a : { c : 1, b : 1 } }*
+```json
+{ "a" : { "c" : 1, "b" : 1 } }
+```
 
 will not.
 
 However, if you use
 
-*{ a.c : 1 }*,
+```json
+{ "a.c" : 1 }
+```
 
 then you will find all documents, which contain a sub-document in *a*
 that has an attribute *c* of value *1*. Both the following documents
 
-*{ a : { c : 1 }, b : 1 }* and
+```json
+{ "a" : { "c" : 1 }, "b" : 1 }
 
-*{ a : { c : 1, b : 1 } }*
+```
+
+and
+
+```json
+{ "a" : { "c" : 1, "b" : 1 } }
+```
 
 will match.
 

Documentation/DocuBlocks/collectionByExampleSkiplist.md

@@ -13,29 +13,44 @@ operator.
 An attribute name of the form *a.b* is interpreted as attribute path,
 not as attribute. If you use
 
-*{ a : { c : 1 } }*
+```json
+{ "a": { "c": 1 } }
+```
 
 as example, then you will find all documents, such that the attribute
-*a* contains a document of the form *{c : 1 }*. For example the document
+*a* contains a document of the form *{ "c": 1 }*. For example the document
 
-*{ a : { c : 1 }, b : 1 }*
+```json
+{ "a" : { "c" : 1 }, "b" : 1 }
+```
 
 will match, but the document
 
-*{ a : { c : 1, b : 1 } }*
+```json
+{ "a" : { "c" : 1, "b" : 1 } }
+```
 
 will not.
 
 However, if you use
 
-*{ a.c : 1 }*,
+```json
+{ "a.c" : 1 }
+```
 
 then you will find all documents, which contain a sub-document in *a*
-that has an attribute @LIT{c} of value *1*. Both the following documents
+that has an attribute *c* of value *1*. Both the following documents
 
-*{ a : { c : 1 }, b : 1 }*and
+```json
+{ "a" : { "c" : 1 }, "b" : 1 }
 
-*{ a : { c : 1, b : 1 } }*
+```
+
+and
+
+```json
+{ "a" : { "c" : 1, "b" : 1 } }
+```
 
 will match.