Merge branch 'devel' of github.com:arangodb/ArangoDB into devel

Documentation/Books/AQL/Examples/Counting.mdpp

@@ -0,0 +1,21 @@
+!CHAPTER Counting
+
+!SECTION Amount of documents in a collection
+
+To return the count of documents that currently exist in a collection,
+you can call the [LENGTH() function](../Aql/ArrayFunctions.md#length):
+
+```
+RETURN LENGTH(collection)
+```
+
+This type of call is optimized since 2.8 (no unnecessary intermediate result
+is built up in memory) and it is therefore the prefered way to determine the count.
+In earlier versions with `COLLECT ... WITH COUNT INTO` available (since 2.4),
+you may use the following code for better performance instead:
+
+```
+FOR doc IN collection
+COLLECT WITH COUNT INTO length
+RETURN length
+```

Documentation/Books/AQL/ExecutionAndPerformance/ExplainingQueries.mdpp

@@ -9,7 +9,7 @@ return the execution plan and some information about what optimizations could be
 the query. The query will not be executed.
 
 Explaining a query can be achieved by calling the [HTTP REST API](../HttpAqlQuery/README.md).
-A query can also be explained from the ArangoShell using `ArangoStatement`s `explain` method.
+A query can also be explained from the ArangoShell using `ArangoStatement`'s `explain` method.
 
 By default, the query optimizer will return what it considers to be the *optimal plan*. The
 optimal plan will be returned in the `plan` attribute of the result. If `explain` is

Documentation/Books/AQL/ExecutionAndPerformance/ParsingQueries.mdpp

@@ -3,7 +3,7 @@
 Clients can use ArangoDB to check if a given AQL query is syntactically valid. ArangoDB provides
 an [HTTP REST API](../HttpAqlQuery/README.md) for this. 
 
-A query can also be parsed from the ArangoShell using `ArangoStatement`s `parse` method. The
+A query can also be parsed from the ArangoShell using `ArangoStatement`'s `parse` method. The
 `parse` method will throw an exception if the query is syntactically invalid. Otherwise, it will
 return the some information about the query.
 

Documentation/Books/AQL/ExecutionAndPerformance/QueryCache.mdpp

@@ -106,14 +106,14 @@ will require time proportional to the number of cached items that need to be inv
 
 There may be workloads in which enabling the query cache will lead to a performance
 degradation. It is not recommended to turn the query cache on in workloads that only
-modify data, or that modify data more often than read it. Turning on the query cache
+modify data, or that modify data more often than reading it. Turning on the query cache
 will also provide no benefit if queries are very diverse and do not repeat often.
 In read-only or read-mostly workloads, the query cache will be beneficial if the same
 queries are repeated lots of times.
 
 In general, the query cache will provide the biggest improvements for queries with
-small result sets that take long to calculate. If a query's results are very big and
-most of the query time is spent in copying the result from the cache to the client,
+small result sets that take long to calculate. If query results are very big and
+most of the query time is spent on copying the result from the cache to the client,
 then the cache will not provide much benefit.
 
 
@@ -180,7 +180,7 @@ this attribute to check if a specific query was served from the cache or not.
 !SECTION Restrictions
 
 Query results that are returned from the query cache do not contain any execution statistics,
-meaning their *extra.stats* attribute will not be present. Additionally query results returned
+meaning their *extra.stats* attribute will not be present. Additionally, query results returned
 from the cache will not contain profile information even if the *profile* option was set to
 true when invoking the query.
 

Documentation/Books/AQL/Extending/Conventions.mdpp

@@ -42,7 +42,7 @@ outer scopes. Not using the `var` keyword for own variables may cause side
 effects when executing the function.
 
 Here is an example that may modify outer scope variables `i` and `name`,
-making the function **not** side effects-free:
+making the function **not** side-effect free:
 
 ```js
 function (values) {
@@ -93,9 +93,9 @@ to undefined behavior and should be avoided.
 
 !SECTION Enforcing strict mode
 
-By default, any user function code will not be executed in *strict mode* or 
-*strong mode*. In order to make a user function being run in strict 
-mode, use `use strict` explicitly inside the user function, e.g.:
+By default, any user function code will be executed in *sloppy mode*, not
+*strict* or *strong mode*. In order to make a user function being run in strict
+mode, use `"use strict"` explicitly inside the user function, e.g.:
 
 ```js
 function (values) {
@@ -116,10 +116,13 @@ Any violation of the strict mode will trigger a runtime error.
 !SECTION Miscellaneous
 
 Internally, user functions are stored in a system collection named
-*_aqlfunctions*  of the selected database. 
-Documents in this collection should not be accessed directly, but 
-only via the dedicated interfaces.
-Also system collection are excluded from dumps created with 
-[arangodump](../HttpBulkImports/Arangodump.md). To include AQL user 
-functions in a dump, the dump should be started with the 
+*_aqlfunctions* of the selected database. The functions will be exclusively
+available for queries in that particular database.
+
+Documents in the *_aqlfunctions* collection (or any other system collection)
+should not be accessed directly, but only via the dedicated interfaces.
+
+Keep in mind that system collections are excluded from dumps created with
+[arangodump](../HttpBulkImports/Arangodump.md) by default. To include AQL user
+functions in a dump, the dump needs to be started with the
 option *--include-system-collections true*.

Documentation/Books/AQL/Functions/Date.mdpp

@@ -184,7 +184,7 @@ DATE_ADD(DATE_ADD("2016-02", "month", 1), -1, "day") // last day of February (29
 
   The string must be prefixed by a `P`. A separating `T` is only required if
   `H`, `M` and/or `S` are specified. You only need to specify the needed pairs
-  of amounts and time intervals.
+  of letters and numbers.
 
   Examples:
 
@@ -345,8 +345,8 @@ FOR user IN users
   - %: ignored
 
   `%yyyy` does not enforce a length of 4 for years before 0 and past 9999.
-  The same format as for `%yyyyyy` will used instead. `%yy` preserves the
-  sign for negative years and thus returns 3 characters in total.
+  The same format as for `%yyyyyy` will be used instead. `%yy` preserves the
+  sign for negative years and may thus return 3 characters in total.
   
   Single `%` characters will be ignored. Use `%%` for a literal `%`. To resolve
   ambiguities like in `%mmonth` (unpadded month number + the string "month")
@@ -411,5 +411,8 @@ special treatment of positive years too, if negative years are used (e.g.
 `+002015-05-15` and `-000753-01-01`). This is rarely used however, and AQL does
 not use the 7-character version for years between 0 and 9999 in ISO strings.
 Keep in mind that they can't be properly compared to dates outside that range.
+Sorting of negative dates does not result in a meaningful order, with years longer
+ago last, but months, days and the time components in otherwise correct order.
+
 Leap seconds are ignored, just as they are in JavaScript as per
 [ECMAScript Language Specifications](http://www.ecma-international.org/ecma-262/5.1/#sec-15.9.1.1).

Documentation/Books/AQL/HEADER.html

@@ -0,0 +1,42 @@
+<div id="header">
+  <div class="wrap">
+    <div id="logo">
+      <a href="https://docs.arangodb.com/">
+        <img src="https://docs.arangodb.com/assets/arangodb_logo.png">
+      </a>
+    </div>
+    <div class="arangodb_version">VERSION_NUMBER</div>
+    <div class="google-search">
+      <gcse:searchbox-only></gcse:searchbox-only>
+    </div>
+    <ul id="navmenu">
+      <li>
+        <a href="BASE_PATH/Users/index.html">Manual</a>
+      </li>
+      <li class="active-tab">
+        <a href="BASE_PATH/AQL/index.html">AQL</a>
+      </li>
+      <li>
+        <a href="BASE_PATH/HTTP/index.html">HTTP</a>
+      </li>
+      <li>
+        <a href="https://docs.arangodb.com/cookbook">Cookbook</a>
+      </li>
+      <li class="socialIcons">
+        <a href="https://github.com/ArangoDB/ArangoDB/issues" target="blank" name="github">
+          <i title="GitHub" class="fa fa-github"></i>
+        </a>
+      </li>
+      <li class="socialIcons">
+        <a href="http://stackoverflow.com/questions/tagged/arangodb" target="blank" name="stackoverflow">
+          <i title="Stackoverflow" class="fa fa-stack-overflow"></i>
+        </a>
+      </li>
+      <li class="socialIcons socialIcons-googlegroups">
+        <a href="https://groups.google.com/forum/#!forum/arangodb" target="blank" name="google groups">
+          <img title="Google Groups" alt="Google Groups" src="https://docs.arangodb.com/assets/googlegroupsIcon.png" style="height:14px"/>
+        </a>
+      </li>
+    </ul>
+  </div>
+</div>

Documentation/Books/AQL/Invocation/WithArangosh.mdpp

@@ -37,7 +37,19 @@ To pass bind parameters into a query, they can be specified as second argument t
 !SUBSUBSECTION ES6 template strings 
 
 It is also possible to use ES6 template strings for generating AQL queries. There is
-a template string generator function named *aqlQuery*:
+a template string generator function named *aqlQuery*; we call it once to demonstrate
+its result, and once putting it directly into the query:
+
+    ```js
+    var key = 'testKey';
+    aqlQuery`FOR c IN mycollection FILTER c._key == ${key} RETURN c._key`;
+    { 
+      "query" : "FOR c IN mycollection FILTER c._key == @value0 RETURN c._key", 
+      "bindVars" : { 
+        "value0" : "testKey" 
+      } 
+    }
+    ```
 
     @startDocuBlockInline 02_workWithAQL_aqlQuery
     @EXAMPLE_ARANGOSH_OUTPUT{02_workWithAQL_aqlQuery}

Documentation/Books/AQL/SUMMARY.md

@@ -0,0 +1,63 @@
+
+# Summary
+* [How to invoke AQL](Invocation/README.md)
+  * [with Arangosh](Invocation/WithArangosh.md)
+  * [with the Web Interface](Invocation/WithWebInterface.md)
+* [Data Modification Queries](DataModification.md)
+* [AQL Fundamentals](Fundamentals/README.md)
+  * [AQL Syntax](Fundamentals/Syntax.md)
+  * [Data types](Fundamentals/DataTypes.md)
+  * [Bind Parameters](Fundamentals/BindParameters.md)
+  * [Type and value order](Fundamentals/TypeValueOrder.md)
+  * [Accessing data from collections](Fundamentals/DocumentData.md)
+  * [Query Results](Fundamentals/QueryResults.md)
+  * [Query Errors](Fundamentals/QueryErrors.md)
+* [High level Operations](Operations/README.md)
+  * [FOR](Operations/For.md)
+  * [RETURN](Operations/Return.md)
+  * [FILTER](Operations/Filter.md)
+  * [SORT](Operations/Sort.md)
+  * [LIMIT](Operations/Limit.md)
+  * [LET](Operations/Let.md)
+  * [COLLECT](Operations/Collect.md)
+  * [REMOVE](Operations/Remove.md)
+  * [UPDATE](Operations/Update.md)
+  * [REPLACE](Operations/Replace.md)
+  * [INSERT](Operations/Insert.md)
+  * [UPSERT](Operations/Upsert.md)
+* [Operators](Operators.md)
+* [Functions](Functions/README.md)
+  * [Type cast](Functions/TypeCast.md)
+  * [String](Functions/String.md)
+  * [Numeric](Functions/Numeric.md)
+  * [Date](Functions/Date.md)
+  * [Array](Functions/Array.md)
+  * [Object / Document](Functions/Document.md)
+  * [Geo](Functions/Geo.md)
+  * [Fulltext](Functions/Fulltext.md)
+  * [Miscellaneous](Functions/Miscellaneous.md)
+* [Graphs](Graphs/README.md)
+  * [Traversal](Graphs/Traversals.md)
+  * [Named Operations](Graphs/Operations.md)
+  * [Other](Graphs/Functions.md)
+* [Advanced Features](Advanced/README.md)
+  * [Array Operators](Advanced/ArrayOperators.md)
+* [Usual Query Patterns](Examples/README.md)
+  * [Counting](Examples/Counting.md)
+  * [Data-modification queries](Examples/DataModificationQueries.md)
+  * [Subqueries](Examples/CombiningQueries.md)
+  * [Projections and filters](Examples/ProjectionsAndFilters.md)
+  * [Joins](Examples/Join.md)
+  * [Grouping](Examples/Grouping.md)
+  * [Traversals](Examples/CombiningGraphTraversals.md)
+  * [Queries without collections](Examples/QueriesNoCollections.md)
+* [User Functions](Extending/README.md)
+  * [Conventions](Extending/Conventions.md)
+  * [Registering Functions](Extending/Functions.md)
+* [Execution and Performance](ExecutionAndPerformance/README.md)
+  * [Query statistics](ExecutionAndPerformance/QueryStatistics.md)
+  * [Parsing queries](ExecutionAndPerformance/ParsingQueries.md)
+  * [Explaining queries](ExecutionAndPerformance/ExplainingQueries.md)
+  * [Optimizing queries](ExecutionAndPerformance/Optimizer.md)
+  * [Caching query results](ExecutionAndPerformance/QueryCache.md)
+* [Common Errors](CommonErrors.md)

Documentation/Books/AQL/book.json

@@ -0,0 +1,27 @@
+{
+  "gitbook": ">=2.0.0",
+  "title": "ArangoDB VERSION_NUMBER AQL Documentation",
+  "author": "ArangoDB GmbH",
+  "description": "Official AQL manual for ArangoDB - the multi-model NoSQL database",
+  "language": "en",
+  "plugins":["-search", "-sharing", "toggle-chapters", "addcssjs", "heading-anchors", "add-header"],
+  "pdf": {
+    "fontSize": 12,
+    "toc": true,
+    "margin": {
+      "right": 60,
+      "left": 60,
+      "top": 35,
+      "bottom": 35
+    }
+  },
+  "styles": {
+    "website": "styles/website.css"
+  },
+  "pluginsConfig": {
+    "addcssjs": {
+      "js": ["styles/header.js"],
+      "css": ["styles/header.css"]
+    }
+  }
+}

Documentation/Books/AQL/styles/header.css

@@ -0,0 +1,239 @@
+/* Design fix because of the header */
+@import url(https://fonts.googleapis.com/css?family=Roboto:400,500,300,700);
+
+body {
+  overflow: hidden;
+  font-family: Roboto, Helvetica, sans-serif;
+  background: #444444;
+}
+
+.book .book-header h1 a, .book .book-header h1 a:hover {
+  display: none;
+}
+
+/* GOOGLE START */
+
+.google-search #gsc-iw-id1{
+  border: none !important;
+}
+
+.google-search .gsst_b {
+  position: relative;
+  top: 10px;
+  left: -25px;
+  width: 1px;
+}
+
+.gsst_a .gscb_a {
+  color: #c01a07 !important;
+}
+
+.google-search input {
+  background-color: #fff !important;
+  font-family: Roboto, Helvetica, sans-serif;
+  font-size: 10pt !important;
+  padding-left: 5px !important; 
+  float: right;
+  position: relative;
+  top: 8px;
+  width: 100% !important;
+  height: 30px !important;
+}
+
+.google-search input:active {
+}
+
+.google-search {
+  margin-right: 114px !important;
+  margin-left: 10px !important;
+  float: right !important;
+}
+
+.google-search td, 
+.google-search table, 
+.google-search tr, 
+.google-search th {
+  background-color: #444444 !important;
+}
+
+.google-search .gsc-input-box,
+.google-search .gsc-input-box input {
+  border-radius: 3px !important;
+  width: 200px;
+}
+
+.gsc-branding-text,
+.gsc-branding-img,
+.gsc-user-defined-text {
+  display: none !important;
+}
+
+.google-search .gsc-input-box input {
+  font-size: 16px !important;
+}
+
+.google-search .gsc-search-button {
+  display: none !important;
+}
+
+.google-search .gsc-control-cse {
+  padding: 10px !important;
+}
+
+.google-search > div {
+  float: left !important;
+  width: 200px !important;
+}
+
+/* GOOGLE END */
+
+.book-summary,
+.book-body {
+  margin-top: 48px;
+}
+
+.book .book-summary ul.summary li.active > a,
+.book .book-summary ul.summary li a:hover {
+  color: #fff !important;
+}
+
+#logo {
+  display: block;
+  float: left;
+  color: #fff;
+  width: 12%;
+  line-height: 40px;
+}
+
+#logo img {
+  width: 150px;
+  margin-top: 0px;
+  margin-left: 114px;
+}
+
+.wrap {
+  display: block;
+  margin: 0 auto;
+  max-width: 1200px;
+  padding: 0 10px;
+}
+
+#header {
+  position: fixed;
+  width: 100%;
+  height: 48px;
+  z-index: 1;
+}
+
+#header .socialIcons-googlegroups a img {
+  position: relative;
+  top: 3px;
+}
+
+/*
+#header .wrap,
+#header .wrap .clearfix {
+  max-height: 48px;
+}
+*/
+
+.absolute{
+  position: absolute;
+  z-index: 10;
+  right: 0;
+  left: 0;
+  top: 0;
+}
+
+#navmenu {
+  display: block;
+  float: right;
+  margin: 0px;
+}
+
+#navmenu li {
+  display: block;
+  float: left;
+}
+
+#navmenu li a {
+  display: block;
+  float: left;
+  padding-left: 10px;
+  padding-right: 10px;
+  line-height: 48px;
+  font-size: 16px;
+  font-weight: 400;
+  color: #fff;
+  text-decoration: none;
+  font-family: Roboto, Helvetica, sans-serif;
+}
+
+#navmenu li a:hover, #navmenu li.active-tab a {
+  background: #8aa051 !important;
+}
+
+.arangodb_version {
+  float: left;
+  padding-left: 130px;
+  padding-top: 3px;
+  padding-right: 0px;
+  line-height: 40px;
+  font-weight: bold;
+  color: #fff;
+  text-decoration: none;
+}
+
+/** simple responsive updates **/
+
+@media screen and (max-width: 1100px) {
+  #logo {
+    position: absolute;
+    left: -100px;
+  }
+
+  .google-search {
+    margin-right: -5px !important;
+  }
+
+  .socialIcons {
+    display: none !important;
+  }
+}
+
+
+@media screen and (max-width: 770px) {
+  .google-search {
+    margin-right: -5px !important;
+    width: 200px !important;
+  }
+  #navmenu {
+    display: none;
+  }
+  #navmenu li a { font-size: 0.8em; padding: 0 15px; }
+  #navmenu li a img { width:11px; height:36px; padding-top: 4px; }
+  #logo {
+    width: 100px;
+    height: 50px;
+    position: absolute;
+    top: 4px;
+    left: -100px;
+    z-index: 9999;
+  }
+  #logo img {
+    width: 100px;
+    margin-top:4px;
+    position: absolute;
+    float: left;
+    left: -10px;
+  }
+
+  .arangodb_version { display: none !important; }
+}
+
+/** clearfix **/
+.clearfix:after { content: "."; display: block; clear: both; visibility: hidden; line-height: 0; height: 0; }
+.clearfix { display: inline-block; }
+
+html[xmlns] .clearfix { display: block; }
+* html .clearfix { height: 1%; }

