From 86d58c241d86c78c64b367967cd0257768b4ea37 Mon Sep 17 00:00:00 2001 From: CoDEmanX Date: Sat, 5 Sep 2015 03:33:55 +0200 Subject: [PATCH] Remove doc building readme, fix typos --- .../Books/Users/FirstSteps/README.mdpp | 2 +- Documentation/Books/Users/README.mdpp | 2 +- Documentation/Books/readme.txt | 5 --- README | 8 ++-- README.md | 6 +-- README.windows | 14 +++--- README_maintainers.md | 44 +++++++++---------- js/node/node_modules/js-yaml/CHANGELOG.md | 4 +- 8 files changed, 40 insertions(+), 45 deletions(-) delete mode 100644 Documentation/Books/readme.txt diff --git a/Documentation/Books/Users/FirstSteps/README.mdpp b/Documentation/Books/Users/FirstSteps/README.mdpp index 6136f3ed29..33d9d9fb0e 100644 --- a/Documentation/Books/Users/FirstSteps/README.mdpp +++ b/Documentation/Books/Users/FirstSteps/README.mdpp @@ -27,7 +27,7 @@ Key features include: * *Transactions*: Run queries on multiple documents or collections with optional transactional consistency and isolation * *Replication*: Set up the database in a master-slave configuration -* It is open source (*Apache Licence 2.0*) +* It is open source (*Apache License 2.0*) For more in-depth information: diff --git a/Documentation/Books/Users/README.mdpp b/Documentation/Books/Users/README.mdpp index dbeee3d2c1..5d4a748330 100644 --- a/Documentation/Books/Users/README.mdpp +++ b/Documentation/Books/Users/README.mdpp @@ -19,7 +19,7 @@ Key features include: * **Powerful query language** (AQL) to retrieve and modify data * **Transactions**: run queries on multiple documents or collections with optional transactional consistency and isolation * **Replication** and **Sharding**: set up the database in a master-slave configuration or spread bigger datasets across multiple servers -* It is **open source** (Apache Licence 2.0) +* It is **open source** (Apache License 2.0) In this documentation you can inform yourself about all the functions, features and programs ArangoDB provides for you. diff --git a/Documentation/Books/readme.txt b/Documentation/Books/readme.txt deleted file mode 100644 index a09eb4dec8..0000000000 --- a/Documentation/Books/readme.txt +++ /dev/null @@ -1,5 +0,0 @@ -How to generate the documentation: - -1. Install markdown-pp from our repository (https://github.com/triAGENS/markdown-pp) -2. Install gitbook (https://github.com/GitbookIO/gitbook) -3. Run "make" in this folder diff --git a/README b/README index bf6a582700..dd3132db50 100644 --- a/README +++ b/README @@ -6,7 +6,7 @@ convenient SQL-like query language or JavaScript extensions. Use ACID transactions if you require them. Scale horizontally with a few mouse clicks. The supported data models can be mixed in queries and allow ArangoDB to be the aggregation point for your data. -To get started, try one of our 10 minutes tutorials in your favourite +To get started, try one of our 10 minutes tutorials in your favorite programming language or try one of our ArangoDB_Cookbook_recipes. For the impatient: download and install ArangoDB. Start the server arangod and point your browser to http://127.0.0.1:8529/. @@ -25,7 +25,7 @@ Here is an AQL query that makes use of all those features: AQL Query Example AQL Query Example Joins and transactions are key features for flexible, secure data designs, widely used in relational databases but lacking in many NoSQL products. -However, there is no need to forego them in ArangoDB. You decide how and when +However, there is no need to forget them in ArangoDB. You decide how and when to use joins and strong consistency guarantees, without sacrificing performance and scalability. Furthermore, ArangoDB offers a JavaScript framework called Foxx that is @@ -46,7 +46,7 @@ Other features of ArangoDB include: * JavaScript for all: no language zoo, you can use one language from your browser to your back-end * ArangoDB is multi-threaded - exploit the power of all your cores -* Flexible data modelling: model your data as combination of key-value pairs, +* Flexible data modeling: model your data as combination of key-value pairs, documents or graphs - perfect for social relations * Free index choice: use the correct index for your problem, be it a skip list or a fulltext search @@ -57,7 +57,7 @@ Other features of ArangoDB include: transactional consistency and isolation * Replication and Sharding: set up the database in a master-slave configuration or spread bigger datasets across multiple servers -* It is open source (Apache Licence 2.0) +* It is open source (Apache License 2.0) For more in-depth information read the design_goals_of_ArangoDB diff --git a/README.md b/README.md index b098a0c036..6931d5c046 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ ArangoDB is a multi-model, open-source database with flexible data models for do The supported data models can be mixed in queries and allow ArangoDB to be the aggregation point for your data. -To get started, try one of our 10 minutes [tutorials](https://www.arangodb.com/tutorials) in your favourite programming language or try one of our [ArangoDB Cookbook recipes](https://docs.arangodb.com/cookbook). +To get started, try one of our 10 minutes [tutorials](https://www.arangodb.com/tutorials) in your favorite programming language or try one of our [ArangoDB Cookbook recipes](https://docs.arangodb.com/cookbook). For the impatient: [download](https://www.arangodb.com/download) and install ArangoDB. Start the server `arangod` and point your browser to `http://127.0.0.1:8529/`. @@ -48,13 +48,13 @@ Other features of ArangoDB include: * Use a **data-centric microservices** approach with ArangoDB Foxx and fuse your application-logic and database together for maximal throughput * JavaScript for all: **no language zoo**, you can use one language from your browser to your back-end * ArangoDB is **multi-threaded** - exploit the power of all your cores -* **Flexible data modelling**: model your data as combination of key-value pairs, documents or graphs - perfect for social relations +* **Flexible data modeling**: model your data as combination of key-value pairs, documents or graphs - perfect for social relations * Free **index choice**: use the correct index for your problem, be it a skip list or a fulltext search * Configurable **durability**: let the application decide if it needs more durability or more performance * **Powerful query language** (AQL) to retrieve and modify data * **Transactions**: run queries on multiple documents or collections with optional transactional consistency and isolation * **Replication** and **Sharding**: set up the database in a master-slave configuration or spread bigger datasets across multiple servers -* It is **open source** (Apache Licence 2.0) +* It is **open source** (Apache License 2.0) For more in-depth information read the [design goals of ArangoDB](http://www.arangodb.com/2012/03/07/avocadodbs-design-objectives) diff --git a/README.windows b/README.windows index b5cee89f29..b598af42b1 100644 --- a/README.windows +++ b/README.windows @@ -13,16 +13,16 @@ that ArangoDB has been installed in the location . You have to be careful when choosing an installation directory. You need either - write permission to this directoy or you need to modify the config file for the + write permission to this directory or you need to modify the config file for the server process. In the latter case the database directory and the Foxx directory should must be writable by the user. - Installating for a single user: + Installation for a single user: Select a different directory during installation. For example `C:/Users//arangodb` or `C:/ArangoDB`. - Installating for multiple users: + Installation for multiple users: Keep the default directory. After the installation edit the file `/etc/arangodb/arangod.conf`. Adjust the `directory` and `app-path` @@ -36,7 +36,7 @@ Create the directories for each user that wants to use ArangoDB. - Installating as Service + Installation as Service Keep the default directory. After the installation open a command line as administrator (search for `cmd` and right click `run as administrator`) @@ -67,7 +67,7 @@ by default. Please check the output of the `arangod.exe` executable before going on. If - the server started successully, you should see a line `ArangoDB is ready for + the server started successfully, you should see a line `ArangoDB is ready for business. Have fun!` at the end of its output. We now wish to check that the installation is working correctly and to do @@ -76,7 +76,7 @@ to the page: http://127.0.0.1:8529/ To check if your installation was successful, click the `Collection` tab and - open the configutation. Select the `System` TYPE. If the installation was + open the configuration. Select the `System` TYPE. If the installation was successful, then the page should display a few system collections. Try to add a new collection and then add some documents to this new @@ -119,7 +119,7 @@ 7) To uninstall the Arango server application you can use the windows control panel (as you would normally uninstall an application). Note however, that any data files created by the Arango server will remain as well as the - directory. To complete the uninstallation process, remove the data files and + directory. To complete the deinstallation process, remove the data files and the directory manually. If you have any questions regarding the installation or other matters please use diff --git a/README_maintainers.md b/README_maintainers.md index cb55f82c47..772a40352f 100644 --- a/README_maintainers.md +++ b/README_maintainers.md @@ -36,7 +36,7 @@ Runtime Startup ------- -We now have a startup rc file: ~/.arangod.rc . Its evaled as javascript. +We now have a startup rc file: ~/.arangod.rc . It's evaled as javascript. A sample version to help working with the arangod rescue console may look like that: ENABLE_NATIVE_BACKTRACES(true); @@ -67,11 +67,11 @@ to lint your modified files. make jslint -to find out whether all of your files comply to jslint. This is required to make contineous integration work smoothly. +to find out whether all of your files comply to jslint. This is required to make continuous integration work smoothly. if you want to add new files / patterns to this make target, edit js/Makefile.files -to be safe from commiting non-linted stuff add **.git/hooks/pre-commit** with: +to be safe from committing non-linted stuff add **.git/hooks/pre-commit** with: make gitjslint @@ -115,7 +115,7 @@ These tests are disabled. You may however want to run them by hand. replication ----------- (only applies to ruby tests) -These tests aren't run automaticaly since they require a manual set up environment. +These tests aren't run automatically since they require a manual set up environment. -spec ----- @@ -316,11 +316,11 @@ For the average *nix user windows debugging has some awkward methods. Coredump generation ------------------- -Coredumps can be created using the task manager; switch it to detail view, the context menu offers to *create dump file*; the generated file ends in a directory that explorer hides from you - AppData - you have to type that in the location bar. This however only for running processes which is not as usefull as having dumps of crashing processes. While its a common feature to turn on coredumps with the system facilities on *nix systems, its not as easy in windows. You need an external program [from the Sysinternals package: ProcDump](https://technet.microsoft.com/en-us/sysinternals/dd996900.aspx). First look up the PID of arangod, you can finde it in the brackets in its logfile. Then call it like this: +Coredumps can be created using the task manager; switch it to detail view, the context menu offers to *create dump file*; the generated file ends in a directory that explorer hides from you - AppData - you have to type that in the location bar. This however only for running processes which is not as useful as having dumps of crashing processes. While its a common feature to turn on coredumps with the system facilities on *nix systems, its not as easy in windows. You need an external program [from the Sysinternals package: ProcDump](https://technet.microsoft.com/en-us/sysinternals/dd996900.aspx). First look up the PID of arangod, you can finde it in the brackets in its logfile. Then call it like this: procdump -accepteula -e -ma < PID of arangod > -It will keep on running and monitor arangod until eventually a crash happenes. You will then get a core dump if an incident occurs or *Dump count not reached.* if nothing happened, *Dump count reached.* if a dump was written - the filename will be printed above. +It will keep on running and monitor arangod until eventually a crash happens. You will then get a core dump if an incident occurs or *Dump count not reached.* if nothing happened, *Dump count reached.* if a dump was written - the filename will be printed above. Debugging symbols ----------------- @@ -350,28 +350,28 @@ Where... generate -------- - - make examples - on toplevel to generate Documentation/Examples + - make examples - on top level to generate Documentation/Examples - make examples FILTER_EXAMPLE=geoIndexSelect will only produce one example - *geoIndexSelect* - make examples FILTER_EXAMPLE='MOD.*' will only produce the examples matching that regex - - make examples server.endpoint=tcp://127.0.0.1:8529 will utilize an existing arangod instead of starting anown. + - make examples server.endpoint=tcp://127.0.0.1:8529 will utilize an existing arangod instead of starting a new one. this does seriously cut down the execution time. - - alternatively you can use generateExamples (i.e. on windows since the make taregt is not portable) like that: + - alternatively you can use generateExamples (i.e. on windows since the make target is not portable) like that: ./scripts/generateExamples --server.endpoint 'tcp://127.0.0.1:8529' --withPython 3rdParty/V8-4.3.61/third_party/python_26/python26.exe --onlyThisOne 'MOD.*' - - make swagger - on toplevel to generate the documentation interactively with the server + - make swagger - on top level to generate the documentation interactively with the server - cd Documentation/Books; make - to generate the HTML documentation write markdown -------------- -mdpp files are used for the structure. To join it with parts extracted from the programm documentation +mdpp files are used for the structure. To join it with parts extracted from the program documentation you need to place hooks: - `@startDocuBlock <docuBlockName>` is replaced by a Docublock extracted from source. - `@startDocuBlockInline <docuBlockName>` till `@endDocuBlock <docuBlockName>` is replaced in with its own evaluated content - so *@EXAMPLE_ARANGOSH_OUTPUT* sections are executed - the same way as inside of sourcecode documentation. + the same way as inside of source code documentation. read / use the documentation ---------------------------- @@ -386,34 +386,34 @@ arangod Example tool To update Heres how its details work: - all ending with *.cpp*, *.js* and *.mdpp* are searched. - - all lines inside of sourcecode starting with '///' are matched, all lines in .mdpp files. + - all lines inside of source code starting with '///' are matched, all lines in .mdpp files. - an example start is marked with *@EXAMPLE_ARANGOSH_OUTPUT* or *@EXAMPLE_ARANGOSH_RUN* - the example is named by the string provided in brackets after the above key - the output is written to *Documentation/Examples/.generated* - examples end with *@END_EXAMPLE_[OUTPUT|RUN]* - - all code inbetween is executed as javascript in the **arangosh** while talking to a valid **arangod**. + - all code in between is executed as javascript in the **arangosh** while talking to a valid **arangod**. -OUTPUT and RUN Specialities +OUTPUT and RUN specifics --------------------------- By default, Examples should be self contained and thus not depend on each other. They should clean up the collections they create. Building will fail if resources aren't cleaned. -However, if you intend a set of OUTPUT and RUN to demonstrate interactively, you have to use an alphabeticaly sorteable -namingscheme so they're executed in sequence. Using _[abcd]_thisDoesThat seems to be a good scheme. +However, if you intend a set of OUTPUT and RUN to demonstrate interactively, you have to use an alphabetical sortable +naming scheme so they're executed in sequence. Using _[abcd]_thisDoesThat seems to be a good scheme. - OUTPUT is intended to create samples that the users can cut'n'paste into their arangosh. Its used for javascript api documentation. * wrapped lines: Lines starting with a pipe ('/// |') are joined together with the next following line. - You have to do this, if you want to execute loops, functions or commands which shouldn't be torn appart by the framework. + You have to do this, if you want to execute loops, functions or commands which shouldn't be torn apart by the framework. * Lines starting with *var*: The command behaves similar to the arangosh: the server reply won't be printed. - Hovever, the variable will be in the scope of the other lines - else it won't. + However, the variable will be in the scope of the other lines - else it won't. * Lines starting with a Tilde ('/// ~'): - These lines can be used for setup/teardown purposes. They are completely invisible in the generated example transscript. + These lines can be used for setup/teardown purposes. They are completely invisible in the generated example transcript. * ~removeIgnoreCollection("test") - the collection test may live across several tests. * ~addIgnoreCollection("test") - the collection test will again be alarmed if left over. - - it is excuted line by line. If a line is intended to fail (aka throw an exception), + - it is executed line by line. If a line is intended to fail (aka throw an exception), you have to specify *// xpError(ERROR_ARANGO_DOCUMENT_KEY_UNEXPECTED)* so the exception will be caught; else the example is marked as broken. If you need to wrap that line, you may want to make the next line like this to suppress an empty line: @@ -422,7 +422,7 @@ namingscheme so they're executed in sequence. Using _