<?xml version="1.0" encoding="UTF-8"?> 

<!--
	description:
	
		"Gobo Eiffel XSLT extensions"

	library: "Gobo Eiffel XSLT"
	copyright: "Copyright (c) 2004, Colin Adams and others"
	license: "Eiffel Forum License v2 (see forum.txt)"
	date: "$Date: 2005/07/07 18:37:45 $"
	revision: "$Revision: 1.7 $"
-->

<chapter xmlns="http://www.gobosoft.com/eiffel/gobo/documentation" id="gexslt_extensions">
  <chapterinfo>
    <copyright>
      <year>2004</year>
      <holder>Colin Adams and others</holder>
    </copyright>
    <author>
      <firstname>Colin</firstname>
      <surname>Adams</surname>
    </author>
    <email>colin@colina.demon.co.uk</email>
    <date>Wednesday, November 24th, 2004</date>
  </chapterinfo>
  <title>Extensions</title>
  <para>
    All extensions are in the namespace <uri>http://www.gobosoft.com/eiffel/gobo/gexslt/extension</uri>.
  </para>
  <section>
    <title>Extension attributes</title>
    <para>
      The following extension attributes are available:
      <variablelist>
	<varlistentry>
	  <term><exmlsyntax>explain</exmlsyntax></term>
	  <listitem>
	    <para>
	      This attribute may be set on any instruction in the stylesheet, or on a literal result element. The permitted values are "yes", "no" and "all". 
	      If the value is "yes", then at compile time an analysis of all XPath expressions appearing as attributes of that element is written to the standard
	      error stream. The analysis includes the static type of the expression, and a representation of the expression tree that results from parsing and optimization.
	      The tree structure is represented by indentation.
	    </para>
	    <para>
	      The value of "all" only takes effect on xsl:stylesheet and xsl:transform elements. It is treated as if "yes" was coded.
	      Additionally, if this is the prinicpal stylesheet, then the instructions themselves, when compiled to an expression,
	      have their compiled form displayed. (Only xsl:templates, top-level xsl:variables and xsl:params, and xsl:function definitions
	      are displayed.)
	      <warning>This can produce a lot of output.</warning>
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><exmlsyntax>memo-function</exmlsyntax></term>
	  <listitem>
	    <para>
	      This attribute may be set on any xsl:function declaration in the stylesheet. The permitted values are "yes" and "no". 
	      If the value is "yes", then the result of calling the function with a given set of parameters is cached.
	    </para>
	    <para>
	      <warning>
		This should not be set to "yes" if the function has any side effects (which can only occur if it uses
		user-written extension functions with side-effects), or if it access context information, such as position(),
		last() or the context item.
	      </warning>
	    </para>
	    <para>
	      <warning>
		If the function constructs and returns a temporary tree, the same tree will be returned each time. The only consequence
		of this is if you compare node identities on that tree. 
	      </warning>
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><exmlsyntax>character-representation</exmlsyntax></term>
	  <listitem>
	    <para>
	      This tells the serializer how to serialize non-ASCII characters, and characters that are not representable
	      in the selected encoding.
	    </para>
	    <para>
	      When the output method is "xml" or "xhtml" <warning>(Hm.maybe xhtml should follow the html behaviour)</warning>,
	      this parameter only effects characters that are not representable
	      in the selected encoding. It can take on the value "hex" or "decimal", and it determines whether 
	      the character is written out with a decimal character reference, or a hexadecimal 
	      character reference (the default).
	    </para>
	    <para>
	      When the output method is "html", then the value may hold two strings, separated by a semicolon.
	      The first string defines how non-ASCII characters within the character encoding will be represented, 
	      the values being "native", "entity", "decimal", or "hex". 
	      The second string defines how characters outside the encoding will be represented, the values being 
	      "entity", "decimal", or "hex". Here "native" means output the character as itself; "entity" means 
	      use a defined entity reference (such as "&amp;eacute;") if known; "decimal" and "hex" refer to numeric 
	      character references. For example "entity;decimal" (the default) means that with encoding="iso-8859-1", 
	      characters in the range 160-255 will be represented using standard HTML entity references, while 
	      Unicode characters above 255 will be represented as decimal character references.
	    </para>
	    <para>
	      This parameter has no meaning when the output method is "text". For <exmlsyntax>QName</exmlsyntax> output methods,
	      it's interpretation is up to the programmer of the method, but the possible values are those for the 
	      "html" method.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><exmlsyntax>indent-spaces</exmlsyntax></term>
	  <listitem>
	    <para>
	      This tells the serializer how many spaces to add for indentation when <xslt>indent="yes"</xslt> is specified.
	      It is ignored when <xslt>indent="no"</xslt> is specified, or is omitted and the default
	      for the serialization method is "no". If you omit this parameter, then three spaces are used 
	      (but check the creation procedure for <classname>XM_XSLT_OUTPUT_PROPERTIES</classname> to confirm
	      this, in case it gets changed and I forget to update the documentation).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><exmlsyntax>next-in-chain</exmlsyntax></term>
	  <listitem>
	    <para>
	      To be documented. (See the programs in $GOBO/test/xml/xslt for an example of how to use it).
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </para>
  </section>
 <section>
    <title>User-defined data elements</title>
    <para>
      The only user-defined data element provided by the library is <exmlsyntax>collation</exmlsyntax>.
      This is intended for declaring collation-URI names, but as the only collation supported is
      the default one at the moment, it is not much use (I use it for binding additional URIs to the default collation,
      to test the collation-naming mechanism). When a tailorable collation based on the Unicode Collation Algorithm is
      available, then this will be used to bind URI names to tailored collations.
    </para>
 </section>
 <section>
    <title>Extension instructions</title>
    <para>
      None are provided at present.
    </para>
 </section>
 <section>
    <title>Additional output methods</title>
    <para>
      None are provided in the extension namespace.
    </para>
    <para>
      However, there is an example provided to show Eiffel programmers
      how to write their own output methods. This is in the namespace 
      <uri>http://www.gobosoft.com/eiffel/gobo/gexslt/extension/example</uri>, and has
      a local name of <exmlsyntax>xml</exmlsyntax>. It functions identically to the standard
      <xslt>xml</xslt> method, unless the extension attribute <exmlsyntax>internal-subset</exmlsyntax> (in the same
      namespace) is supplied. In which case, it's value is used as the text for a DTD internal subset. You
      must also supply <xslt>doctype-system</xslt> for this to work.
    </para>
 </section>
 <section>
    <title>Extension functions</title>
    <para>
      None are provided at present.
    </para>
 </section>

</chapter>

