1.1 --- a/docs/COPYING.txt Thu Jan 18 23:33:37 2007 +0000
1.2 +++ b/docs/COPYING.txt Thu Jan 18 23:34:11 2007 +0000
1.3 @@ -1,7 +1,7 @@
1.4 Licence Agreement for XSLTools
1.5 ------------------------------
1.6
1.7 -Copyright (C) 2005, 2006 Paul Boddie <paul@boddie.org.uk>
1.8 +Copyright (C) 2005, 2006, 2007 Paul Boddie <paul@boddie.org.uk>
1.9
1.10 This library is free software; you can redistribute it and/or
1.11 modify it under the terms of the GNU Lesser General Public
2.1 --- a/docs/index.html Thu Jan 18 23:33:37 2007 +0000
2.2 +++ b/docs/index.html Thu Jan 18 23:34:11 2007 +0000
2.3 @@ -10,23 +10,23 @@
2.4 libxml2, libxslt and (optionally) <a href="http://www.boddie.org.uk/python/WebStack.html">WebStack</a>.</p>
2.5 <h2>Setting Up</h2>
2.6 <p>First of all, let us assume that the XSLTools distribution has been
2.7 -unpacked and now sits in the <code>XSLTools-0.4.2</code> directory.</p>
2.8 +unpacked and now sits in the <code>XSLTools-0.4.3</code> directory.</p>
2.9 <p>Before we begin, we must make sure that the XSLTools package is
2.10 available
2.11 -to Python. The easiest way to do this is to change into the <code>XSLTools-0.4.2</code> directory and to run the <code>setup.py</code>
2.12 +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>
2.13 script provided with the version of Python you are going to be using
2.14 (possibly as a privileged user like <code>root</code>):</p>
2.15 -<pre>cd XSLTools-0.4.2<br />python setup.py install</pre>
2.16 +<pre>cd XSLTools-0.4.3<br />python setup.py install</pre>
2.17 <p>If you don't want to install XSLTools in this way, or if you can't
2.18 do so
2.19 because you don't have <code>root</code> privileges, you can just make
2.20 sure
2.21 -that the <code>XSLTools-0.4.2</code> directory sits on your
2.22 +that the <code>XSLTools-0.4.3</code> directory sits on your
2.23 <code>PYTHONPATH</code>.</p>
2.24 <h2>Viewing the API Documentation</h2>
2.25 <p>The API documentation for use in conjunction with this
2.26 guide can be found inside the <a href="../apidocs/index.html"><code>apidocs</code></a>
2.27 -directory within the <code>XSLTools-0.4.2</code> directory. Of course,
2.28 +directory within the <code>XSLTools-0.4.3</code> directory. Of course,
2.29 it is always possible to view the API documentation
2.30 within Python by importing modules (such as <a href="../apidocs/public/XSLTools.XSLOutput-module.html"><code>XSLTools.XSLOutput</code></a>)
2.31 and using Python's built-in <code>help</code> function.</p>
3.1 --- a/docs/internationalisation.html Thu Jan 18 23:33:37 2007 +0000
3.2 +++ b/docs/internationalisation.html Thu Jan 18 23:34:11 2007 +0000
3.3 @@ -42,13 +42,16 @@
3.4 templates and documents containing data which are also used to prepare
3.5 the final user-viewable output from an application. For example, one
3.6 can define a file with the name <code>translations.xml</code> and then insert the following contents into it:</p><pre><?xml version="1.0" encoding="iso-8859-1"?><br /><translations><br /> <locale><br /> <code value="en_GB"/><br /> <code value="en"/><br /> </locale><br /> <locale><br /> <code value="nb_NO"/><br /> <code value="nb"/><br /> <translation value="System Configurator">Systemkonfigurasjon</translation><br /> <translation value="Update!">Oppdatér!</translation><br /> <translation value="Export!">Eksportér!</translation><br /> </locale><br /></translations></pre><p>The structure of any such translations file must resemble the above:</p><ol><li>A top-level <code>translations</code> element containing...</li><li>A number of <code>locale</code> sections, each containing...</li><li>One or more <code>code</code> elements identifying the locale, together with...</li><li>A number of <code>translation</code> elements, each providing a translation for each token.</li></ol><p>In the above example, the locale for <code>en</code> and <code>en_GB</code> have no translations defined; as a result, for any requests for translations in this locale the
3.7 -text already found in the document will be preserved, and this
3.8 -behaviour is therefore equivalent to requests for translations
3.9 -in locales which are not defined or mentioned in the above
3.10 -document.</p><p>Conversely, in the above example, the locale for <code>en</code> and <code>en_GB</code>
3.11 +text already found in the document will be preserved.</p><p>Conversely, in the above example, the locale for <code>nb</code> and <code>nb_NO</code>
3.12 has some translations defined; as a result, requests for translations
3.13 in this locale will result in the specified translations being
3.14 -returned, provided the token is defined in a <code>value</code> attribute of a <code>translation</code> element; otherwise, the text already found in the document will be preserved.</p><h3><a name="UsingTheTranslations"></a>Using the Translations</h3><p>To make use of such a translation file, the file must first be registered in an application. As described in the <a href="Web-resource.html">"Creating Applications: Write a Web Resource"</a> and <a href="XSLForms-resource.html">"Using the XSLFormsResource API"</a> documents, we may add the above example to a resource in the <code>document_resources</code> attribute:</p><pre>document_resources = {<br /> "translations" : "translations.xml"<br /> # Other resources are defined here.<br /> }</pre><p>When
3.15 +returned, provided the token is defined in a <code>value</code> attribute of a <code>translation</code> element; otherwise, the default translation will be employed.</p><p>Note that the default translation, <strong>in contrast to earlier versions of XSLTools</strong>, is defined by the first <code>locale</code> section.
3.16 +Thus, in the above example, other locales not mentioned in the
3.17 +translations file will employ the translations associated with the <code>en</code> and <code>en_GB</code> locales.
3.18 +In this case, the text already found in the document will be preserved
3.19 +since no translations are explicitly given for that locale.</p><h4>Summary of Selection Algorithm</h4><p>The following algorithm summarises the above description:</p><ol><li>For a requested locale, look for a matching <code>locale</code> section.</li><li>For a matching section, find a translation for a text value; if a translation is found, return it.</li><li>Where
3.20 +no matching section or translation is found, find a translation in the
3.21 +first, default section; if a translation is found, return it.</li><li>Where no matching default translation is found, return the original text value.</li></ol><h3><a name="UsingTheTranslations"></a>Using the Translations</h3><p>To make use of such a translation file, the file must first be registered in an application. As described in the <a href="Web-resource.html">"Creating Applications: Write a Web Resource"</a> and <a href="XSLForms-resource.html">"Using the XSLFormsResource API"</a> documents, we may add the above example to a resource in the <code>document_resources</code> attribute:</p><pre>document_resources = {<br /> "translations" : "translations.xml"<br /> # Other resources are defined here.<br /> }</pre><p>When
3.22 producing output for a template which uses internationalisation
3.23 features, we must first obtain a reference to the above document:</p><pre># In the respond_to_form method of an XSLFormsResource...<br />translations_xml = self.prepare_document("translations")</pre><p>Then,
3.24 we must decide which language or locale the output will employ. One way