updated some documentation

Documentation/arango.template.in

@@ -701,8 +701,7 @@ EXAMPLE_PATH           = \
 	@srcdir@/Documentation/Examples.Ahuacatl \
 	@srcdir@/Documentation/Examples.ArangoDB \
 	@srcdir@/Documentation/Examples.Durham \
-	@srcdir@/Documentation/Examples.Fyn \
+	@srcdir@/Documentation/Examples.Fyn 
-	@srcdir@/Demos/Scripts
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp

Documentation/man8/arangod

@@ -10,6 +10,8 @@ clients to connect to it via the network. The server also has
 an emergency console mode that can be used for any sort of
 maintenance operations. In the emergency console mode, the 
 server does not allow any clients to connect.
+The server can be stopped gracefully at any time by pressing 
+CTRL-C or by sending the SIGINT signal to the process.
 OPTIONS
 The COMMAND binary has many options that can be used to control
 its behavior. 

Doxygen/man/man1/arangoimp.1

@@ -1,4 +1,4 @@
-.TH arangoimp 1 "Mo 3. Sep 15:33:27 CEST 2012" "" "ArangoDB"
+.TH arangoimp 1 "Di 4. Sep 11:48:53 CEST 2012" "" "ArangoDB"
 .SH NAME
 arangoimp - a bulk importer for the ArangoDB database
 .SH SYNOPSIS

Doxygen/man/man1/arangosh.1

@@ -1,4 +1,4 @@
-.TH arangosh 1 "Mo 3. Sep 15:33:27 CEST 2012" "" "ArangoDB"
+.TH arangosh 1 "Di 4. Sep 11:48:54 CEST 2012" "" "ArangoDB"
 .SH NAME
 arangosh - the ArangoDB shell
 .SH SYNOPSIS

Doxygen/man/man8/arango-dfdb.8

@@ -1,4 +1,4 @@
-.TH arango-dfdb 8 "Mo 3. Sep 15:33:27 CEST 2012" "" "ArangoDB"
+.TH arango-dfdb 8 "Di 4. Sep 11:48:54 CEST 2012" "" "ArangoDB"
 .SH NAME
 arango-dfdb - a datafile debugger for ArangoDB
 .SH SYNOPSIS

Doxygen/man/man8/arango-password.8

@@ -1,4 +1,4 @@
-.TH arango-password 8 "Mo 3. Sep 15:33:27 CEST 2012" "" "ArangoDB"
+.TH arango-password 8 "Di 4. Sep 11:48:54 CEST 2012" "" "ArangoDB"
 .SH NAME
 arango-password - user setup utility for the ArangoDB database server
 .SH SYNOPSIS

Doxygen/man/man8/arango-upgrade.8

@@ -1,4 +1,4 @@
-.TH arango-upgrade 8 "Mo 3. Sep 15:33:27 CEST 2012" "" "ArangoDB"
+.TH arango-upgrade 8 "Di 4. Sep 11:48:54 CEST 2012" "" "ArangoDB"
 .SH NAME
 arango-upgrade - upgrade script for the ArangoDB database server
 .SH SYNOPSIS

Doxygen/man/man8/arangod.8

@@ -1,4 +1,4 @@
-.TH arangod 8 "Mo 3. Sep 15:33:27 CEST 2012" "" "ArangoDB"
+.TH arangod 8 "Di 4. Sep 11:48:54 CEST 2012" "" "ArangoDB"
 .SH NAME
 arangod - the ArangoDB database server
 .SH SYNOPSIS
@@ -10,6 +10,8 @@ clients to connect to it via the network. The server also has
 an emergency console mode that can be used for any sort of
 maintenance operations. In the emergency console mode, the 
 server does not allow any clients to connect.
+The server can be stopped gracefully at any time by pressing 
+CTRL-C or by sending the SIGINT signal to the process.
 .SH OPTIONS
 The arangod binary has many options that can be used to control
 its behavior. 

Doxygen/man/man8/rcarangod.8

@@ -1,4 +1,4 @@
-.TH rcarangod 8 "Mo 3. Sep 15:33:27 CEST 2012" "" "ArangoDB"
+.TH rcarangod 8 "Di 4. Sep 11:48:54 CEST 2012" "" "ArangoDB"
 .SH NAME
 rcarangod - control script for the ArangoDB database server
 .SH SYNOPSIS