Documentation/Books/AQL/styles/header.js

@@ -0,0 +1,40 @@
+window.onload = function(){
+window.localStorage.removeItem(":keyword");
+
+$(document).ready(function() {
+
+function appendHeader() {
+/*
+  var div = document.createElement('div');
+  div.innerHTML = '<header id="header" class="header absolute"><div class="wrap"><div class="clearfix" style="width:100%;"><div id="logo"><a href="https://docs.arangodb.com/"><img src="https://docs.arangodb.com/assets/arangodb_logo.png"></a></div><div class="arangodb_version">VERSION_NUMBER</div><div class="google-search"><gcse:searchbox-only></div><ul id="navmenu"><li><a href="https://tst.arangodb.com/simran/all-in-one/">Docs</a></li><li><a href="https://docs.arangodb.com/cookbook">Cookbook</a></li><li class="socialIcons"><a href="https://github.com/ArangoDB/ArangoDB/issues" target="blank" name="github"><i title="GitHub" class="fa fa-github"></i></a></li><li class="socialIcons"><a href="http://stackoverflow.com/questions/tagged/arangodb" target="blank" name="stackoverflow"><i title="Stackoverflow" class="fa fa-stack-overflow"></i></a></li><li class="socialIcons socialIcons-googlegroups"><a href="https://groups.google.com/forum/#!forum/arangodb" target="blank" name="google groups"><img title="Google Groups" alt="Google Groups" src="https://docs.arangodb.com/assets/googlegroupsIcon.png" style="height:14px"></img></a></li></ul></div></div></header>';
+
+    $('.book').before(div.innerHTML);
+*/
+  };
+
+
+  function rerenderNavbar() {
+    $('#header').remove();
+    appendHeader();
+    renderGoogleSearch();
+  };
+
+  function renderGoogleSearch() {
+  };
+  //render header
+  //rerenderNavbar();
+  function addGoogleSrc() {
+    var cx = '002866056653122356950:ju52xx-w-w8';
+    var gcse = document.createElement('script');
+    gcse.type = 'text/javascript';
+    gcse.async = true;
+    gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
+        '//cse.google.com/cse.js?cx=' + cx;
+    var s = document.getElementsByTagName('script')[0];
+    s.parentNode.insertBefore(gcse, s);
+  };
+  addGoogleSrc();
+
+});
+
+};

