# HG changeset patch
# User paulb
# Date 1131474775 0
# Node ID 2da5c845cc557dd2405965232bb8fe92ef9b543a
# Parent  b7d6c1e31ae9b7fc30536ec0c7886b7930af165f
[project @ 2005-11-08 18:32:55 by paulb]
Tidied up the docstrings, adding more element-path information.

diff -r b7d6c1e31ae9 -r 2da5c845cc55 XSLForms/Output.py
--- a/XSLForms/Output.py	Sat Nov 05 01:46:04 2005 +0000
+++ b/XSLForms/Output.py	Tue Nov 08 18:32:55 2005 +0000
@@ -123,6 +123,7 @@
 
     """
     Exposed as {template:this-element()}.
+
     Provides a reference to the current element in the form data structure.
     """
 
@@ -134,6 +135,7 @@
 
     """
     Exposed as {template:this-attribute()}.
+
     Provides a reference to the current attribute in the form data structure.
     """
 
@@ -145,6 +147,7 @@
 
     """
     Exposed as {template:new-attribute(name)}.
+
     Provides a reference to a new attribute of the given 'name' on the current
     element in the form data structure.
     """
@@ -158,6 +161,7 @@
 
     """
     Exposed as {template:other-elements(nodes)}.
+
     Provides a reference to other elements in the form data structure according
     to the specified 'nodes' parameter (an XPath expression in the template).
     """
@@ -175,6 +179,7 @@
 
     """
     Exposed as {template:list-attribute(element_name, attribute_name)}.
+
     Provides a reference to one or many elements of the given 'element_name'
     found under the current element in the form data structure having
     attributes with the given 'attribute_name'.
@@ -190,6 +195,7 @@
 
     """
     Exposed as {template:other-list-attributes(element_name, attribute_name, nodes)}.
+
     Provides a reference to other elements in the form data structure, found
     under the specified 'nodes' (described using an XPath expression in the
     template) having the given 'element_name' and bearing attributes of the
@@ -211,6 +217,7 @@
 
     """
     Exposed as {template:other-attributes(name, nodes)}.
+
     Provides a reference to attributes in the form data structure of the given
     'attribute_name' residing on the specified 'nodes' (described using an XPath
     expression in the template).
@@ -233,6 +240,7 @@
 
     """
     Exposed as {template:child-element(element_name, position, node_paths)}.
+
     Provides relative paths to the specifed 'element_name', having the given
     'position' (1-based) under each element specified in 'node_paths' (provided
     by calls to other extension functions in the template). For example:
@@ -251,6 +259,7 @@
 
     """
     Exposed as {template:child-attribute(attribute_name, node_paths)}.
+
     Provides a relative path to the specifed 'attribute_name' for each element
     specified in 'node_paths' (provided by calls to other extension functions in
     the template). For example:
@@ -268,6 +277,7 @@
 
     """
     Exposed as {template:selector-name(field_name, nodes)}.
+
     Provides a selector field name defined using 'field_name' and referring to
     the given 'nodes'. For example:
 
@@ -310,6 +320,7 @@
 
     """
     Exposed as {template:url-encode(nodes)}.
+
     Provides a "URL encoded" string created from the merged textual contents of
     the given 'nodes', with the encoded character values representing characters
     in the optional 'charset' (UTF-8 if not specified).
@@ -327,11 +338,22 @@
 def element_path(context, field_names):
 
     """
+    Exposed as {template:element-path(field_names)}.
+
     Convert the given 'field_names' back to XPath references.
     For example:
+
     /configuration$1/details$1/base-system$$value -> /*[position() = 1]/*[position() = 1]/base-system
+
     If more than one field name is given - ie. 'field_names' contains a
     comma-separated list of names - then only the first name is used.
+
+    To use this function effectively, use the result of another function as the
+    argument. For example:
+
+    template:element-path(template:this-element())
+    template:element-path(template:other-elements(matches))
+    template:element-path(template:other-elements(..))
     """
 
     field_name = field_names.split(",")[0]