[DOCS]: some updates and typos fixed

Author: Davide Faconti

docs/BT_basics.md

@@ -11,17 +11,24 @@ For instance, in a service-oriented architecture, the leaves would contain
 the "client" code that communicate with the "server" that performs the
 operation.
 
-![Leaf To Component Communication](images/LeafToComponentCommunication.png)
+In the following example, we can see two Actions executed in a sequence,
+`DetectObject` and `GraspObject`.
 
+![Leaf To Component Communication](images/LeafToComponentCommunication.png)
 
-The other nodes of the tree, those which are not leaves, control the 
+The other nodes of the tree, those which are __not leaves__, control the 
 "flow of execution".
 
-To better understand how this flow takes place , imagine a signal, that we will further
-call "__tick__"; it is executed at the __root__ of the tree and propagates through
-the branches until it reaches one or multiple leaves.
+To better understand how this control flow takes place , imagine a signal 
+called "__tick__"; it is executed at the __root__ of the tree and it propagates 
+through the branches until it reaches one or multiple leaves.
+
+!!! Note
+    The word __tick__ will be often used as a *verb* (to tick / to be ticked) and it means
+    
+    "To invoke the callback `tick()` called of a `TreeNode`".
 
-The `tick()` callback returns a `NodeStatus` that will be either:
+Then a `TreeNode` is ticked, it returns a `NodeStatus` that can be either:
 
 - __SUCCESS__
 - __FAILURE__
@@ -37,7 +44,7 @@ and they needs more time to return a valid result.
 This C++ library provides also the status __IDLE__; it means that the node is ready to
 start.
 
-The result of a node is propagated back to the parent, that will decide
+The result of a node is propagated back to its parent, that will decide
 which child should be ticked next or will return a result to its own parent.
 
 ## Types of nodes
@@ -57,7 +64,7 @@ alter the state of the system.
 ![UML hierarchy](images/TypeHierarchy.png)
 
 
-## Learn by example
+## Examples
 
 To better understand how a BehaviorTrees work, let's focus on some practical
 examples. For the sake of simplicity we will not take into account what happens
@@ -83,11 +90,11 @@ In short:
 
 - If a child returns SUCCESS, tick the next one.
 - If a child returns FAILURE, then no more children are ticked and the Sequence returns FAILURE.
-- If all the children return SUCCESS, then the Sequence returns SUCCESS too.
+- If __all__ the children return SUCCESS, then the Sequence returns SUCCESS too.
 
-??? warning "Exercise: find the bug! Expand to read the answer."
+!!! warning "Have you spotted the bug?"
     If the action __GrabBeer__ fails, the door of the 
-    fridge would remain open, since the last action __CloseDoor__ is skipped.
+    fridge would remain open, since the last action __CloseFridge__ is skipped.
 
 
 ### Decorators
@@ -113,14 +120,15 @@ __Apparently__, the branch on the right side means:
 
     If the door is closed, then try to open it.
     Try up to 3 times, otherwise give up and return FAILURE.
-
-      
-__But__ there is an error. Can you find it?
 
-??? warning "Exercise: find the bug! Expand to read the answer."
+But...
+    
+!!! warning "Have you spotted the bug?"
     If __DoorOpen__ returns FAILURE, we have the desired behaviour.
     But if it returns SUCCESS, the left branch fails and the entire Sequence
-    is interrupted. 
+    is interrupted.
+    
+    We will see later how we can improve this tree. 
 
 
 ### Second ControlNode: Fallback
@@ -140,37 +148,37 @@ In the next example, you can see how Sequence and Fallbacks can be combined:
 ![FallbackNodes](images/FallbackBasic.png)  
 
 
->In the door open?
+> Is the door open?
 >
-> I not, try to open the door.
+> If not, try to open the door.
 >
 > Otherwise, if you have a key, unlock and open the door.
 >
 > Otherwise, smash the door. 
 >
->If any of these actions succeeded, then enter the room.
+> If __any__ of these actions succeeded, then enter the room.
 
 ### "Fetch me a beer" revisited
 
-We can now improve the "Fetch Me a Beer" example, which leaves the door open 
-if the beer was not there.
+We can now improve the "Fetch Me a Beer" example, which left the door open 
+if the beer was not inside the fridge.
 
-We use the color "green" to represent nodes which will return
+We use the color "green" to represent nodes which return
 SUCCESS and "red" for those which return FAILURE. Black nodes are never executed. 
 
 ![FetchBeer failure](images/FetchBeerFails.png)
 
-
 Let's create an alternative tree that closes the door even when __GrabBeer__ 
 returns FAILURE.
 
 
 ![FetchBeer failure](images/FetchBeer.png)
 
-Both the trees will close the door of the fridge, eventually, but:
+Both these trees will close the door of the fridge, eventually, but:
 
 - the tree on the __left__ side will always return SUCCESS if we managed to
  open and close the fridge.
+ 
 - the tree on the __right__ side will return SUCCESS if the beer was there, 
 FAILURE otherwise.
 

