Updated Getting Started Guide.

docs/includes/nodes/show_in_viewport.rst

@@ -1,4 +1,4 @@
 
-- **Show in viewport** - If this option is enabled, the property will show up in the *Data Input* panel in the *AN* tab in the *Tool Shelf*. The name of that property is defined by the node label if it is set. This option is useful if one want to edit some parameters in the node tree directly from within the 3d viewport without having to go the node editor.
+- **Show in viewport** - If this option is enabled, the property will show up in the *Data Input* panel in the Animation Nodes tab in the *Tool Shelf* in the 3D viewport. The name of that property is defined by the node label if it is set. This option is useful if one want to edit some parameters directly from within the 3D viewport without having to go the node editor.
 
 .. image:: /includes/nodes/images/show_in_viewport.png

docs/index.rst

@@ -2,9 +2,9 @@
 Animation Nodes Manual
 **********************
 
-Welcome to the official manual of **Animation Nodes** (AN).
+Welcome to the official manual of **Animation Nodes**.
 
-AN is a node based visual scripting system designed for motion graphics in `Blender <http://www.blender.org/>`_.
+Animation Nodes is a node based visual scripting system designed for motion graphics in `Blender <http://www.blender.org/>`_.
 
 .. toctree::
    :maxdepth: 2
@@ -16,14 +16,14 @@ AN is a node based visual scripting system designed for motion graphics in `Blen
 External Links
 **************
 
-- `Github Issues <https://github.com/JacquesLucke/animation_nodes/issues>`_: A place where you can report bugs, suggest features, ask for help and have general discuss about Animation Nodes.
-- `Stack Exchange <https://blender.stackexchange.com/questions/ask?tags=animation-nodes>`_: A place where you can use the `animation-nodes` tag to ask question related to animation nodes and get support from the big community of Blender.SE.
-- `Blender Artists Thread <https://blenderartists.org/forum/showthread.php?350296-Addon-Animation-Nodes/>`_: A place where you can share your work, ask question and have general discuss about Animation Nodes.
+- `Github Issues <https://github.com/JacquesLucke/animation_nodes/issues>`_: A place where you can report bugs, suggest features, ask for help and have general discussion about Animation Nodes.
+- `Stack Exchange <https://blender.stackexchange.com/questions/ask?tags=animation-nodes>`_: A place where you can ask questions related to Animation Nodes using the `animation-nodes` tag and get support from the big community of Blender.SE.
+- `Blender Artists Thread <https://blenderartists.org/forum/showthread.php?350296-Addon-Animation-Nodes/>`_: A place where you can share your work, ask question and have general discussion about Animation Nodes.
 
 Tutorials
 *********
 
-Below is a list of all known Animation Nodes tutorials creators. Do you create tutorials? Let us know !
+Below is a list of all known Animation Nodes tutorials creators. Do you create tutorials? Let us know!
 
 +------------------+-------------+---------------+
 | Creator          | Contents    | Notes         |

docs/user_guide/getting_started/data.rst

@@ -2,7 +2,9 @@
 Data
 ****
 
-Data in Animation Nodes is typed, that is, sockets have specific data type which can be identified by its color. For instance, a blue socket represents a *3D Vector* data type and a black socket represents an *Object* data type. If one attempts to connect a node output to an input, unless they have the same data type or the output can be implicitly converted to the target data type, Animation Nodes won't allow it (Implicit Conversion is discussed in the next section). All data types have corresponding list types, list data types have the same socket color but are transparent. For instance, the 3D Vector data type has a corresponding 3D Vector List that can exclusively store multiple 3D Vectors.
+Data in Animation Nodes is typed, that is, sockets have specific data types which can be identified by their color. For instance, a blue socket represents a *3D Vector* data type and a black socket represents an *Object* data type. If one attempts to connect two node sockets, unless they have the same data type or the origin type can be implicitly converted to the target type, Animation Nodes won't allow the connection.
+
+All data types have corresponding list types, list data types have the same socket color but are somewhat transparent. For instance, the 3D Vector data type has a corresponding 3D Vector List that can exclusively store 3D Vectors.
 
 .. image:: images/data_types.png
 
@@ -11,7 +13,7 @@ The output of the *Combine Vector* and *Object Input* nodes are 3D Vector and Ob
 Implicit Conversion
 ===================
 
-Some data can be *implicitly* converted to other type of data, the conversion happens at the socket level. Thus, it is noted that some sockets accepts more than one data type. For instance, it is possible to connect Integers, Floats and Booleans together because all of which are numbers and can be implicitly converted to each other.
+Some data types can be *implicitly* converted to other data types, the conversion happens at the socket level. Thus, it is noted that some sockets accepts more than one data type. For instance, it is possible to connect Integers, Floats and Booleans together because all of which are numbers and can be implicitly converted to each other.
 
 .. note::
     A boolean when converted to a number is ``1`` if ``True`` and ``0`` if ``False``. Moreover, a number when converted to boolean is ``True`` if it is non zero and ``False`` if zero. Floats are floored when converted into integers, so ``1.5`` becomes ``1`` and ``2.7`` becomes ``2``.
@@ -35,7 +37,7 @@ Vectorized Sockets
 
 Some nodes in Animation Nodes are said to be "vectorized". Vectorization is the ability of the node to operate on lists just as it can operate on individual elements.
 
-A vectorized node include vectorized sockets, such sockets change from list types to their element type and vise versa based on your input. For instance, the *Parse Number* node parse the input text, if I were to input a text list the input socket will automatically turn into a text list. A vectorized socket have the same color as its data type but it is semi-transparent.
+A vectorized node has vectorized sockets, such sockets change from list types to their element type and vise versa based on your input. For instance, the *Parse Number* node parses the input text, if I were to input a text list the input socket will automatically turn into a text list. A vectorized socket have the same color as its data type but is semi-transparent.
 
 .. image:: gifs/parse_number.gif
 
@@ -45,22 +47,37 @@ A vectorized node include vectorized sockets, such sockets change from list type
 Data Copying
 ============
 
-Animation Nodes copied data whenever needed, and for most of the nodes, copying is not something you can control, Animation Nodes take complete control of what should or should not be copied. For instance, if you have a vector list and you shuffle it using a *shuffle* node, Animation Nodes makes the decision of shuffling the original list instead of shuffling a copy of the data. If, however, we shuffle the vector list with another *shuffle* node, Animation Nodes makes the decision of copying the data. To understand why Animation Nodes made that decision, consider the scenario where the data wasn't copied, then the first *shuffle* node will shuffle the original list and the second *shuffle* node will shuffle the already shuffled list and not the list itself. Due to this behavior, you should never assume that a node will copy or or edit original data unless explicitly specified.
+Users of Animation nodes don't have to worry about data copying as Animation Nodes automatically copy data if needed, however, sometimes, control over whether data should be copied is given to the user, such control is only needed for advanced uses of subprograms and data editing nodes. The options to control data copying is provided in the *Advanced Node Settings* of the nodes that supports it.
+
+To have a better understanding of data copying and a possible situation where control over it might be needed, consider the following example (*The following example is rather advanced and require good knowledge of loops, you may skip it if you are just getting started*).
+
+A loop is constructed such that it appends a float to an initially empty float list parameter provided a condition is satisfied at each iteration. The conditional appending is achieved by conditionally reassigning the float list parameter to the list after appending. *Notice that using a conditional generator may not be an option because access to the generated list at each iteration might be needed.* Now, consider the situation where we only reassign if the index is larger than 2, if the number of iterations is 5, we should expect the float list to contain two floats, but upon viewing it, we see it actually contains five elements realizing that the conditional reassigning is rendered ineffective. Why is that?
+
+.. image:: images/copying_example_1.png
+
+You see, the *Append To List* node appends the float to the original list because the *Loop Input* node handed it without copying (The default no-copying behavior is chosen for performance superiority.), subsequently, it doesn't matter whether we reassigned the list or not because the original data is already altered and by the end of the loop, all floats will have been appended. The solution to this is to instruct the loop to copy the data before handing it, this can be done by enabling *Copy* for the float list parameter. Upon enabling it, we see the expected two-element output float list.
 
-.. image:: images/color_copies.png
+.. image:: images/copying_example_2.png
 
-Animation Nodes have an option to identify nodes that copy data, you can enable that by changing **Color Mode** to *Needed Copies* in the developer panel. Where nodes that copy data will be colored in red.
+Notice that Animation Nodes may enforce copying of the parameter on its own  if needed. For instance, by connecting the float list parameter to any other node, Animation Nodes feels the need to copy the data and enforce it **even if copy option is disabled**.
+
+.. image:: images/copying_example_3.png
+
+Animation Nodes provides a feature to visualize data copying by coloring nodes that copy data in red. This feature can be enabled by switching the coloring mode to *Needed Copied*. Below, we show two loops, one where data is copied colored in red and another where data is not copied.
+
+.. image:: images/needed_copies.png
 
 Generic Data Type
 =================
 
-Animation Nodes have a special data type called the *Generic* data type. This data type can store anything, including any data type along with their lists. Such data type is particularly useful when one want to store a list of lists, something that can't be done with normal data types. However, the downside is, Animation Nodes store the data as python objects (Not blender object) and thus it doesn't know what it stores, so if I were to use a generic as an input for some node, it won't allow it, because it isn't sure it is the type it wants. So, generics have to be converted back to a data type Animation Nodes knows. For instance, if we have a list of float lists, getting the first list of the this generic list would return a generic data type and not a float list, if I want to get the first float in the output list, I have to convert it to a float list first, this can be done using the converter node:
+Animation Nodes have a special data type called *Generic*. This type can hold any other data type including lists as well as other generic data. This type is particularly useful in storing lists of lists. For instance, one could construct a generic list ``A`` composed of multiple float lists, in this case, the generic type holds lists. To use the data stored in a generic type in any node, it has to be converted to an appropriate type that Animation Nodes is familiar with, the conversion can be done using the *Convert* node. For instance, if we want to get the first float in the first float list of the list ``A``, we first get the first element of the list, convert it into a float list and get the first float from that.
 
-.. image:: images/converter_node.png
+.. image:: images/converter_node_example_1.png
 
-.. note::
-    I could have got the element as a generic element then convert it to a float at the end, and the final output would have been the same.
+The convert node converts and data type to any other data type **if possible**. The node automatically detects the input type and changes the type of the output accordingly, if you want the output to be another type, disable automatic detection by checking the lock button and choose the type manually by pressing the button next to the lock.
+
+The converter node can convert structurally similar types to each others. For instance, a 3D Vector is structurally similar to an Euler because both are composed of three floats, same goes for their lists, that is, 3D vector List and Euler List. Moreover, a float list of three elements can be converted to a Vector or an Euler and a float list of four elements can be converted into a quaternion or a color, because quaternions and colors are composed of four floats. However, such conversion are slower than manual conversions and should be avoided if performance is desired.
 
-The converter node converts and data type to any other data type **if possible**. The node automatically detects the input type and changes the type of the output accordingly, so if you want the output to be something different, you have to check the lock button and choose the type manually by pressing on the button next to the lock.
+.. image:: images/converter_node_example_2.png
 
-The converter node can convert structurally similar types to each others. For instance, a 3D Vector is structurally similar an Euler because they are both composed of three floats, so they can be converted to each other, the same goes for their lists, that is, 3D vector List and Euler List.
+Some nodes are capable of performing conversion on their own, an example would be the *Expression* node where it can convert its output to the socket type it is connected to if *Correct Type* option is enabled. The type can be changed manually similar to the *Convert* node by enabling the *Fixed Data Type* option and changing the type by pressing on the gear button.