Minor documentation changes, part 1 (from devel, squashed): (#3957)

* Add WITH to graph traversal syntax

* State clearer what where whitespace is ignored in conf files

* Add cross-references between POSITION() and CONTAINS()

* Mention GeoJSON in the description of the useLonLat option

* Troubleshooting: unexpected long running queries
  Add remark that collection literals are inferior to FOR constructs and should not be used accidentally instead of variable names

* Add storage engine comparison table, replace hint to note that users might want to pick RocksDB for an installation

* CSS: No margin extra margin after last paragraph in callouts / hint boxes

Documentation/Books/AQL/CommonErrors.md

@@ -29,6 +29,69 @@ RETURN CONCAT("foo", 123)   // [ "foo123" ]
 RETURN CONCAT("123", 200)   // [ "123200" ]
 ```
 
+Unexpected long running queries
+-------------------------------
+
+Slow queries can have various reasons and be legitimate for queries with a high
+computational complexity or if they touch a lot of data. Use the *Explain*
+feature to inspect execution plans and verify that appropriate indexes are
+utilized. Also check for mistakes such as references to the wrong variables.
+
+A literal collection name, which is not part of constructs like `FOR`,
+`UPDATE ... IN` etc., stands for an array of all documents of that collection
+and can cause an entire collection to be materialized before further
+processing. It should thus be avoided.
+
+Check the execution plan for `/* all collection documents */` and verify that
+it is intended. You should also see a warning if you execute such a query:
+
+> collection 'coll' used as expression operand
+
+For example, instead of:
+
+```js
+RETURN coll[* LIMIT 1]
+```
+
+... with the execution plan ...
+
+```
+Execution plan:
+ Id   NodeType          Est.   Comment
+  1   SingletonNode        1   * ROOT
+  2   CalculationNode      1     - LET #2 = coll   /* all collection documents */[* LIMIT  0, 1]   /* v8 expression */
+  3   ReturnNode           1     - RETURN #2
+```
+
+... you can use the following equivalent query:
+
+```js
+FOR doc IN coll
+    LIMIT 1
+    RETURN doc
+```
+
+... with the (better) execution plan:
+
+```
+Execution plan:
+ Id   NodeType                  Est.   Comment
+  1   SingletonNode                1   * ROOT
+  2   EnumerateCollectionNode     44     - FOR doc IN Characters   /* full collection scan */
+  3   LimitNode                    1       - LIMIT 0, 1
+  4   ReturnNode                   1       - RETURN doc
+```
+
+Similarly, make sure you have not confused any variable names with collection
+names by accident:
+
+```js
+LET names = ["John", "Mary", ...]
+// supposed to refer to variable "names", not collection "Names"
+FOR name IN Names
+    ...
+```
+
 <!--
 
 Rename to Error Sources?

Documentation/Books/AQL/Functions/Array.md

@@ -199,6 +199,9 @@ Return whether *search* is contained in *array*. Optionally return the position.
   *false* otherwise. If *returnIndex* is enabled, the position of the match is
   returned (positions start at 0), or *-1* if it's not found.
 
+To determine if or at which position a string occurs in another string, see the
+[CONTAINS() string function](String.md#contains).
+
 ### PUSH()
 
 `PUSH(anyArray, value, unique) → newArray`

Documentation/Books/AQL/Functions/Geo.md

@@ -134,8 +134,8 @@ This can be changed by setting the 3rd parameter to *true* to interpret the poin
   points of the polygon
 - **coord** (array): the search coordinate as a number array with two elements
 - **useLonLat** (bool, *optional*): if set to *true*, the coordinates in *polygon* and
-  the search coordinate *coord* will be interpreted as *[lon, lat]*. The default is
+  the search coordinate *coord* will be interpreted as *[lon, lat]* (GeoJSON).
-  *false* and the format *[lat, lon]* is expected.
+  The default is *false* and the format *[lat, lon]* is expected.
 - returns **bool** (bool): *true* if the point *coord* is inside the *polygon* or
   *false* if it's not. The result is undefined (can be *true* or *false*) if the
   specified point is exactly on a boundary of the polygon.

Documentation/Books/AQL/Functions/String.md

@@ -101,6 +101,9 @@ CONTAINS("foobarbaz", "ba", true) // 3
 CONTAINS("foobarbaz", "horse", true) // -1
 ```
 
+To determine if or at which position a value is included in an array, see the
+[POSITION() array function](Array.md#position).
+
 ### COUNT()
 
 This is an alias for [LENGTH()](#length).

Documentation/Books/AQL/Graphs/Traversals.md

@@ -12,13 +12,17 @@ There are two slightly different syntaxes for traversals in AQL, one for
 ### Working with named graphs
 
 ```
+[WITH collection1[, collection2[, ...collectionN]]]
 FOR vertex[, edge[, path]]
   IN [min[..max]]
   OUTBOUND|INBOUND|ANY startVertex
   GRAPH graphName
   [OPTIONS options]
 ```
-
+- `WITH`: optional for single server instances, but required for
+  [graph traversals in a cluster](#graph-traversals-in-a-cluster).
+  - **collections** (collection, *repeatable*): list of collections that will
+    be involved in the traversal
 - `FOR`: emits up to three variables:
   - **vertex** (object): the current vertex in a traversal
   - **edge** (object, *optional*): the current edge in a traversal
@@ -76,6 +80,7 @@ FOR vertex[, edge[, path]]
 ### Working with collection sets
 
 ```
+[WITH collection1[, collection2[, ...collectionN]]]
 FOR vertex[, edge[, path]]
   IN [min[..max]]
   OUTBOUND|INBOUND|ANY startVertex
@@ -113,13 +118,13 @@ collection in your traversal.
 ### Graph traversals in a cluster
 
 Due to the nature of graphs, edges may reference vertices from arbitrary
-collections. Following the path can thus involve documents from various
+collections. Following the paths can thus involve documents from various
 collections and it's not possible to predict which will be visited in a
 traversal. Hence, which collections need to be locked can only be determined
 at run time. Deadlocks may occur under certain circumstances.
 
 Please consider to use the [`WITH` statement](../Operations/With.md) to
-specify the collections you expect to be involved. 
+specify the collections you expect to be involved.
 
 Using filters and the explainer to extrapolate the costs
 --------------------------------------------------------

Documentation/Books/AQL/styles/website.css

@@ -23,6 +23,10 @@ div.example_show_button {
   margin-bottom: 0.85em;
 }
 
+.book .book-body .alert p:last-child {
+  margin-bottom: 0;
+}
+
 .columns-3 {
   -webkit-column-count: 3;
   -moz-column-count: 3;

Documentation/Books/Cookbook/styles/website.css

@@ -23,6 +23,10 @@ div.example_show_button {
   margin-bottom: 0.85em;
 }
 
+.book .book-body .alert p:last-child {
+  margin-bottom: 0;
+}
+
 .columns-3 {
   -webkit-column-count: 3;
   -moz-column-count: 3;

Documentation/Books/HTTP/styles/website.css

@@ -23,6 +23,10 @@ div.example_show_button {
   margin-bottom: 0.85em;
 }
 
+.book .book-body .alert p:last-child {
+  margin-bottom: 0;
+}
+
 .columns-3 {
   -webkit-column-count: 3;
   -moz-column-count: 3;

Documentation/Books/Manual/Administration/Configuration/README.md

@@ -51,8 +51,7 @@ Only command line options with a value should be set within the configuration
 file. Command line options which act as flags should be entered on the command
 line when starting the server.
 
-Whitespace in the configuration file is ignored. Each option is specified on a
+Each option is specified on a separate line in the form:
-separate line in the form
 
 ```js
 key = value
@@ -79,6 +78,19 @@ So you see in general `--section.param value` translates to
 param=value 
 ```
 
+{% hint 'warning' %}
+Whitespace around `=` is ignored in the configuration file. Do not put spaces
+around additional `=` in the parameter value however. The following example
+shows the correct way to specify a log level of `trace` for the topic `startup`:
+
+```js
+log.level = startup=trace
+```
+
+Note that there is no whitespace between `startup` and `=`, and also not `=`
+and `trace`.
+{% endhint %}
+
 Where one section may occur multiple times, and the last occurance of `param`
 will become the final value. In case of parameters being vectors, multiple
 occurance adds another item to the vector. Vectors can be identified by the
@@ -104,4 +116,4 @@ or
 --configuration none
 ```
 
-When starting up the server. Note that, the word *none* is case-insensitive.
+when starting up the server. Note that, the word *none* is case-insensitive.

Documentation/Books/Manual/Architecture/StorageEngines.md

@@ -5,21 +5,32 @@ engine. The storage engine is responsible for persisting the documents
 on disk, holding copies in memory, providing indexes and caches to
 speed up queries.
 
-Up to version 3.1 ArangoDB only supported memory mapped files (MMFILES)
+Up to version 3.1 ArangoDB only supported memory mapped files (MMFiles)
 as sole storage engine. Beginning with 3.2 ArangoDB has support for
 pluggable storage engines. The second supported engine is RocksDB from
 Facebook.
 
+| MMFiles | RocksDB |
+|---|---|
+| default | optional |
+| dataset needs to fit into memory | work with as much data as fits on disk |
+| indexes in memory | hot set in memory, data and indexes on disk |
+| slow restart due to index rebuilding | fast startup (no rebuilding of indexes) |
+| volatile collections (only in memory, optional) | collection data always persisted |
+| collection level locking (writes block reads) | concurrent reads and writes |
+
+*Blog article: [Comparing new RocksDB and MMFiles storage engines](https://www.arangodb.com/why-arangodb/comparing-rocksdb-mmfiles-storage-engines/)*
+
 RocksDB is an embeddable persistent key-value store. It is a log
 structure database and is optimized for fast storage.
 
-The MMFILES engine is optimized for the use-case where the data fits
+The MMFiles engine is optimized for the use-case where the data fits
 into the main memory. It allows for very fast concurrent
 reads. However, writes block reads and locking is on collection
 level. Indexes are always in memory and are rebuilt on startup. This
 gives better performance but imposes a longer startup time.
 
-The ROCKSDB engine is optimized for large data-sets and allows for a
+The RocksDB engine is optimized for large data-sets and allows for a
 steady insert performance even if the data-set is much larger than the
 main memory. Indexes are always stored on disk but caches are used to
 speed up performance. RocksDB uses document-level locks allowing for
@@ -45,7 +56,7 @@ The main advantages of RocksDB are
 ### Caveats
 
 RocksDB allows concurrent writes. However, when touching the same document a
-write conflict is raised. This cannot happen with the MMFILES engine, therefore
+write conflict is raised. This cannot happen with the MMFiles engine, therefore
 applications that switch to RocksDB need to be prepared that such exception can
 arise. It is possible to exclusively lock collections when executing AQL. This
 will avoid write conflicts but also inhibits concurrent writes.

Documentation/Books/Manual/GettingStarted/README.md

@@ -35,7 +35,9 @@ startup parameters, installation in a cluster and so on, see
 [Installing](Installing/README.md).
 
 {% hint 'info' %}
-Want help? Read more about [**consulting, training and developer support**](https://www.arangodb.com/subscriptions/)
+ArangoDB offers two [**storage engines**](../Architecture/StorageEngines.md):
+MMFiles and RocksDB. Choose the one which suits your needs best in the
+installation process or on first startup.
 {% endhint %}
 
 ### Securing the installation

Documentation/Books/Manual/styles/website.css

@@ -23,6 +23,10 @@ div.example_show_button {
   margin-bottom: 0.85em;
 }
 
+.book .book-body .alert p:last-child {
+  margin-bottom: 0;
+}
+
 .columns-3 {
   -webkit-column-count: 3;
   -moz-column-count: 3;