docs/index.md

@@ -20,8 +20,37 @@ to visualize, record, replay and analyze state transitions.
 
 ![ReadTheDocs](images/ReadTheDocs.png)  
 
+## What is a Behavior Tree?
+
+A Behavior Tree (__BT__) is a way to structure the switching between different 
+tasks in an autonomous agent, such as a robot or a virtual entity in a computer game.
+
+BTs are a very efficient way of creating complex systems that are both modular and reactive. 
+These properties are crucial in many applications, which has led to the spread 
+of BT from computer game programming to many branches of AI and Robotics. 
+ 
+If you are already familiar with Finite State Machines (__FSM__), you will
+easily grasp most of the concepts but, hopefully, you will find that BTs
+are more expressive and easier to reason about.
+
+The main advantages of Behavior Trees, when compared to FSMs are:
+
+- __They are intrinsically Hierarchical__: this means that we can _compose_
+complex behaviors including entire trees as sub-branches of a bigger tree. 
+For instance, the behavior "Fetch Beer" may reuse in one of its nodes the tree
+"Grasp Object".
+
+- __Their graphical representation has a semantic meaning__: it is easier to 
+"read" a BT and understand the corresponding workflow. 
+State transitions in FSMs, by comparisons, are harder to understand
+both in their textual and graphical representation.    
+
+- __They are more expressive__: Ready to use ControlNodes and DecoratorNodes
+make possible to express more complex control flows. The user can extend the
+"vocabulary" with his/her own custom nodes.
+
 
-## The problem
+## "Ok, but WHY do we need BehaviorTrees (or FSM)?"
 
 Many software systems, being robotics a notable example, are inherently
 complex.
@@ -59,32 +88,3 @@ __Finite State Machines__ were created specifically with this goal in mind, but
 the recent years __Behavior Trees__ gained popularity, especially in the game industry.
 
 
-## What is a Behavior Tree?
-
-A Behavior Tree (__BT__) is a way to structure the switching between different 
-tasks in an autonomous agent, such as a robot or a virtual entity in a computer game.
-
-BTs are a very efficient way of creating complex systems that are both modular and reactive. 
-These properties are crucial in many applications, which has led to the spread 
-of BT from computer game programming to many branches of AI and Robotics. 
- 
-If you are already familiar with Finite State Machines (__FSM__), you will
-easily grasp most of the concepts but, hopefully, you will  find that BTs
-are more expressive and easier to reason about.
-
-The main advantages of Behavior Trees, when compared to FSMs are:
-
-- __They are intrinsically Hierarchical__: this means that we can _compose_
-complex behaviors including entire trees as sub-branches of a bigger tree. 
-For instance, the behavior "Fetch Beer" may reuse in one of its nodes the tree
-"Grasp Object".
-
-- __Their graphical representation has a semantic meaning__: it is easier to 
-"read" a BT and understand the corresponding workflow. 
-State transitions in FSMs, by comparisons, are harder to understand
-both in their textual and graphical representation.    
-
-- __They are more expressive__: Ready to use ControlNodes and DecoratorNodes
-make possible to express more complex control flows. The user can extend the
-"vocabulary" with his/her own custom nodes.
-

docs/tutorial_A_create_trees.md

@@ -45,10 +45,9 @@ As you can see:
 - The method __tick()__ is the place where the actual Action takes place.
 It must return a NodeStatus, i.e. RUNNING, SUCCESS or FAILURE. 
 
-- The method __halt()__ is used to stop an asynchronous Action. ApproachObject
+- The method __halt()__ is used to stop an __asynchronous Action__. ApproachObject
 doesn't need it.
 
- 
 Alternatively, we can use __dependecy injection__ to create a TreeNode given 
 a function pointer. 
 
@@ -184,7 +183,7 @@ We must first register our custom TreeNodes into the `BehaviorTreeFactory`
 The identifier used in the XML must coincide with those used to register
 the TreeNodes.
 
-The attribute "name" represent the name of the instance and it is optional.
+The attribute "name" represents the name of the instance and it is optional.
 
 
 ``` c++

docs/tutorial_B_node_parameters.md

@@ -35,7 +35,7 @@ Please note:
 - The __static__ method `requiredNodeParameters()` contains a single key/value pair.
   The string "default message" is the default value.
 
-- Parameters must be accessed using the method `getParam()`, preferably in the
+- Parameters must be accessed using the method `getParam()`, preferably inside the
 `tick()` method.
 
 ``` c++ hl_lines="5 9 18"
@@ -81,11 +81,16 @@ struct Pose2D
 ```
 
 If we want the method `getParam()` to be able to parse a string
-and store its value into a Pose2D, we must provide our own specialization
+and store its value into a `Pose2D`, we must provide our own template specialization
 of `convertFromString<T>()`.
 
-In this case, we want to represent Pose2D as three real numbers separated by 
-semicolons.
+In this case, the text representation of a `Pose2D` is three real numbers separated by 
+semicolons, like this:
+
+    "1.1;-2.32;0.4"
+
+Since this is a common pattern, the library provide the helper function `BT::splitString`.
+
 
 ``` c++ hl_lines="6"
 // use this namespace
