doc/xslt/slides/keynote/xsltsl/stdlib.xsl

   1 <?xml version="1.0"?>
   2 <!DOCTYPE xsl:stylesheet [
   3   <!ENTITY version "1.2.1">
   4 ]>
   5
   6 <xsl:stylesheet
   7   xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   8   xmlns:doc="http://xsltsl.org/xsl/documentation/1.0"
   9   exclude-result-prefixes="doc"
  10   version="1.0">
  11
  12   <xsl:import href="string.xsl"/>
  13   <xsl:import href="date-time.xsl"/>
  14   <xsl:import href="node.xsl"/>
  15   <xsl:import href="uri.xsl"/>
  16   <xsl:import href="markup.xsl"/>
  17   <xsl:import href="math.xsl"/>
  18   <xsl:import href="cmp.xsl"/>
  19
  20   <xsl:import href="svg.xsl"/>
  21 <!--
  22   <xsl:import href="html/html.xsl"/>
  23   <xsl:import href="fo/fo.xsl"/>
  24 -->
  25
  26   <!-- For a new module, add an import element here -->
  27   <xsl:import href="example.xsl"/>
  28
  29   <doc:book xmlns="">
  30     <bookinfo>
  31       <title>XSLT Standard Library</title>
  32       <subtitle>Version &version;</subtitle>
  33       <!-- $Id: stdlib.xsl 3991 2004-11-10 06:51:55Z balls $ -->
  34
  35       <author>
  36         <surname>Ball</surname>
  37         <firstname>Steve</firstname>
  38       </author>
  39       <copyright>
  40         <year>2004</year>
  41         <year>2002</year>
  42         <holder>Steve Ball</holder>
  43       </copyright>
  44     </bookinfo>
  45
  46     <preface>
  47       <para>The <ulink url="http://www.w3.org/Style/XSL">XSLT</ulink> Standard Library, <acronym>xsltsl</acronym>, provides the XSLT developer with a set of XSLT templates for commonly used functions.  These are implemented purely in XSLT, that is they do not use any extensions.</para>
  48       <para><acronym>xsltsl</acronym> is a <ulink url="http://sourceforge.net/projects/xsltsl/">SourceForge project</ulink>.</para>
  49       <para><ulink url="http://sourceforge.net/"><inlinemediaobject>
  50           <imageobject>
  51             <imagedata fileref="sflogo.gif" width="88" height="31"/>
  52           </imageobject>
  53           <textobject>
  54             <phrase>SourceForge Logo</phrase>
  55           </textobject>
  56         </inlinemediaobject></ulink></para>
  57       <para>Goals of the <acronym>xsltsl</acronym> project include:</para>
  58       <itemizedlist>
  59         <listitem>
  60           <para>Provision of a high-quality library of XSLT templates, suitable for inclusion by vendors in XSLT processor software products.</para>
  61         </listitem>
  62         <listitem>
  63           <para>Demonstration of best practice in XSLT stylesheet development and documentation.</para>
  64         </listitem>
  65         <listitem>
  66           <para>Provide examples of various techniques used to develop XSLT stylesheets (ie. a working FAQ).</para>
  67         </listitem>
  68       </itemizedlist>
  69     </preface>
  70
  71     <chapter>
  72       <title>Using The Library</title>
  73
  74       <para>There are two ways of using the library:</para>
  75       <itemizedlist>
  76         <listitem>
  77           <para>Use a local copy of the library.</para>
  78           <orderedlist>
  79             <listitem>
  80               <para>Download the distribution (see below).</para>
  81             </listitem>
  82             <listitem>
  83               <para>Unpack the distribution, using either gunzip/tar or unzip.</para>
  84             </listitem>
  85             <listitem>
  86               <para>In your stylesheet import or include either the main stylesheet, <filename>stdlib.xsl</filename>, or the stylesheet module you wish to use, such as <filename>string.xsl</filename>.  This example assumes that the distribution has been extracted into the same directory as your own stylesheet:</para>
  87               <informalexample>
  88                 <programlisting><![CDATA[
  89 <xsl:import href="stdlib.xsl"/>
  90 ]]></programlisting>
  91               </informalexample>
  92             </listitem>
  93           </orderedlist>
  94         </listitem>
  95         <listitem>
  96           <para>Import or include either the main stylesheet, or the stylesheet module you wish to use, directly from the library website; http://xsltsl.sourceforge.net/modules/.  The <filename>modules</filename> directory always contains the latest stable release.  For example:</para>
  97           <informalexample>
  98             <programlisting><![CDATA[
  99 <xsl:import href="http://xsltsl.sourceforge.net/modules/stdlib.xsl"/>
 100 ]]></programlisting>
 101           </informalexample>
 102           <para>Older versions of the library are available in subdirectories.  For example, to access version 1.1 of the library use:</para>
 103           <informalexample>
 104             <programlisting><![CDATA[
 105 <xsl:import href="http://xsltsl.sourceforge.net/modules/1.1/stdlib.xsl"/>
 106 ]]></programlisting>
 107           </informalexample>
 108         </listitem>
 109       </itemizedlist>
 110       <para>Next, add XML Namespace declarations for the modules you wish to use.  For example, to use templates from the string module, your stylesheet should have the following declaration:</para>
 111       <informalexample>
 112         <programlisting><![CDATA[
 113 <xsl:stylesheet version="1.0"
 114         xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 115         xmlns:str="http://xsltsl.org/string">
 116
 117 <xsl:import href="http://xsltsl.sourceforge.net/modules/stdlib.xsl"/>
 118 ]]></programlisting>
 119       </informalexample>
 120       <para>Finally, use a template with the <sgmltag>call-template</sgmltag> element.  Most templates require parameters, which are passed using the <sgmltag>with-param</sgmltag> element.  For example:</para>
 121       <informalexample>
 122         <programlisting><![CDATA[
 123 <xsl:template match="foo">
 124   <xsl:call-template name="str:subst">
 125     <xsl:with-param name="text" select="."/>
 126     <xsl:with-param name="replace">a word</xsl:with-param>
 127     <xsl:with-param name="with">another word</xsl:with-param>
 128   </xsl:call-template>
 129 </xsl:template>
 130 ]]></programlisting>
 131       </informalexample>
 132     </chapter>
 133
 134     <chapter>
 135       <title>Obtaining The Library</title>
 136
 137       <para>The XSLT Standard Library is available for download as either:</para>
 138       <itemizedlist>
 139         <listitem>
 140           <para>Gzip'd tarball: <ulink url="http://prdownloads.sourceforge.net/xsltsl/xsltsl-&version;.tar.gz">http://prdownloads.sourceforge.net/xsltsl/xsltsl-&version;.tar.gz</ulink></para>
 141         </listitem>
 142         <listitem>
 143           <para>Zip file: <ulink url="http://prdownloads.sourceforge.net/xsltsl/xsltsl-&version;.zip">http://prdownloads.sourceforge.net/xsltsl/xsltsl-&version;.zip</ulink></para>
 144         </listitem>
 145       </itemizedlist>
 146     </chapter>
 147
 148     <chapter>
 149       <title>Getting Involved</title>
 150
 151       <para>Contributions to the project are most welcome, and may be in the form of stylesheet modules, patches, bug reports or sample code.  Any contributed code must use the LGPL license to be accepted into the library.</para>
 152
 153       <para>See the SourceForge Project Page <ulink url="http://sourceforge.net/projects/xsltsl/">http://sourceforge.net/projects/xsltsl/</ulink> for information on the development of the project.  Bug reports may be submitted here.</para>
 154
 155       <para>See the project Web Page <ulink url="http://xsltsl.sourceforge.net/">http://xsltsl.sourceforge.net/</ulink> for documentation.</para>
 156
 157       <para>There are three mailing lists for the project:</para>
 158       <variablelist>
 159         <varlistentry>
 160           <term><email>xsltsl-users@lists.sourceforge.net</email></term>
 161           <listitem>
 162             <para>Discussion of the use of <acronym>xsltsl</acronym>.</para>
 163           </listitem>
 164         </varlistentry>
 165         <varlistentry>
 166           <term><email>xsltsl-devel@lists.sourceforge.net</email></term>
 167           <listitem>
 168             <para>Discussion of the development of <acronym>xsltsl</acronym>.</para>
 169           </listitem>
 170         </varlistentry>
 171         <varlistentry>
 172           <term><email>xsltsl-announce@lists.sourceforge.net</email></term>
 173           <listitem>
 174             <para>Project announcements.</para>
 175           </listitem>
 176         </varlistentry>
 177       </variablelist>
 178     </chapter>
 179
 180     <chapter>
 181       <title>XML Namespaces</title>
 182
 183       <para>Apart from the XSLT XML Namespace (http://www.w3.org/1999/XSL/Transform), <acronym>xsltsl</acronym> employs a number of XML Namespaces to allow inclusion of the library in developer stylesheets.  In addition, documentation is defined in a separate namespace.</para>
 184       <para>Each module is allocated a namespace URI by appending the module name to the URI for the project, http://xsltsl.org/.  For example, the string module has the namespace URI http://xsltsl.org/string.</para>
 185       <para>All documentation is written using an <ulink url="docbook-extensions.html">extension</ulink> of <ulink url="http://www.docbook.org/">DocBook</ulink> designed for <ulink url="docbook-extensions.html">embedding DocBook into XSLT stylesheets</ulink>.  The namespace URI for DocBook embedded in stylesheets is http://xsltsl.org/xsl/documentation/1.0</para>
 186     </chapter>
 187
 188     <chapter>
 189       <title>Engineering Standards</title>
 190
 191       <para>In order to maintain a high engineering standard, all modules and contributions to the <acronym>xsltsl</acronym> project must adhere to the following coding and documentation standards.  Submissions which do not meet (or exceed) this standard will not be accepted.</para>
 192       <itemizedlist>
 193         <listitem>
 194           <para>All stylesheets must be indented, with each level indented by two spaces.  NB. a simple stylesheet could be used to enforce/fix this.</para>
 195         </listitem>
 196         <listitem>
 197           <para>Templates are named using a qualified name (QName).  The namespace URI for the template's containing stylesheet is assigned as above.</para>
 198         </listitem>
 199         <listitem>
 200           <para>Parameters for templates should use sensible names.  Where possible (or if in doubt), follow these conventions:</para>
 201           <itemizedlist>
 202             <listitem>
 203               <para>A parameter containing a single node is named <parametername>node</parametername>.  Where more than one parameter contains a single node, the suffix <parametername>Node</parametername> is appended to the parameter name, eg. <parametername>referenceNode</parametername></para>
 204             </listitem>
 205             <listitem>
 206               <para>A parameter which potentially contains multiple nodes is named <parametername>nodes</parametername>.  Where more than one parameter potentially contains multiple nodes, the suffix <parametername>Nodes</parametername> is appended to the parameter name, eg. <parametername>copyNodes</parametername></para>
 207             </listitem>
 208             <listitem>
 209               <para>A parameter which contains a string value is named <parametername>text</parametername>.</para>
 210             </listitem>
 211           </itemizedlist>
 212         </listitem>
 213         <listitem>
 214           <para>All templates in each stylesheet must be documented.  A template is documented as a <ulink url="http://www.docbook.org/">DocBook</ulink> RefEntry.</para>
 215         </listitem>
 216         <listitem>
 217           <para>Every stylesheet must include a test suite.  The test system is in the <filename>test</filename> subdirectory.  See <ulink url="test/test.html">test/test.html</ulink> for further details.</para>
 218         </listitem>
 219       </itemizedlist>
 220
 221       <para>An <ulink url="example.xsl">example stylesheet</ulink> has been provided, which acts as a template for new stylesheet modules.</para>
 222
 223     </chapter>
 224
 225     <chapter>
 226       <title>Related Work</title>
 227
 228       <para>The <ulink url="http://www.exslt.org/">EXSLT</ulink> project is creating a library to standardise extension functions.  The XSLT Standard Library is complementary to the EXSLT project.</para>
 229
 230     </chapter>
 231
 232     <chapter>
 233       <title>Reference Documentation</title>
 234
 235       <para>Reference documentation is available for each module.</para>
 236
 237       <section>
 238         <title>String Processing</title>
 239
 240         <itemizedlist>
 241           <listitem>
 242             <para><ulink url="string.html">string.xsl</ulink></para>
 243           </listitem>
 244         </itemizedlist>
 245       </section>
 246
 247       <section>
 248         <title>Nodes</title>
 249
 250         <itemizedlist>
 251           <listitem>
 252             <para><ulink url="node.html">node.xsl</ulink></para>
 253           </listitem>
 254         </itemizedlist>
 255       </section>
 256
 257       <section>
 258         <title>Date/Time Processing</title>
 259
 260         <itemizedlist>
 261           <listitem>
 262             <para><ulink url="date-time.html">date-time.xsl</ulink></para>
 263           </listitem>
 264         </itemizedlist>
 265       </section>
 266
 267       <section>
 268         <title>Mathematics</title>
 269
 270         <itemizedlist>
 271           <listitem>
 272             <para><ulink url="math.html">math.xsl</ulink></para>
 273           </listitem>
 274         </itemizedlist>
 275       </section>
 276
 277       <section>
 278         <title>URI (Uniform Resource Identifier) Processing</title>
 279
 280         <itemizedlist>
 281           <listitem>
 282             <para><ulink url="uri.html">uri.xsl</ulink></para>
 283           </listitem>
 284         </itemizedlist>
 285       </section>
 286
 287       <section>
 288         <title>Comparing Nodesets</title>
 289
 290         <itemizedlist>
 291           <listitem>
 292             <para><ulink url="cmp.html">cmp.xsl</ulink></para>
 293           </listitem>
 294         </itemizedlist>
 295       </section>
 296
 297       <section>
 298         <title>Generating XML Markup</title>
 299
 300         <itemizedlist>
 301           <listitem>
 302             <para><ulink url="markup.html">markup.xsl</ulink></para>
 303           </listitem>
 304         </itemizedlist>
 305       </section>
 306
 307       <section>
 308         <title>Presentation Media Support</title>
 309
 310         <itemizedlist>
 311           <listitem>
 312             <para>Scalable Vector Graphics: <ulink url="svg.html">svg.xsl</ulink></para>
 313           </listitem>
 314 <!--
 315           <listitem>
 316             <para><ulink url="html/html.html">html/html.xsl</ulink></para>
 317           </listitem>
 318           <listitem>
 319             <para><ulink url="fo/fo.html">fo/fo.xsl</ulink></para>
 320           </listitem>
 321 -->
 322         </itemizedlist>
 323       </section>
 324
 325       <section>
 326         <title>Example</title>
 327
 328         <!-- Add a new module in a similar fashion -->
 329
 330         <itemizedlist>
 331           <listitem>
 332             <para><ulink url="example.html">example.xsl</ulink></para>
 333           </listitem>
 334         </itemizedlist>
 335       </section>
 336     </chapter>
 337
 338   </doc:book>
 339
 340 </xsl:stylesheet>