1.1 --- a/docs/reference.html Fri Jan 19 22:22:33 2007 +0000
1.2 +++ b/docs/reference.html Fri Jan 19 22:22:51 2007 +0000
1.3 @@ -80,4 +80,23 @@
1.4 collection of elements.</p><p>Example:</p><pre><p template:multiple-choice-list-element="question,question-types,question-type"><br /> <input template:attribute-list-button="question-type,checked" name="..." value="..." type="checkbox"/><br /></p></pre><p>Given an XML document like this...</p><pre><question><br /> <question-types question-type="text" value-is-set="true"/><br /> <question-types question-type="choice"/><br /></question></pre><p>...the following would be produced as output:</p><pre><p><br /> <input name="path-to-question-type" value="text" type="checkbox" checked="checked"/><br /></p><br /><p><br /> <input name="path-to-question-type" value="choice" type="checkbox"/><br /></p></pre><p>Syntax:</p><pre>attribute-name,attribute-to-create-when-set</pre><p>Related attributes:</p><ul><li><code>template:multiple-choice-list-element</code></li><li><code>template:attribute-button</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:attribute</code></li><li><code>template:expr</code></li><li><code>template:expr-attr</code></li></ul><h2>Internal Annotations</h2><p>The special annotations <code>template:expr</code> and <code>template:expr-attr</code>
1.5 are used respectively to test an XPath expression in the current
1.6 context and to provide the name of an attribute which is to be created
1.7 -in the final output, should the expression evaluate to a true value.</p></body></html>
1.8 \ No newline at end of file
1.9 +in the final output, should the expression evaluate to a true value.</p><h2>Housekeeping Annotations</h2><p>In order to support explicit, additional namespaces in output document processing, the special <code>expr-prefix</code>
1.10 +attribute can be used to ensure the presence of a namespace declaration
1.11 +in the generated stylesheet files. Consider the usage of various
1.12 +stylesheet extension functions:</p><pre><body><br /> <p><br /> <span template:value="sum(str:split('1 2 3 4 5'))">result</span><br /> </p><br /></body></pre><p>For the stylesheet which produces the output, the <code>str</code>
1.13 +namespace will need to be declared somewhere. To do this, we must not
1.14 +only declare the namespace in the template document, but we must also
1.15 +provide a hint to the stylesheet processor that the namespace is
1.16 +important (even though it is only mentioned in the text of an
1.17 +attribute, which might persuade some XML processing toolkits to abandon
1.18 +the namespace declaration).</p><pre><body xmlns:str="http://exslt.org/strings" str:expr-prefix="str http://exslt.org/strings"><br /> <p><br /> <span template:value="sum(str:split('1 2 3 4 5'))">result</span><br /> </p><br /></body></pre><p>What the special <code>expr-prefix</code>
1.19 +attribute does is to provide that hint to the stylesheet processor,
1.20 +although XSLTools also uses the attribute for other internal purposes.
1.21 +Consequently, the resulting output stylesheet is able to find the <code>str:split</code> extension function and to evaluate the expected result.</p><h3>Fixing Annotations</h3><p>One important application of the <code>expr-prefix</code>
1.22 +attribute is the restoration of damaged attributes after the editing of
1.23 +a template document using a less than careful HTML editor. Consider the
1.24 +above document fragment after a small edit in Nvu:</p><pre><body expr-prefix="str http://exslt.org/strings" str="http://exslt.org/strings"><br /> <p><br /> <span value="sum(str:split('1 2 3 4 5'))">result!</span><br /> </p><br /></body></pre><p>Nvu has obviously decided to remove the <code>str</code> and <code>template</code> namespace prefixes. To revert this damage, a tool is provided with XSLTools called <code>xslform_fix.py</code> (found in the <code>scripts</code> directory in the source distribution), and this tool will attempt to re-add namespace declarations for <code>template</code> automatically (since the <code>template</code> namespace is obviously the basis of XSLForms) along with any namespaces declared using <code>expr-prefix</code> attributes. The tool is invoked as follows:</p><pre>xslform_fix.py template.xhtml template_fixed.xhtml</pre><p>Since
1.25 +namespace declarations may be moved to the root element of the new
1.26 +template document, it is possible that some problems may result
1.27 +with documents using namespaces in advanced ways, but the tool
1.28 +should provide a reasonable solution for most documents.</p></body></html>
1.29 \ No newline at end of file