1.1 --- a/docs/index.html Fri Jan 19 22:22:33 2007 +0000
1.2 +++ b/docs/index.html Fri Jan 19 22:22:51 2007 +0000
1.3 @@ -10,23 +10,23 @@
1.4 libxml2, libxslt and (optionally) <a href="http://www.boddie.org.uk/python/WebStack.html">WebStack</a>.</p>
1.5 <h2>Setting Up</h2>
1.6 <p>First of all, let us assume that the XSLTools distribution has been
1.7 -unpacked and now sits in the <code>XSLTools-0.4.3</code> directory.</p>
1.8 +unpacked and now sits in the <code>XSLTools-0.4.4</code> directory.</p>
1.9 <p>Before we begin, we must make sure that the XSLTools package is
1.10 available
1.11 -to Python. The easiest way to do this is to change into the <code>XSLTools-0.4.3</code> directory and to run the <code>setup.py</code>
1.12 +to Python. The easiest way to do this is to change into the <code>XSLTools-0.4.4</code> directory and to run the <code>setup.py</code>
1.13 script provided with the version of Python you are going to be using
1.14 (possibly as a privileged user like <code>root</code>):</p>
1.15 -<pre>cd XSLTools-0.4.3<br />python setup.py install</pre>
1.16 +<pre>cd XSLTools-0.4.4<br />python setup.py install</pre>
1.17 <p>If you don't want to install XSLTools in this way, or if you can't
1.18 do so
1.19 because you don't have <code>root</code> privileges, you can just make
1.20 sure
1.21 -that the <code>XSLTools-0.4.3</code> directory sits on your
1.22 +that the <code>XSLTools-0.4.4</code> directory sits on your
1.23 <code>PYTHONPATH</code>.</p>
1.24 <h2>Viewing the API Documentation</h2>
1.25 <p>The API documentation for use in conjunction with this
1.26 guide can be found inside the <a href="../apidocs/index.html"><code>apidocs</code></a>
1.27 -directory within the <code>XSLTools-0.4.3</code> directory. Of course,
1.28 +directory within the <code>XSLTools-0.4.4</code> directory. Of course,
1.29 it is always possible to view the API documentation
1.30 within Python by importing modules (such as <a href="../apidocs/public/XSLTools.XSLOutput-module.html"><code>XSLTools.XSLOutput</code></a>)
1.31 and using Python's built-in <code>help</code> function.</p>
2.1 --- a/docs/reference.html Fri Jan 19 22:22:33 2007 +0000
2.2 +++ b/docs/reference.html Fri Jan 19 22:22:51 2007 +0000
2.3 @@ -80,4 +80,23 @@
2.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>
2.5 are used respectively to test an XPath expression in the current
2.6 context and to provide the name of an attribute which is to be created
2.7 -in the final output, should the expression evaluate to a true value.</p></body></html>
2.8 \ No newline at end of file
2.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>
2.10 +attribute can be used to ensure the presence of a namespace declaration
2.11 +in the generated stylesheet files. Consider the usage of various
2.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>
2.13 +namespace will need to be declared somewhere. To do this, we must not
2.14 +only declare the namespace in the template document, but we must also
2.15 +provide a hint to the stylesheet processor that the namespace is
2.16 +important (even though it is only mentioned in the text of an
2.17 +attribute, which might persuade some XML processing toolkits to abandon
2.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>
2.19 +attribute does is to provide that hint to the stylesheet processor,
2.20 +although XSLTools also uses the attribute for other internal purposes.
2.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>
2.22 +attribute is the restoration of damaged attributes after the editing of
2.23 +a template document using a less than careful HTML editor. Consider the
2.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
2.25 +namespace declarations may be moved to the root element of the new
2.26 +template document, it is possible that some problems may result
2.27 +with documents using namespaces in advanced ways, but the tool
2.28 +should provide a reasonable solution for most documents.</p></body></html>
2.29 \ No newline at end of file