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.