Documentation: reviewed and updated

Some fixes:
* document title
* gitbook-plugin-richquotes disabled due to bad rendering
* TOC titles and ordering

Change-Id: I09b133f45a32b179ca4d1e8e13ea3b1e2fdb795b

8 files changed, 53 insertions, 50 deletions

diff --git a/docs/2-Installation.md b/docs/2-Installation.md
index d813bf75..f2823b64 100644
--- a/docs/2-Installation.md
+++ b/docs/2-Installation.md
@@ -1,12 +1,12 @@
 # Prerequisites
 
-- An AGL system installed with latest Chinook version (>3.0.2).
+* An AGL system installed with latest Chinook version \(>3.0.2\).
 
-- Make sure you built the AGL generator else you will not be able to generate custom low-level CAN binding. Generator can be found [here](http://github.com/iotbzh/can-config-generator) with the attached instruction to install and run it.
+* Make sure you built the AGL generator else you will not be able to generate custom low-level CAN binding. Generator can be found [here](http://github.com/iotbzh/can-config-generator) with the attached instruction to install and run it.
 
-It will produce a *configuration-generated.cpp* file to paste in the source, *src/*, directory.
+It will produce a _configuration-generated.cpp_ file to paste in the source, _src/_, directory.
 
-- Make sure you already set up the AGL SDK using the following [guide](http://docs.iot.bzh/docs/getting_started/en/dev/reference/setup-sdk-environment.html).
+* Make sure you already set up the AGL SDK using the following [guide](http://docs.iot.bzh/docs/getting_started/en/dev/reference/setup-sdk-environment.html).
 
 To get the correct SDK version installed, you **must** prepare your environment with the **chinook-next** version. To do so, run the following command in your docker image:
 
@@ -14,14 +14,14 @@ To get the correct SDK version installed, you **must** prepare your environment
 $ prepare_meta -f chinook-next -o /xdt -l /home/devel/mirror -p /home/devel/share/proprietary-renesas-rcar/ -t porter -e wipeconfig -e rm_work
 ```
 
-- Check that you updated git submodules, executing the following commands from this repository:
+* Check that you updated git submodules, executing the following commands from this repository:
 
 ```bash
 $ git submodule init
 $ git submodule update
 ```
 
-- An [USB CAN adapter](http://shop.8devices.com/usb2can) connected to OBD2 connector through the [right cable](http://www.mouser.fr/ProductDetail/EasySync/OBD-M-DB9-F-ES/)).
+* An [USB CAN adapter](http://shop.8devices.com/usb2can) connected to OBD2 connector through the [right cable](http://www.mouser.fr/ProductDetail/EasySync/OBD-M-DB9-F-ES/)\).
 
 # Getting started
 
@@ -32,9 +32,9 @@ $ git submodule update
 * CMake version 3.0 or later
 * G++, Clang++ or any C++11 complient compiler.
 * Boost
-    * filesystem
-    * program_options
-    * system
+  * filesystem
+  * program\_options
+  * system
 
 You can install any of these using your package manager. For instance, inside the iotbzh's docker image, you must enter this command :
 
@@ -54,7 +54,7 @@ remote: Compressing objects: 100% (42/42), done.
 remote: Total 74 (delta 30), reused 67 (delta 27), pack-reused 0
 Unpacking objects: 100% (74/74), done.
 Checking connectivity... done.
-	
+
 <b>devel@bsp-devkit:~/projects/$</b> cd can-config-generator
 <b>devel@bsp-devkit:~/projects/can-config-generator/(master)$</b> mkdir build
 <b>devel@bsp-devkit:~/projects/can-config-generator/build(master)$</b> cmake -G "Unix Makefiles" ..
@@ -98,21 +98,21 @@ To generate your config file you just have to run the generator using the `-m` o
 $ can-config-generator -m ../tests/basic.json -o configuration-generated.cpp
 ```
 
-If you omit the `-o` option, then code is generated on the stdout.
-You also can specify a header and a footer file.
-These files must be valid C++ fragment as long as they will be inserted as is.
+If you omit the `-o` option, then code is generated on the stdout.  
+You also can specify a header and a footer file.  
+These files must be valid C++ fragment as long as they will be inserted as is.  
 Use the `-h` option to display help.
 
-> **CAUTION** Each `diagnostic_message` must define the same `bus` as the binding will use only one bus.
+> **CAUTION:** Each `diagnostic_message` must define the same `bus` as the binding will use only one bus.
 
 ### Supported OpenXC items
 
-About now, compliance with OpenXC reference is in progress, can-config-generator and CAN_signaling will implement them soon.
+About now, compliance with OpenXC reference is in progress, can-config-generator and CAN\_signaling will implement them soon.  
 `initializers`, `loopers`, `commands` and `handlers` nodes are ignored for now.
 
 This generator will follow OpenXC support status of the low level CAN signaling binding.
 
-> **NOTE** The `buses` item will not be supported by this generator because the binding use another way to declare and configure buses. Please refer to the binding's documentation.
+> **NOTE**: The `buses` item will not be supported by this generator because the binding use another way to declare and configure buses. Please refer to the binding's documentation.
 
 ## Compile and install the binding
 
@@ -153,9 +153,9 @@ Error org.freedesktop.DBus.Error.Failed: "system error"
 
 It's because installation remove the binding before installing it.
 
-If it is the first time that you make the installation then you'll have this message in place of ***true***.
+If it is the first time that you make the installation then you'll have this message in place of _**true**_.
 
-To install it manually, you need to copy the *low-can-binding.wgt* file on your target, then from it execute the following commands :
+To install it manually, you need to copy the _low-can-binding.wgt_ file on your target, then from it execute the following commands :
 
 On your host, to copy over the network :
 
@@ -163,9 +163,12 @@ On your host, to copy over the network :
 $ scp low-can-binding.wgt root@<target_IP>:~
 ```
 
-On the target, assuming ***wgt*** file is in the root home directory :
+On the target, assuming _**wgt**_ file is in the root home directory :
 
 ```bash
 ~# afm-util install low-can-binding.wgt
 { "added": "low-can-binding@0.1" }
 ```
+
+
+
diff --git a/docs/3-Usage.md b/docs/3-Usage.md
index 00dace09..7c0a4f15 100644
--- a/docs/3-Usage.md
+++ b/docs/3-Usage.md
@@ -1,6 +1,6 @@
 # Install AFB Websocket CLI client to test the binding.
 
-You can test it using afb-client-demo CLI tool provided by the RPM package *libafbwsc-dev*.
+You can test it using afb-client-demo CLI tool provided by the RPM package _libafbwsc-dev_.
 
 You can find this package in your build environment, using docker SDK recommended setup the file is `/xdt/build/tmp/deploy/rpm/<your-target-arch>/`.
 
@@ -18,7 +18,7 @@ From the docker image copy RPM to the shared directory between docker image and
 $ cp /xdt/build/tmp/deploy/rpm/cortex15hf_neon/libafbwsc-dev-1.0-r0.cortexa15hf_neon.rpm ~/share
 ```
 
-Then plugin you SDcard in your Linux host (Windows can't read ext4 filesystem AGL runs on) and copy RPM file on it.
+Then plugin you SDcard in your Linux host \(Windows can't read ext4 filesystem AGL runs on\) and copy RPM file on it.
 
 From your host, identify SDcard block device node here it is **sdc** with the correct capacity automounted by the desktop manager:
 
@@ -48,7 +48,7 @@ sda
 
 Copy, still from your host:
 
-> **CAUTION** Make sure to sync IO with sync command before unplug your SDcard. It could be corrupted if removed before all pending IO aren't done.
+> **CAUTION:** Make sure to sync IO with sync command before unplug your SDcard. It could be corrupted if removed before all pending IO aren't done.
 
 ```bash
 $ sudo cp ~/devel/docker/share/libafbwsc-dev-1.0-r0.cortexa15hf_neon.rpm /run/media/claneys/97f418a5-612f-44e9-b968-a19505695151/home/root
@@ -61,19 +61,19 @@ Insert the modified SDcard in your Porter board and boot from it. You are ready
 
 ### Virtual CAN device
 
- Connected to the target, here is how to load the virtual CAN device driver and set up a new vcan device :
+Connected to the target, here is how to load the virtual CAN device driver and set up a new vcan device :
 
 ```bash
 # modprobe vcan
 # ip link add vcan0 type vcan
 # ip link set vcan0 up
- ```
+```
 
 ### CAN device using the USB CAN adapter
 
 Using real connection to CAN bus of your car using the USB CAN adapter connected to the OBD2 connector.
 
-Once connected, launch ```dmesg``` command and search which device to use :
+Once connected, launch `dmesg` command and search which device to use :
 
 ```bash
 # dmesg
@@ -110,11 +110,11 @@ This instruction assuming a speed of 500000kbps for your CAN bus, you can try ot
 
 ## Configure the binding
 
-Configure the binding specifying in the JSON configuration file the CAN device(s) that it will to connect to. Edit file */var/lib/afm/applications/low-can-binding/0.1/can_buses.json* and change the CAN device name to the one you have :
+Configure the binding specifying in the JSON configuration file the CAN device\(s\) that it will to connect to. Edit file _/var/lib/afm/applications/low-can-binding/0.1/can\_buses.json_ and change the CAN device name to the one you have :
 
 ```json
 {
-	"canbus":  "can0"
+    "canbus":  "can0"
 }
 ```
 
@@ -122,11 +122,11 @@ If you have several specify CAN bus devices use an array:
 
 ```json
 {
-	"canbus": [ "vcan0", "can0" ]
+    "canbus": [ "vcan0", "can0" ]
 }
 ```
 
-> **WARNING** Make sure the CAN bus(es) you specify in your configuration file match those specified in your generated source file with the [can-config-generator](http://github.com/iotbzh/can-config-generator).
+> **WARNING:** Make sure the CAN bus\(es\) you specify in your configuration file match those specified in your generated source file with the [can-config-generator](http://github.com/iotbzh/can-config-generator).
 
 ## Run it, test it, use it !
 
@@ -157,7 +157,7 @@ NOTICE: vcan0 device opened and reading {binding low-can}
 NOTICE: Initialized 1/1 can bus device(s) {binding low-can}
 ```
 
-On another terminal, connect to the binding using previously installed ***AFB Websocket CLI*** tool:
+On another terminal, connect to the binding using previously installed _**AFB Websocket CLI**_ tool:
 
 ```bash
 # afb-client-demo ws://localhost:1234/api?token=
@@ -165,11 +165,11 @@ On another terminal, connect to the binding using previously installed ***AFB We
 
 You will be on an interactive session where you can communicate directly with the binding API.
 
-The binding provides at this moment 2 verbs, *subscribe* and *unsubscribe*, which can take argument by a JSON **event** object.
+The binding provides at this moment 2 verbs, _subscribe_ and _unsubscribe_, which can take argument by a JSON **event** object.
 
-The argument value is the CAN message **generic_name** as described in the JSON file used to generate cpp file for the binding.
+The argument value is the CAN message **generic\_name** as described in the JSON file used to generate cpp file for the binding.
 
-To use the ***AFB Websocket CLI*** tool, a command line will be like the following :
+To use the _**AFB Websocket CLI**_ tool, a command line will be like the following :
 
 ```
 <api> <verb> <arguments>
@@ -177,15 +177,15 @@ To use the ***AFB Websocket CLI*** tool, a command line will be like the followi
 
 Where:
 
-- API : ***low-can***.
-- Verb : ***subscribe*** or ***unsubscribe***
-- Arguments : ***{ "event": "driver.doors.open" }***
+* API : _**low-can**_.
+* Verb : _**subscribe**_ or _**unsubscribe**_
+* Arguments : _**{ "event": "driver.doors.open" }**_
 
 ### Subscription and unsubscription
 
-You can ask to subscribe to chosen CAN event with a call to *subscribe* API verb with the CAN messages name as JSON argument.
+You can ask to subscribe to chosen CAN event with a call to _subscribe_ API verb with the CAN messages name as JSON argument.
 
-> **Note** If no argument is provided, then you'll subscribe to all signals at once.
+> **NOTE:** If no argument is provided, then you'll subscribe to all signals at once.
 
 For example from a websocket session:
 
@@ -194,7 +194,7 @@ low-can subscribe { "event": "doors.driver.open" }
 ON-REPLY 1:low-can/subscribe: {"jtype":"afb-reply","request":{"status":"success","uuid":"a18fd375-b6fa-4c0e-a1d4-9d3955975ae8"}}
 ```
 
-Subscription and unsubscription can take wildcard in their *event* value.
+Subscription and unsubscription can take wildcard in their _event_ value.
 
 To reveive all doors events :
 
@@ -203,15 +203,15 @@ low-can subscribe { "event" : "doors*" }
 ON-REPLY 1:low-can/subscribe: {"jtype":"afb-reply","request":{"status":"success","uuid":"511c872e-d7f3-4f3b-89c2-aa9a3e9fbbdb"}}
 ```
 
-Then you will receive an event each time a CAN message is decoded for the event named *doors.driver.open*
+Then you will receive an event each time a CAN message is decoded for the event named _doors.driver.open_
 
 ```json
 ON-EVENT low-can/messages.doors.driver.open({"event":"low-can\/messages.doors.driver.open","data":{"name":"messages.doors.driver.open","value":true},"jtype":"afb-event"})
 ```
 
-Notice that event shows you that the CAN event is named *messages.doors.driver.open* but you ask for event about *doors.driver.open*.
+Notice that event shows you that the CAN event is named _messages.doors.driver.open_ but you ask for event about _doors.driver.open_.
 
-This is because all CAN messages or diagnostic messages are prefixed by the JSON parent node name, **messages** for CAN messages and **diagnostic_messages** for diagnostic messages like OBD2.
+This is because all CAN messages or diagnostic messages are prefixed by the JSON parent node name, **messages** for CAN messages and **diagnostic\_messages** for diagnostic messages like OBD2.
 
 This will let you subscribe or unsubcribe to all signals at once, not recommended, and better make filter on subscribe operation based upon their type. Examples:
 
@@ -248,3 +248,6 @@ Send a custom message:
 ```bash
 # cansend can0 ID#DDDDAAAATTTTAAAA
 ```
+
+
+
diff --git a/docs/Doc-Revisions.md b/docs/Doc-Revisions.md
index 7fa0c64d..9f30d28a 100644
--- a/docs/Doc-Revisions.md
+++ b/docs/Doc-Revisions.md
@@ -3,4 +3,4 @@ Document revisions
 
 | Date        | Version | Designation                          | Author                  |
 |-------------|---------|--------------------------------------|-------------------------|
-| 20 Mar 2017 |   1.0   | Initial release                      | R. Forlot [ Iot.bzh ] <br> S. Douheret [ Iot.bzh ] |
+| 20 Mar 2017 |   1.0   | Initial release                      | R. Forlot [ Iot.bzh ] <br/> S. Douheret [ Iot.bzh ] |
diff --git a/docs/README.md b/docs/README.md
index eccf553e..a7897207 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,6 +1,4 @@
-# Low level CAN binding for AGL
-
-## Abstract
+# Abstract
 
 This project proposes a Low Level CAN Binding for AGL, with the following features:
 
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index f444d925..504de463 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -1,8 +1,7 @@
 # Summary
 
+* [Abstract](README.md)
 * [Document revisions](Doc-Revisions.md)
-
-* [Introduction](README.md)
 * [Architecture](1-Architecture.md)
 * [Installation](2-Installation.md)
 * [Usage](3-Usage.md)
diff --git a/docs/cover.jpg b/docs/cover.jpg
index 5ff907cb..4aee7c9f 100644
--- a/docs/cover.jpg
+++ b/docs/cover.jpg
diff --git a/docs/cover_small.jpg b/docs/cover_small.jpg
index fdab95af..72f4dcf9 100644
--- a/docs/cover_small.jpg
+++ b/docs/cover_small.jpg
diff --git a/docs/resources/make_cover.sh b/docs/resources/make_cover.sh
index 6494bd4c..bdbe414d 100755
--- a/docs/resources/make_cover.sh
+++ b/docs/resources/make_cover.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 
-cat cover.svg | sed -e 's/{title}/Low level CAN binder/' \
+cat cover.svg | sed -e 's/{title}/Low Level CAN binding/' \
     -e 's/font-size:87.5px/font-size:50px/g' \
     -e 's/{subtitle}//g' \
     -e 's/{version}/Version 1.0/g' \
@@ -11,4 +11,4 @@ inkscape --without-gui --export-png=../cover.jpg \
     --export-background="#ffffff" -w 1800 -h 2360 /tmp/cover.svg
 
 inkscape --without-gui --export-png=../cover_small.jpg \
-    --export-background="#ffffff" -w 200 -h 262 /tmp/cover.svg
\ No newline at end of file
+    --export-background="#ffffff" -w 200 -h 262 /tmp/cover.svg