Makefile.files

@@ -81,7 +81,6 @@ WIKI = \
 	DbaManualAuthentication \
 	DbaManualDatafileDebugger \
 	DefineAction \
-	ExamplesSetup \
 	FirstStepsArangoDB \
 	Glossary \
 	Graphs \

Makefile.in

@@ -1248,7 +1248,6 @@ WIKI = \
 	DbaManualAuthentication \
 	DbaManualDatafileDebugger \
 	DefineAction \
-	ExamplesSetup \
 	FirstStepsArangoDB \
 	Glossary \
 	Graphs \

arangod/Documentation/dba-manual.dox

@@ -84,8 +84,12 @@
 ///////////////////////////////////////////////////////////////
 ///
 /// Database documents are stored in memory-mapped files. Per default, these
-/// memory-mapped files are synced frequently - storing all documents securely
+/// memory-mapped files are synced regularly but not instantly. This is often a
-/// at once (durability).
+/// good tradeoff between storage performance and durability. If this level of
+/// durabiity is too low for an application, the server can also sync all
+/// modifications to disk instantly. This will give full durability but will come
+/// with a performance penalty as each data modification will trigger a sync
+/// I/O operation.
 ///
 /// @section DbaManualBasicsMvcc AppendOnly/MVCC
 ////////////////////////////////////////////////
@@ -163,14 +167,14 @@
 ///
 /// @EMBEDTOC{DbaManualDatafileDebuggerTOC}
 ///
-/// AranagoDB uses append-only journals. The corruption should only occur when
+/// AranagoDB uses append-only journals. Data corruption should only occur when
-/// the database server is kill. In this case, the corruption should only
+/// the database server is killed. In this case, the corruption should only
 /// occur in the last object(s) being written to the journal.
 ///
 /// If a corruption occurs within a normal datafile, then this can only happen
 /// if a hardware fault occurred.
 ///
-/// If a journal or datafile is corrupt, shutdown the database server and start
+/// If a journal or datafile is corrupt, shut down the database server and start
 /// the program
 ///
 /// @LIT{arango-dfdb}

arangod/Documentation/examples-setup.dox

@@ -1,87 +0,0 @@
-////////////////////////////////////////////////////////////////////////////////
-/// @brief over the wire protocol
-///
-/// @file
-///
-/// DISCLAIMER
-///
-/// Copyright 2012 triagens GmbH, Cologne, Germany
-///
-/// Licensed under the Apache License, Version 2.0 (the "License");
-/// you may not use this file except in compliance with the License.
-/// You may obtain a copy of the License at
-///
-///     http://www.apache.org/licenses/LICENSE-2.0
-///
-/// Unless required by applicable law or agreed to in writing, software
-/// distributed under the License is distributed on an "AS IS" BASIS,
-/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-/// See the License for the specific language governing permissions and
-/// limitations under the License.
-///
-/// Copyright holder is triAGENS GmbH, Cologne, Germany
-///
-/// @author Dr. Frank Celler
-/// @author Copyright 2012, triAGENS GmbH, Cologne, Germany
-////////////////////////////////////////////////////////////////////////////////
-
-////////////////////////////////////////////////////////////////////////////////
-/// @page ExamplesSetup Preparing the Examples
-///
-/// Some examples in the manuals assume that you have created the following
-/// collections:
-///
-/// - demo
-/// - five
-/// - geo
-///
-/// Some of the examples may destroy the collection. In that case you can
-/// use one of the following script to restore the collection.
-///
-/// @LIT{examples.js}: A JavaScript script usable within the ArangoDB shell to
-/// regenerate the above collections.
-///
-/// @LIT{examples.sh}: A shell script using curl to setup the collections. The
-/// script works without any additional client, but will not be able to detect
-/// any errors.
-///
-/// @section ExamplesSetupDemo Collection "demo"
-////////////////////////////////////////////////
-///
-/// @verbinclude demo1
-///
-/// was generated by
-///
-/// @verbinclude demo.js
-///
-/// @section ExamplesSetupFive Collection "five"
-////////////////////////////////////////////////
-///
-/// The collection "five" has a unique constraint on the attribute @LIT{a},
-/// and a second unique constraint on the attribute @LIT{b}.
-///
-/// @verbinclude five1
-///
-/// was generated by
-///
-/// @verbinclude five.js
-///
-/// @section ExamplesSetupGeo Collection "geo"
-//////////////////////////////////////////////
-///
-/// The collection "geo" has two geo fields, one @LIT{home} being a list with
-/// two elements, one @LIT{work} being an hash array with latitude @LIT{b} and
-/// longitude @LIT{l}.
-///
-/// @verbinclude geojs1
-///
-/// was generated by
-///
-/// @verbinclude geo.js
-////////////////////////////////////////////////////////////////////////////////
-
-// Local Variables:
-// mode: c++
-// mode: outline-minor
-// outline-regexp: "^\\(/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|// --SECTION--\\|/// @page\\|/// @\\}\\)"
-// End:

