Merge pull request #815 from triAGENS/thomas-documentation-handling-databases

Documentation fixes: Reviewed HandlingDatabases

Documentation/ImplementorManual/HttpDatabase.md

@@ -116,6 +116,6 @@ applications until they are explicitly installed for the particular database.
 
 @copydoc GlossaryDatabaseName
 
-@copydoc GlossaryDatabaseOrganisation
+@copydoc GlossaryDatabaseOrganization
 
 @BNAVIGATE_HttpDatabase

Documentation/Manual/GlossaryDatabase.md

@@ -6,12 +6,12 @@ instance. Databases can be used to logically group and separate data. An ArangoD
 database consists of collections and dedicated database-specific worker processes.
 
 A database contains its own collections (which cannot be accessed from other databases),
-Foxx applications, and replication loggers and appliers. Each ArangoDB database
+Foxx applications and replication loggers and appliers. Each ArangoDB database
 contains its own system collections (e.g. `_users`, `_replication`, ...).
 
 There will always be at least one database in ArangoDB. This is the default
-database, named `_system`. This database cannot be dropped, and provides special
-operations for creating, dropping, and enumerating databases.
+database named `_system`. This database cannot be dropped and provides special
+operations for creating, dropping and enumerating databases.
 Users can create additional databases and give them unique names to access them later.
 Database management operations cannot be initiated from out of user-defined databases.
 

Documentation/Manual/GlossaryDatabaseName.md

@@ -2,10 +2,10 @@ DatabaseName {#GlossaryDatabaseName}
 ====================================
 
 @GE{Database Name}: A single ArangoDB instance can handle multiple databases 
-in parallel. When multiple databases are used, each database must be given a 
+in parallel. When multiple databases are used, each database must be given an 
 unique name. This name is used to uniquely identify a database. The default 
 database in ArangoDB is named `_system`.
 
 The database name is a string consisting of only letters, digits 
 and the `_` (underscore) and `-` (dash) characters. User-defined database 
-names must always start with a letter. Database names is case-sensitive.
+names must always start with a letter. Database names are case-sensitive.

Documentation/Manual/GlossaryDatabaseOrganization.md

@@ -0,0 +1,40 @@
+Database Organization {#GlossaryDatabaseOrganization}
+=====================================================
+
+@GE{Database Organization}: A single ArangoDB instance can handle multiple
+databases in parallel. By default, there will be at least one database which
+is named `_system`.
+
+Databases are physically stored in separate sub-directories underneath the
+`database` directory, which itself resides in the instance's data directory. 
+
+Each database has its own sub-directory, named `database-<database id>`. The
+database directory contains sub-directories for the collections of the 
+database, and a file named `parameter.json`. This file contains the database
+id and name.
+
+In an example ArangoDB instance which has two databases, the filesystem 
+layout could look like this:
+
+    data/                     # the instance's data directory
+      databases/              # sub-directory containing all databases' data
+        database-<id>/        # sub-directory for a single database
+          parameter.json      # file containing database id and name
+          collection-<id>/    # directory containg data about a collection
+        database-<id>/        # sub-directory for another database
+          parameter.json      # file containing database id and name
+          collection-<id>/    # directory containg data about a collection
+          collection-<id>/    # directory containg data about a collection
+
+Foxx applications are also organized in database-specific directories inside
+the application path. The filesystem layout could look like this:
+
+    apps/                   # the instance's application directory
+      system/               # system applications (can be ignored)
+      databases/            # sub-directory containing database-specific applications
+        <database-name>/    # sub-directory for a single database
+          <app-name>        # sub-directory for a single application
+          <app-name>        # sub-directory for a single application
+        <database-name>/    # sub-directory for another database
+          <app-name>        # sub-directory for a single application
+

Documentation/UserManual/HandlingDatabases.md

@@ -11,13 +11,13 @@ This is an introduction to managing databases in ArangoDB from within
 JavaScript. 
 
 While being in an established connection to ArangoDB, the current
-database can be changed explicity by using the `db._useDatabase()`
+database can be changed explicitly by using the `db._useDatabase()`
 method. This will switch to the specified database (provided it
 exists and the user can connect to it). From this point on, any
 following actions in the same shell or connection will use the
 specified database unless otherwise specified.
 
-Note: if the database is changed, client drivers need to store the 
+Note: If the database is changed, client drivers need to store the 
 current database name on their side, too. This is because connections
 in ArangoDB do not contain any state information. All state information
 is contained in the HTTP request/response data.
@@ -43,7 +43,7 @@ Working with Databases {#HandlingDatabasesShell}
 Database Methods {#HandlingDatabasesMethods}
 --------------------------------------------
 
-To following methods are available to manage databases via JavaScript.
+The following methods are available to manage databases via JavaScript.
 Please note that several of these methods can be used from the `_system`
 database only.
 
@@ -85,7 +85,7 @@ Notes about Databases {#HandlingDatabasesGlossary}
 Please keep in mind that each database contains its own system collections,
 which need to set up when a database is created. This will make the creation
 of a database take a while. Replication is configured on a per-database level,
-meaning that any replication logging or applying for the a new database must
+meaning that any replication logging or applying for a new database must
 be configured explicitly after a new database has been created. Foxx applications
 are also available only in the context of the database they have been installed 
 in. A new database will only provide access to the system applications shipped
@@ -96,6 +96,6 @@ applications until they are explicitly installed for the particular database.
 
 @copydoc GlossaryDatabaseName
 
-@copydoc GlossaryDatabaseOrganisation
+@copydoc GlossaryDatabaseOrganization
 
 @BNAVIGATE_HandlingDatabases