add description of operational templates

1 files changed, 46 insertions, 1 deletions

diff --git a/README b/README
index 5bc4672..44cf084 100644
--- a/README
+++ b/README
@@ -1,2 +1,47 @@
 This package has the Vyatta operational command completion script and
-base templates.
+base template tree. The default root of this tree is:
+     /opt/vyatta/share/vyatta-op/templates
+
+Each directory within this tree is a respective command line argument;
+for example, the .../templates/show/interfaces/ethernet directory
+completes the command line "show interfaces ethernet". Thus, the
+directory name is generally equivalent to the command or argument
+name.  The only exception are directories named "node.tag"; these
+represent dynamic or variable command arguments. For example,
+.../templates/show/interfaces/ethernet/node.tag completes the active
+system interfaces like "show interfaces ethernet eth0".
+
+Every template directory must have one and only one file named
+"node.def". This file defines the node help string and run command,
+like .../templates/show/interfaces/node.def:
+
+help: "Show network interface information"
+run: ${vyatta_bindir}/vyatta-show-interfaces
+
+Notes:
+	- field tags (i.e. help and run) must be at the start of line
+	- try to limit help strings to 64 characters
+	- run commands may span multiple lines but subsequent lines must
+	  not begin with "WORD:"
+
+The run command is an evaluated shell expression that may contain the
+positional command line argument variables (i.e. $1, $*, $@).
+However, since the command itself, is evaluated through an aliased
+function, $1 is the command name rather than the usual $0. So, the
+command "show interfaces ethernet eth0" would evaluate the respective
+run command with $4 == eth0.
+
+The variable argument .../node.tag/node.def files must also define an
+"allowed" value field that is a shell expression that outputs (stdout)
+the list of values;
+like .../templates/show/interfaces/ethernet/node.tag/node.def:
+
+help: "Show given ethernet interface information"
+allowed: local -a array=( /sys/class/net/{eth,vmnet}* ) ;
+	 echo  -n ${array[@]##*/}
+run: ${vyatta_bindir}/vyatta-show-interfaces ethernet $4
+
+You may use the "--" wild card, for variable arguments with no
+possible completion:
+
+allowed: echo -n --