Documentation/Books/AQL/styles/website.css

@@ -0,0 +1,43 @@
+div.example_show_button {
+  border: medium solid lightgray;
+  text-align: center;
+  position: relative;
+  top: -10px;
+}
+
+.book .book-body .navigation.navigation-next {
+  right: 10px !important;
+}
+
+.book .book-summary ul.summary li.active>a,.book .book-summary ul.summary li a:hover {
+  color: #fff !important;
+  background: #80A54D !important;
+  text-decoration: none;
+}
+
+.book .book-body .page-wrapper .page-inner section.normal .deprecated{
+  background-color: rgba(240,240,0,0.4);
+}
+
+.columns-3 {
+  -webkit-column-count: 3;
+  -moz-column-count: 3;
+  -ms-column-count: 3;
+  -o-column-count: 3;
+  column-count: 3;
+  columns: 3;
+}
+
+.gsib_a {
+padding: 0px !important;
+}
+
+.gsc-control-cse {
+border: 0px !important;
+background-color: transparent !important;
+}
+
+
+.gsc-input {
+margin: 0px !important;
+}

Documentation/Books/HTTP/Document/AddressAndEtag.mdpp

@@ -0,0 +1,177 @@
+!CHAPTER Basics and Terminology
+
+!SUBSECTION Documents, Keys, Handles and Revisions
+
+Documents in ArangoDB are JSON objects. These objects can be nested (to
+any depth) and may contain lists. Each document has a unique 
+[primary key](../../Users/Appendix/Glossary.html#document-key) which 
+identifies it within its collection. Furthermore, each document is 
+uniquely identified
+by its [document handle](../../Users/Appendix/Glossary.html#document-handle) 
+across all collections in the same database. Different revisions of
+the same document (identified by its handle) can be distinguished by their 
+[document revision](../../Users/Appendix/Glossary.html#document-revision).
+Any transaction only ever sees a single revision of a document.
+
+Here is an example document:
+
+```js
+{
+  "_id" : "myusers/3456789",
+  "_key" : "3456789",
+  "_rev" : "3456789",
+  "firstName" : "Hugo",
+  "lastName" : "Schlonz",
+  "address" : {
+    "street" : "Street of Happiness",
+    "city" : "Heretown"
+  },
+  "hobbies" : [
+    "swimming",
+    "biking",
+    "programming"
+  ]
+}
+```
+
+All documents contain special attributes: the 
+[document handle](../../Users/Appendix/Glossary.html#document-handle) is stored
+as a string in `_id`, the
+[document's primary key](../../Users/Appendix/Glossary.html#document-key) in 
+`_key` and the 
+[document revision](../../Users/Appendix/Glossary.html#document-revision) in
+`_rev`. The value of the `_key` attribute can be specified by the user when
+creating a document. `_id` and `_key` values are immutable once the document
+has been created. The `_rev` value is maintained by ArangoDB automatically.
+
+
+!SUBSECTION Document Handle
+
+A document handle uniquely identifies a document in the database. It
+is a string and consists of the collection's name and the document key
+(`_key` attribute) separated by `/`.
+
+
+!SUBSECTION Document Key
+
+A document key uniquely identifies a document in the collection it is
+stored in. It can and should be used by clients when specific documents
+are queried. The document key is stored in the `_key` attribute of
+each document. The key values are automatically indexed by ArangoDB in
+a collection's primary index. Thus looking up a document by its
+key is a fast operation. The _key value of a document is
+immutable once the document has been created. By default, ArangoDB will
+auto-generate a document key if no _key attribute is specified, and use
+the user-specified _key otherwise.
+
+This behavior can be changed on a per-collection level by creating
+collections with the `keyOptions` attribute.
+
+Using `keyOptions` it is possible to disallow user-specified keys
+completely, or to force a specific regime for auto-generating the `_key`
+values.
+
+
+!SUBSECTION Document Revision
+
+As ArangoDB supports MVCC (Multiple Version Concurrency Control),
+documents can exist in more than one
+revision. The document revision is the MVCC token used to specify 
+a particular revision of a document (identified by its `_id`). 
+It is a string value currently
+containing an integer number and is unique within the list of document
+revisions for a single document. Document revisions can be used to
+conditionally query, update, replace or delete documents in the database. In
+order to find a particular revision of a document, you need the document
+handle or key, and the document revision.
+
+ArangoDB uses 64bit unsigned integer values to maintain
+document revisions internally. When returning document revisions to
+clients, ArangoDB will put them into a string to ensure the revision
+is not clipped by clients that do not support big integers. Clients
+should treat the revision returned by ArangoDB as an opaque string
+when they store or use it locally. This will allow ArangoDB to change
+the format of revisions later if this should be required. Clients can
+use revisions to perform simple equality/non-equality comparisons
+(e.g. to check whether a document has changed or not), but they should
+not use revision ids to perform greater/less than comparisons with them
+to check if a document revision is older than one another, even if this
+might work for some cases.
+
+
+!SUBSECTION Document Etag
+
+ArangoDB tries to adhere to the existing HTTP standard as far as
+possible. To this end, results of single document queries have the HTTP
+header `ETag` set to the document revision enclosed in double quotes.
+
+The basic operations (create, read, exists, replace, update, delete)
+for documents are mapped to the standard HTTP methods (*POST*, *GET*,
+*HEAD*, *PUT*, *PATCH* and *DELETE*).
+
+If you modify a document, you can use the *If-Match* field to detect conflicts. 
+The revision of a document can be checking using the HTTP method *HEAD*.
+
+
+!SUBSECTION Multiple Documents in a single Request
+
+Beginning with ArangoDB 3.0 the basic document API has been extended
+to handle not only single documents but multiple documents in a single
+request. This is crucial for performance, in particular in the cluster
+situation, in which a single request can involve multiple network hops
+within the cluster. Another advantage is that it reduces the overhead of
+the HTTP protocol and individual network round trips between the client
+and the server. The general idea to perform multiple document operations 
+in a single request is to use a JSON array of objects in the place of a 
+single document. As a consequence, document keys, handles and revisions
+for preconditions have to be supplied embedded in the individual documents
+given. Multiple document operations are restricted to a single document
+or edge collections. 
+See the [API descriptions](WorkingWithDocuments.md) for details.
+
+Note that the *GET*, *HEAD* and *DELETE* HTTP operations generally do
+not allow to pass a message body. Thus, they cannot be used to perform
+multiple document operations in one request. However, there are other
+endpoints to request and delete multiple documents in one request.
+FIXME: ADD SENSIBLE LINKS HERE.
+
+
+!SUBSECTION URI of a Document
+
+Any document can be retrieved using its unique URI:
+
+    http://server:port/_api/document/<document-handle>
+
+For example, assuming that the document handle
+is `demo/362549736`, then the URL of that document
+is:
+
+    http://localhost:8529/_api/document/demo/362549736
+
+The above URL schema does not specify a 
+[database name](../../Users/Appendix/Glossary..html#database-name) 
+explicitly, so the 
+default database `_system` will be used. 
+To explicitly specify the database context, use
+the following URL schema:
+
+    http://server:port/_db/<database-name>/_api/document/<document-handle>
+
+Example:
+
+    http://localhost:8529/_db/mydb/_api/document/demo/362549736
+
+**Note**: The following examples use the short URL format for brevity.
+
+The [document revision](../../Users/Appendix/Glossary.html#document-revision) 
+is returned in the "ETag" HTTP header when requesting a document.
+
+If you obtain a document using *GET* and you want to check whether a 
+newer revision
+is available, then you can use the *If-None-Match* header. If the document is
+unchanged, a *HTTP 412* (precondition failed) error is returned.
+
+If you want to query, replace, update or delete a document, then you
+can use the *If-Match* header. If the document has changed, then the
+operation is aborted and an *HTTP 412* error is returned.
+

Documentation/Books/HTTP/Document/README.mdpp

@@ -0,0 +1,13 @@
+!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.
+

Documentation/Books/HTTP/Document/WorkingWithDocuments.mdpp

@@ -0,0 +1,124 @@
+!CHAPTER Working with Documents using REST
+
+<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
+@startDocuBlock REST_DOCUMENT_READ
+
+!SUBSUBSECTION Changes in 3.0 from 2.8:
+
+The *rev* query parameter has been withdrawn. The same effect can be
+achieved with the *If-Match* HTTP header.
+
+<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
+@startDocuBlock REST_DOCUMENT_READ_HEAD
+
+!SUBSUBSECTION Changes in 3.0 from 2.8:
+
+The *rev* query parameter has been withdrawn. The same effect can be
+achieved with the *If-Match* HTTP header.
+
+<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
+@startDocuBlock REST_DOCUMENT_READ_ALL
+
+!SUBSUBSECTION Changes in 3.0 from 2.8:
+
+The collection name should now be specified in the URL path. The old
+way with the URL path */_api/document* and the required query parameter
+*collection* still works.
+
+<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
+@startDocuBlock REST_DOCUMENT_CREATE
+
+!SUBSUBSECTION Changes in 3.0 from 2.8:
+
+The collection name should now be specified in the URL path. The old
+way with the URL path */_api/document* and the required query parameter
+*collection* still works. The possibility to insert multiple documents
+with one operation is new and the query parameter *returnNew* has been added.
+
+
+<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
+@startDocuBlock REST_DOCUMENT_REPLACE
+
+!SUBSUBSECTION Changes in 3.0 from 2.8:
+
+There are quite some changes in this in comparison to Version 2.8, but
+few break existing usage:
+
+  - the *rev* query parameter is gone (was duplication of If-Match)
+  - the *policy* query parameter is gone (was non-sensical)
+  - the *ignoreRevs* query parameter is new, the default *true* gives 
+    the traditional behaviour as in 2.8
+  - the *returnNew* and *returnOld* query parameters are new
+
+There should be very few changes to behaviour happening in real-world
+situations or drivers. Essentially, one has to replace usage of the
+*rev* query parameter by usage of the *If-Match* header. The non-sensical
+combination of *If-Match* given and *policy=last* no longer works, but can
+easily be achieved by leaving out the *If-Match* header.
+
+The collection name should now be specified in the URL path. The old
+way with the URL path */_api/document* and the required query parameter
+*collection* still works.
+
+<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
+@startDocuBlock REST_DOCUMENT_REPLACE_MULTI
+
+!SUBSUBSECTION Changes in 3.0 from 2.8:
+
+The multi document version is new in 3.0.
+
+<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
+@startDocuBlock REST_DOCUMENT_UPDATE
+
+!SUBSUBSECTION Changes in 3.0 from 2.8:
+
+There are quite some changes in this in comparison to Version 2.8, but
+few break existing usage:
+
+  - the *rev* query parameter is gone (was duplication of If-Match)
+  - the *policy* query parameter is gone (was non-sensical)
+  - the *ignoreRevs* query parameter is new, the default *true* gives 
+    the traditional behaviour as in 2.8
+  - the *returnNew* and *returnOld* query parameters are new
+
+There should be very few changes to behaviour happening in real-world
+situations or drivers. Essentially, one has to replace usage of the
+*rev* query parameter by usage of the *If-Match* header. The non-sensical
+combination of *If-Match* given and *policy=last* no longer works, but can
+easily be achieved by leaving out the *If-Match* header.
+
+The collection name should now be specified in the URL path. The old
+way with the URL path */_api/document* and the required query parameter
+*collection* still works.
+
+<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
+@startDocuBlock REST_DOCUMENT_UPDATE_MULTI
+
+!SUBSUBSECTION Changes in 3.0 from 2.8:
+
+The multi document version is new in 3.0.
+
+<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
+@startDocuBlock REST_DOCUMENT_DELETE
+
+!SUBSUBSECTION Changes in 3.0 from 2.8:
+
+There are only very few changes in this in comparison to Version 2.8:
+
+  - the *rev* query parameter is gone (was duplication of If-Match)
+  - the *policy* query parameter is gone (was non-sensical)
+  - the *returnOld* query parameter is new
+
+There should be very few changes to behaviour happening in real-world
+situations or drivers. Essentially, one has to replace usage of the
+*rev* query parameter by usage of the *If-Match* header. The non-sensical
+combination of *If-Match* given and *policy=last* no longer works, but can
+easily be achieved by leaving out the *If-Match* header.
+
+<!-- arangod/RestHandler/RestDocumentHandler.cpp -->
+@startDocuBlock REST_DOCUMENT_DELETE_MULTI
+
+!SUBSUBSECTION Changes in 3.0 from 2.8:
+
+This variant is new in 3.0. Note that it requires a body in the DELETE
+request.