@@ -111,13 +116,15 @@ template <> Pose2D BT::convertFromString(const std::string& key)
     }
 }
 
-} // end naespace
+} // end namespace
 ```
 
 We now define a __asynchronous__ ActionNode called __MoveBaseAction__.
 
+The method tick() of an `ActionNode` is executed in its own thread.
+
 The method `getParam()` will call the function `convertFromString<Pose2D>()` under the hood;
-alternatively, we can use the latter directly, for instance to convert the default
+alternatively, we can use the latter funtion directly, for instance to convert the default
 string "0;0;0" into a Pose2D.
 
 ``` c++ hl_lines="20 21 22 23 24"
@@ -175,9 +182,7 @@ private:
 
 ## NodeParameters in the XML
 
-
-To pass the parameter in the XML, use an attribute
-with the same name:
+To pass the parameter from a XML, use attributes:
 
 ``` XML
 <Sequence>

docs/tutorial_C_blackboard.md

@@ -1,18 +1,18 @@
 # Blackboards
 
-The blackboard is a a __key/value__ storage that can be shared by all the Nodes
+The blackboard is a a __key/value__ storage shared by all the Nodes
 of a tree.
 
 The __key__ is a string whilst the __value__ is a type-erased container (called `SafeAny::Any`) 
 that allows the user to store any C++ object and to cast it back to its original form.
 
-Contrariwise to `boost::any` and `std::any`, this container will also try to 
+Contrariwise to `boost::any` and `std::any`, `SafeAny::Any` will also try to 
 avoid common overflow and underflow errors.
 
-You can't cast a negative number into an `unsigned integer`,
+In fact, you can't cast a negative number into an `unsigned integer`,
 nor a very large number that exceeds 2^8 into a `char`. 
 
-If the __value__ is stored as a string, it will use `convertFromString<T>()`
+If the __value__ is stored as a string, the blackboard will use `convertFromString<T>()`
 to cast it to the type T (see [previous example](tutorial_B_node_parameters.md));
 
 The user can create his/her own Blackboards backend; it is possible, for instance,
@@ -61,9 +61,10 @@ Let's consider the following XML tree definition:
 The root SequenceStar will execute four actions:
 
 - `CalculateGoalPose` writes into the blackboard key "GoalPose".
-- The syntax `${...}` tells to `MoveBase` to read the goal from the key "GoalPose" in the blackboard.
+- The syntax `${...}` tells to `MoveBase` to read the goal at run-time from the blackboard;
+  they blackboard key is "GoalPose".
 - Alternatively, you can write a key/value pair into the blackboard using the built-in action `SetBlackboard`.
-- Similar to step 2. Pose2D is retrieved from "OtherGoal".  
+- Similar to step 2. Pose2D is retrieved from the key "OtherGoal".  
 
 !!! note
     For your information, __GoalPose__ is stored as a type erased Pose2D.

docs/tutorial_E_plugins.md

@@ -1,7 +1,7 @@
 # Plugins
 
-In the previous examples we linked the user-defined nodes where included
-and linked statically into out projects.
+In the previous examples the user-defined nodes where included
+and linked statically into out C++ projects.
 
 We used the `BehaviorTreeFactory` to registed manualy these custom TreeNodes.
 
@@ -12,11 +12,13 @@ pre-compiled __dynamic shared libraries, i.e. plugins__.
 
 Let's consider the [first tutorial](tutorial_A_create_trees.md).
 
-To do this we must encapsulate the registration of multiple TreeNodes into a single 
-function like this:
+To create a plugin we must encapsulate the registration of one or multiple TreeNodes 
+into a single function like this:
 
 ``` c++
-// This is a macro. Just deal with it.
+// This is a macro that defines a function with a single argument 
+// (BehaviorTreeFactory& factory)
+
 BT_REGISTER_NODES(factory)
 {
     static GripperInterface gi; // we can't have more than instance
@@ -34,18 +36,18 @@ BT_REGISTER_NODES(factory)
 !!! note
     This function must be placed in __.cpp__ file, not the header file.
     
-In this particular example we assume that BT_REGISTER_NODES and
+Here, we assume that BT_REGISTER_NODES and
 the definitions of our custom TreeNodes are all defined in the file __dummy_nodes.cpp__.
 
-If you compile the plugin using __cmake__, add the argument `SHARED` to
+When you use __cmake__ to compile a plugin, add the argument `SHARED` to
 `add_library`.
 
 ```cmake
 #your CMakeLists.txt
 add_library(dummy_nodes  SHARED dummy_nodes.cpp )
 ``` 
 
-In Linux the file __libdummy_nodes.so__ will be created.
+In Linux, the file __libdummy_nodes.so__ will be created.
 
 The [first tutorial](tutorial_A_create_trees.md) becomes, as a result, much simpler: