Updated documentation about variables

MAKING_NEW_RULES.md

@@ -70,6 +70,9 @@ The overall structure is this:
     - matcher:
         options:
         - 'verbose'
+        variable:
+        - 'VariableName : Extract pattern'
+        - 'VariableName : Extract pattern'
         require:
         - 'Require pattern'
         - 'Require pattern'
@@ -566,14 +569,12 @@ Variables
 =========
 There is the option of predefining a value which is then usable by all rules in a matcher.
 
-A variable is simply a named point in the tree that is found only once.
-A variable is also always in essense a 'require', it must be present for the matcher to continue.
-You can reference a variable by name in a later variable because they are evaluated in the order
-in which they appear in the definition.
+A variable is simply a named point in the tree that is found only once and the reused as-is by the other rules within the same matcher.
+A variable is also always in essense a 'require', it must be present for the matcher as a whole to continue.
+You can only reference a variable by name in a later variable. This is because they are evaluated in the order
+in which they appear in the definition in the file.
 The variable name follows a similar pattern as variable names in languages like Java: [a-zA-Z][a-zA-Z0-9]+
-When referencing a variable (by means of @name )in an expression you must see it as a point in the tree that happens to have a name.
-
-@@@@@@@@@@@@@ TODO: Describe the backtracking effects
+When referencing a variable (by means of @name) in an expression you must see it as a point in the tree that happens to have a name.
 
 This looks like this:
 
@@ -590,6 +591,24 @@ This looks like this:
         - 'LayoutEngineName      :   1000:"AppleWebKit"'
         - 'LayoutEngineVersion   :   1000:@AppleWebKitVersion'
 
+Note that the backtracking stops when the variable finds its first match.
+So when defined like this:
+
+    extract:
+    - 'Something: 1: agent.product.(1)name="AppleWebKit"^.version'
+
+it may find after backtracking that the 5th product matches
+
+    agent.(5)product.(1)version
+
+Yet when defined like this
+
+    variable:
+    - 'productname: agent.product.(1)name'
+    extract:
+    - 'Something: 1: @productname="AppleWebKit"^.version'
+
+it will stay at the first product and never find the 5th product at all.
 
 License
 =======