updated documentation

CHANGELOG

@@ -10,7 +10,7 @@ v3.0.0 (XXXX-XX-XX)
   The operator is currently implemented by calling the already existing AQL
   function `LIKE`.
 
-  This change also makes `LIKE` an AQL keyword. Using `like` in either case as
+  This change also makes `LIKE` an AQL keyword. Using `LIKE` in either case as
   an attribute or collection name in AQL thus requires quoting.
 
 * make AQL optimizer rule "remove-unnecessary-calculations" fire in more cases

Documentation/Books/Users/AqlOperations/Insert.mdpp

@@ -65,7 +65,7 @@ To refer to the inserted documents, the `INSERT` statement introduces a pseudo-v
 named `NEW`. 
 
 The documents contained in `NEW` will contain all attributes, even those auto-generated by
-the database (e.g. `_id`, `_key`, `_rev`, `_from`, and `_to`).
+the database (e.g. `_id`, `_key`, `_rev`).
 
 
 ```

Documentation/Books/Users/AqlOperations/Replace.mdpp

@@ -9,8 +9,7 @@ Each *REPLACE* operation is restricted to a single collection, and the
 Only a single *REPLACE* statement per collection is allowed per AQL query, and 
 it cannot be followed by read operations that access the same collection, by
 traversal operations, or AQL functions that can read documents.
-The system attributes of documents (*_key*, *_id*, *_from*, *_to*, *_rev*) cannot be
-replaced.
+The system attributes *_id*, *_key* and *_rev* cannot be replaced, *_from* and *_to* can.
 
 The two syntaxes for a replace operation are:
 

Documentation/Books/Users/AqlOperations/Update.mdpp

@@ -9,8 +9,7 @@ Each *UPDATE* operation is restricted to a single collection, and the
 Only a single *UPDATE* statement per collection is allowed per AQL query, and 
 it cannot be followed by read operations that access the same collection, by
 traversal operations, or AQL functions that can read documents.
-The system attributes of documents (*_key*, *_id*, *_from*, *_to*, *_rev*) cannot be
-updated.
+The system attributes *_id*, *_key* and *_rev* cannot be updated, *_from* and *_to* can.
 
 The two syntaxes for an update operation are:
 

Documentation/Books/Users/AqlOperations/Upsert.mdpp

@@ -24,8 +24,7 @@ updated or added. When using the *REPLACE* variant of upsert, existing documents
 be replaced with the contexts of *update-expression*.
 
 Updating a document will modify the document's revision number with a server-generated value.
-The system attributes of documents (*_key*, *_id*, *_from*, *_to*, *_rev*) cannot be
-updated.
+The system attributes *_id*, *_key* and *_rev* cannot be updated, *_from* and *_to* can.
 
 The *search-expression* contains the document to be looked for. It must be an object 
 literal without dynamic attribute names. In case no such document can be found in

Documentation/Books/Users/Documents/DocumentMethods.mdpp

@@ -837,8 +837,8 @@ replaces documents matching an example
 
 Replaces all documents matching an example with a new document body.
 The entire document body of each document matching the *example* will be
-replaced with *newValue*. The document meta-attributes such as *_id*,
-*_key*, *_from*, *_to* will not be replaced.
+replaced with *newValue*. The document meta-attributes *_id*, *_key* and
+*_rev* will not be replaced.
 
 `collection.replaceByExample(document, newValue, waitForSync)`
 
@@ -884,8 +884,7 @@ partially updates documents matching an example
 Partially updates all documents matching an example with a new document body.
 Specific attributes in the document body of each document matching the
 *example* will be updated with the values from *newValue*.
-The document meta-attributes such as *_id*, *_key*, *_from*,
-*_to* cannot be updated.
+The document meta-attributes *_id*, *_key* and *_rev* cannot be updated.
 
 Partial update could also be used to append new fields,
 if there were no old field with same name.

Documentation/Books/Users/Edges/README.mdpp

@@ -9,8 +9,8 @@ A graph data model always consists of at least two collections: the relations be
 nodes in the graphs are stored in an "edges collection", the nodes in the graph
 are stored in documents in regular collections.
 
-Edges in ArangoDB are special documents. In addition to the internal 
-attributes *_key*, *_id* and *_rev*, they have two attributes *_from* and *_to*, 
+Edges in ArangoDB are special documents. In addition to the system
+attributes *_key*, *_id* and *_rev*, they have the attributes *_from* and *_to*, 
 which contain [document handles](../Glossary/README.md#document-handle), namely the start-point and the end-point of the edge.
 
 *Example*:
@@ -21,9 +21,6 @@ which contain [document handles](../Glossary/README.md#document-handle), namely
 - *_from* is the [document handle](../Glossary/README.md#document-handle) of the linked vertex (incoming relation)
 - *_to* is the document handle of the linked vertex (outgoing relation)
 
-The values of *_from* and *_to* are immutable once as edge was saved - thus you will not be able to update them.
-
-
 [Edge collections](../Glossary/README.md#edge-collection) are special collections that store edge documents. Edge documents 
 are connection documents that reference other documents. The type of a collection 
 must be specified when a collection is created and cannot be changed afterwards.

Documentation/Books/Users/Glossary/README.mdpp

@@ -103,9 +103,7 @@ ArangoDB currently uses 64bit unsigned integer values to maintain document revis
 
 !SUBSECTION Edge
 
-Edges are special documents used for connecting other documents into a graph. An edge describes the connection between two documents using the internal attributes: _from and _to. These contain document handles, namely the start-point and the end-point of the edge.
-
-The values of _from and _to are immutable once saved.
+Edges are special documents used for connecting other documents into a graph. An edge describes the connection between two documents using the internal attributes: `_from` and `_to`. These contain document handles, namely the start-point and the end-point of the edge.
 
 !SUBSECTION Edge Collection
 
@@ -127,15 +125,15 @@ Named graphs enforce consistency between edge collections and vertex collections
 
 Indexes are used to allow fast access to documents in a collection. All collections have a primary index, which is the document's _key attribute. This index cannot be dropped or changed.
 
-Edge collections will also have an automatically created edges index, which cannot be modified. This index provides quick access to documents via the _from and _to attributes.
+Edge collections will also have an automatically created edges index, which cannot be modified. This index provides quick access to documents via the `_from` and `_to` attributes.
 
 Most user-land indexes can be created by defining the names of the attributes which should be indexed. Some index types allow indexing just one attribute (e.g. fulltext index) whereas other index types allow indexing multiple attributes.
 
-Indexing system attributes such as _id, _key, _from, and _to in user-defined indexes is not supported by any index type. Manually creating an index that relies on any of these attributes is unsupported.
+Indexing the system attribute `_id` in user-defined indexes is not supported by any index type.
 
 !SUBSECTION Edges Index
 
-An edges index is automatically created for edge collections. It contains connections between vertex documents and is invoked when the connecting edges of a vertex are queried. There is no way to explicitly create or delete edge indexes.
+An edges index is automatically created for edge collections. It contains connections between vertex documents and is invoked when the connecting edges of a vertex are queried. There is no way to explicitly create or delete edges indexes.
 
 !SUBSECTION Fulltext Index
 

Documentation/Books/Users/HttpIndexes/README.mdpp

@@ -8,11 +8,11 @@ general. There are special sections for various index types.
 !SUBSUBSECTION Index
 
 Indexes are used to allow fast access to documents. For each collection there is always the primary index which is a hash index for the [document key](../Glossary/README.md#document-key) (_key attribute). This index cannot be dropped or changed.
-[edge collections](../Glossary/README.md#edge-collection) will also have an automatically created edges index, which cannot be modified. This index provides quick access to documents via the _from and _to attributes.
+[edge collections](../Glossary/README.md#edge-collection) will also have an automatically created edges index, which cannot be modified. This index provides quick access to documents via the `_from` and `_to` attributes.
 
 Most user-land indexes can be created by defining the names of the attributes which should be indexed. Some index types allow indexing just one attribute (e.g. fulltext index) whereas other index types allow indexing multiple attributes.
 
-Indexing system attributes such as _id, _key, _from, and _to in user-defined indexes is not supported by any index type. Manually creating an index that relies on any of these attributes is unsupported.
+Using the system attribute `_id` in user-defined indexes is not supported by any index type.
 
 !SUBSUBSECTION Index Handle
 

Documentation/Books/Users/IndexHandling/IndexBasics.mdpp

@@ -13,8 +13,8 @@ other index types allow indexing multiple attributes at the same time.
 The system attributes `_id`, `_key`, `_from` and `_to` are automatically indexed
 by ArangoDB, without the user being required to create extra indexes for them.
 
-Therefore, indexing `_id`, `_key`, `_rev`, `_from`, and `_to` in a user-defined 
-index is often not required and is currently not supported by ArangoDB.
+Using the system attribute `_id` in user-defined indexes is not possible, but 
+indexing `_key`, `_rev`, `_from`, and `_to` is.
 
 ArangoDB provides the following index types:
 

Documentation/Books/Users/NamingConventions/AttributeNames.mdpp

@@ -24,11 +24,10 @@ following attribute naming constraints are not violated:
   portability, special characters should be avoided though.  For example,
   attribute names may contain the dot symbol, but the dot has a special meaning
   in JavaScript and also in AQL, so when using such attribute names in one of
-  these languages, the attribute name would need to be quoted by the end
-  user. This will work but requires more work so it might be better to use
-  attribute names which don't require any quoting/escaping in all languages
-  used. This includes languages used by the client (e.g. Ruby, PHP) if the
-  attributes are mapped to object members there.
+  these languages, the attribute name needs to be quoted by the end user. 
+  Overall it might be better to use attribute names which don't require any 
+  quoting/escaping in all languages used. This includes languages used by the 
+  client (e.g. Ruby, PHP) if the attributes are mapped to object members there.
 * Attribute names starting with an at-mark (*@*) will need to be enclosed in
   backticks when used in an AQL query to tell them apart from bind variables.
   Therefore we do not encourage the use of attributes starting with at-marks,
@@ -36,23 +35,6 @@ following attribute naming constraints are not violated:
 * ArangoDB does not enforce a length limit for attribute names. However, long
   attribute names may use more memory in result sets etc. Therefore the use
   of long attribute names is discouraged.
-* As ArangoDB saves document attribute names separate from the actual document
-  attribute value data, the combined length of all attribute names for a
-  document must fit into an ArangoDB shape structure. The maximum combined names
-  length is variable and depends on the number and data types of attributes
-  used.
 * Attribute names are case-sensitive.
-* Attribute names should not include the NUL byte (`\u0000`), as names will be
-  truncated at the first NUL byte.
-* Attributes with empty names (the empty string) 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:
-
-      { "a" : 1, "" : 2, "b": 3 }
-
-  and later requested, it will be returned like this:
-      
-      { "a" : 1, "b": 3 }
+* Attributes with empty names (the empty string) are disallowed.
 

Documentation/Books/Users/Upgrading/UpgradingChanges30.mdpp

@@ -3,6 +3,47 @@
 It is recommended to check the following list of incompatible changes **before**
 upgrading to ArangoDB 3.0, and adjust any client programs if necessary.
 
+!SECTION Datafiles and datafile names
+
+ArangoDB 3.0 uses a new VelocyPack-based format for storing data in WAL logfiles
+and collection datafiles. The file format is not compatible with the files used
+in prior versions of ArangoDB. That means datafiles written by ArangoDB 3.0 cannot be
+used in earlier versions and vice versa.
+
+The pattern for collection directory names was changed in 3.0 to include a random 
+id component at the end. The new pattern is `collection-<id>-<random>`, where `<id>` 
+is the collection id and `<random>` is a random number. Previous versions of ArangoDB 
+used a pattern `collection-<id>` without the random number.
+  
+
+!SECTION Edges and edges attributes
+
+In ArangoDB prior to 3.0 the attributes `_from` and `_to` of edges were treated 
+specially when loading or storing edges. That special handling led to these attributes
+being not as flexible as regular document attributes. For example, the `_from` and 
+`_to` attribute values of an existing edge could not be updated once the edge was
+created. Additionally, the `_from` and `_to` attributes could not be indexed in
+user-defined indexes, e.g. to make each combination of `_from` and `_to` unique.
+Finally, as `_from` and `_to` referenced the linked collections by collection id
+and not by collection name, their meaning became unclear once a referenced collection 
+was dropped. The collection id stored in edges then became unusable, and when
+accessing such edge the collection name part of it was always translated to `_undefined`.
+
+In ArangoDB 3.0, the `_from` and `_to` values of edges are saved as regular strings.
+This allows using `_from` and `_to` in user-defined indexes. Additionally this allows
+updating the `_from` and `_to` values of existing edges. Furthermore, collections
+referenced by `_from` and `_to` values may be dropped and re-created later. Any
+`_from` and `_to` values of edges pointing to such dropped collection are unaffected
+by the drop operation now. 
+
+
+!SECTION AQL
+
+`LIKE` is now a keyword in AQL. Using `LIKE` in either case as an attribute or collection 
+name in AQL queries now requires quoting.
+
+The AQL optimizer rule "merge-traversal-filter" was renamed to "optimize-traversals".
+
 
 !SECTION Command Line Options
 
@@ -104,6 +145,11 @@ previous versions of ArangoDB, this route was accessible from within the `_syste
 database only, and an HTTP 403 (Forbidden) was thrown by the server for any access
 from within another database.
 
+The undocumented HTTP REST endpoints `/_open/cerberus` and `/_system/cerberus` have
+been removed. These endpoints have been used by some ArangoDB-internal applications
+and were not part of ArangoDB's public API.
+
+
 !SECTION Miscellaneous changes
 
 The checksum calculation algorithm for the `collection.checksum()` method and its