arangod/Documentation/install-manual.dox

@@ -468,7 +468,7 @@
 /// - the GNU ncurses library in version 5 or 6
 /// - boost header files, at least version 1.33
 ///
-/// To compile Google V8 yourself, you will also need SCons.
+/// To compile Google V8 yourself, you will also need Python 2 and SCons.
 ///
 /// Some distributions, for example Centos 5, provide only very out-dated
 /// versions of FLEX, BISON, and the V8 engine. In that case you need to compile

arangod/Documentation/rest-document.dox

@@ -74,9 +74,6 @@
 /// All documents contain two special fields, the document handle in @LIT{_id}
 /// and the etag aka document revision in @LIT{_rev}.
 ///
-/// Some examples in the manual assume that you have created some example
-/// collections, see @ref ExamplesSetup.
-///
 /// @copydoc GlossaryDocumentHandle
 ///
 /// @copydoc GlossaryDocumentIdentifier

arangod/Documentation/shell-document.dox

@@ -88,9 +88,6 @@
 /// All documents contain two special fields, the document handle in @LIT{_id}
 /// and the etag aka document revision in @LIT{_rev}.
 ///
-/// Some examples in the manual assume that you have created some example
-/// collections, see @ref ExamplesSetup.
-///
 /// @copydoc GlossaryDocumentHandle
 ///
 /// @copydoc GlossaryDocumentIdentifier

arangod/Documentation/user-manual.dox

@@ -154,14 +154,18 @@
 ///////////////////////////////////////////////////////////////////
 ///
 /// The ArangoDB database server has two modes of operation: as server, where it
-/// will answer to client requests and an emergency console, in which you can
+/// will answer to client requests, and an emergency console, in which you can
 /// access the database directly. The latter - as the name suggests - should 
 /// only be used in case of an emergency, for example, a corrupted
 /// collection. Using the emergency console allows you to issue all commands
-/// normally available in actions and transactions.
+/// normally available in actions and transactions. When starting the server in
+/// emergency console mode, the server cannot handle any client requests.
 ///
-/// You should never start more than one server for the same database,
+/// You should never start more than one server using the same database directory,
-/// independent from the mode of operation.
+/// independent from the mode of operation. Normally ArangoDB will prevent
+/// you from doing this by placing a lockfile in the database directory and
+/// not allowing a second ArangoDB instance to use the same database directory
+/// if a lockfile is already present.
 ///
 /// The following command starts the ArangoDB database in server mode. You will
 /// be able to access the server using HTTP requests on port 8529. See @ref
@@ -176,6 +180,17 @@
 ///
 /// to access the administration front-end.
 ///
+/// To start the server at system boot time, you should use one of the 
+/// pre-rolled packages that will install the necessary start / stop
+/// scripts for ArangoDB.
+///
+/// If you started the server process manually, you can stop the database
+/// server gracefully by either pressing CTRL-C or by sending the SIGINT
+/// signal to the server process. On many systems, this can be achieved with
+/// the following command:
+///
+/// @LIT{kill -2 `pidof arangod`}
+///
 /// @subsection UserManualServerStartStopOptions Frequently Used Options
 ////////////////////////////////////////////////////////////////////////
 ///