initial documentation for extensions
diff --git a/README.extentions b/README.extentions
new file mode 100644
index 0000000..18d8974
--- /dev/null
+++ b/README.extentions
@@ -0,0 +1,205 @@
+Escaping of References and Inventory Queries
+============================================
+
+Reference and inventory queries can be escaped to produce literal strings, for example:
+
+parameters:
+ colour: Blue
+ unescaped: The colour is ${colour}
+ escaped: The colour is \${colour}
+ double_escaped: The colour is \\${colour}
+
+
+This would produce:
+
+parameters:
+ colour: Blue
+ unescaped: The colour is Blue
+ escaped: The colour is ${colour}
+ double_escaped: The colour is \Blue
+
+
+
+Merging Referenced Lists and Dictionaries
+=========================================
+
+Referenced lists or dicts can now be merged:
+
+# nodes/test.yml
+classes:
+ - test1
+ - test2
+parameters:
+ one:
+ a: 1
+ b: 2
+ two:
+ c: 3
+ d: 4
+ three:
+ e: 5
+
+# classes/test1.yml
+parameters:
+ three: ${one}
+
+# classes/test2.yml
+parameters:
+ three: ${two}
+
+running reclass.py --nodeinfo node1 then gives:
+
+parameters:
+ one:
+ a: 1
+ b: 2
+ three:
+ a: 1
+ b: 2
+ c: 3
+ d: 4
+ e: 5
+ two:
+ c: 3
+ d: 4
+
+This first sets the parameter three to the value of parameter one (class test1) then merges parameter two into
+parameter three (class test2) and finally merges the parameter three definition given in the node definition into
+
+
+
+Nested References
+=================
+
+References can now be nested, for example:
+
+# nodes/node1.yml
+parameters:
+ alpha:
+ one: ${beta:${alpha:two}}
+ two: a
+ beta:
+ a: 99
+
+reclass.py --nodeinfo node1 then gives:
+
+parameters:
+ alpha:
+ one: 99
+ two: a
+ beta:
+ a: 99
+
+The ${beta:${alpha:two}} construct first resolves the ${alpha:two} reference to the value 'a', then resolves
+the reference ${beta:a} to the value 99.
+
+
+
+Inventory Queries
+=================
+
+Inventory querying works using a new key type - exports to hold values which other node definitions can read using a $[] query, for example with:
+
+# nodes/node1.yml
+exports:
+ test_zero: 0
+ test_one:
+ name: ${name}
+ value: 6
+ test_two: ${dict}
+
+parameters:
+ name: node1
+ dict:
+ a: 1
+ b: 2
+ exp_value_test: $[ exports:test_two ]
+ exp_if_test0: $[ if exports:test_zero == 0 ]
+ exp_if_test1: $[ exports:test_one if exports:test_one:value == 7 ]
+ exp_if_test2: $[ exports:test_one if exports:test_one:name == self:name ]
+
+# nodes/node2.yml
+exports:
+ test_zero: 0
+ test_one:
+ name: ${name}
+ value: 7
+ test_two: ${dict}
+
+parameters:
+ name: node2
+ dict:
+ a: 11
+ b: 22
+
+
+running reclass.py --nodeinfo node1 gives (listing only the exports and parameters):
+
+exports:
+ test_one:
+ name: node1
+ value: 6
+ test_two:
+ a: 1
+ b: 2
+parameters:
+ dict:
+ a: 1
+ b: 2
+ exp_if_test0:
+ - node1
+ - node2
+ exp_if_test1:
+ node2:
+ name: node2
+ value: 7
+ exp_if_test2:
+ node1:
+ name: node1
+ value: 6
+ exp_value_test:
+ node1:
+ a: 1
+ b: 2
+ node2:
+ a: 11
+ b: 22
+ name: node1
+
+
+Exports defined for a node can be a simple value or a reference to a parameter in the node definition.
+The $[] inventory queries are calculated for simple value expressions, $[ exports:key ], by returning
+a dictionary with an element ({ node_name: key value }) for each node which defines 'key' in the exports
+section. For tests with a preceeding value, $[ exports:key if exports:test_key == test_value ], the
+element ({ node_name: key value }) is only added to the returned dictionary if the test_key defined in
+the node exports section equals the test value. For tests without a preceeding value,
+$[ if exports:test_key == test_value ], a list of nodes which pass the test is returned. For either test
+form the test value can either be a simple value or a node parameter. And as well as an equality test
+a not equals test (!=) can also be used.
+
+**Inventory query options**
+
+By default inventory queries only look at nodes in the same environment as the querying node. This can be
+overriden using the +AllEnvs option:
+
+ $[ +AllEnvs exports:test ]
+
+Any errors in rendering the export parameters for a node will give an error for the inventory query as a whole.
+This can be overriden using the +IgnoreErrors option:
+
+ $[ +IgnoreErrors exports:test ]
+
+With the +IgnoreErrors option nodes which generate an error evaluating exports:test will be ignored.
+
+Inventory query options can be combined:
+
+ $[ +AllEnvs +IgnoreErrors exports:test ]
+
+**Logical operators and/or**
+
+The logical operators and/or can be used in inventory queries:
+
+ $[ exports:test_value if exports:test_zero == 0 and exports:test_one == self:value ]
+
+The individual elements of the if statement are evaluated and combined with the logical operators starting from the
+left and working to the right.
diff --git a/README.rst b/README.rst
index e88c135..6a70e2f 100644
--- a/README.rst
+++ b/README.rst
@@ -1,5 +1,31 @@
-reclass README
-==============
+reclass (extended) README
+=========================
-The documentation for **reclass** is available from
-http://reclass.pantsfullofunix.net.
+This is an extended version of **reclass** available at:
+https://github.com/AndrewPickford/reclass
+
+The original **reclass** is available at:
+https://github.com/madduck/reclass
+
+
+Extentions
+==========
+
+Escaping of References and Inventory Queries
+Merging Referenced Lists and Dictionaries
+Nested References
+Inventory Queries
+
+
+Changes
+=======
+
+The escaping of references changes how the constructs '\${xxx}' and '\\${xxx}'
+are rendered.
+
+
+Documentation
+=============
+
+Documentation covering the original version is in the doc directory.
+See the README.extensions file for documentation on the extentions.