<?xml version="1.0"?> 

<!--
	description:
	
		"configuration of the XSLT processor"

	library: "Gobo Eiffel XSLT Library"
	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.2 $"
-->

<chapter xmlns="http://www.gobosoft.com/eiffel/gobo/documentation" id="xslt_configuration">
  <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>Tuesday, October 19th, 2004</date>
  </chapterinfo>
  <title>Configuring the XSLT processor</title>
  <para>
    The configuration of the processor is controlled by <classname>XM_XSLT_CONFIGURATION</classname>.
    This has two creation procedures, <featurename>make</featurename> and <featurename>make_with_defaults</featurename>.
    The latter creation procedure takes no arguments, and sets up convenient defaults (as used by the command-line processor gexslt).
    We will look in detail at the arguments to <featurename>make</featurename>.
  </para>
  <section>
    <title>The Entity Resolver</title>
    <para>
      The first argument is an <classname>XM_URI_EXTERNAL_RESOLVER</classname>, for use by 
      the XML parser to resolve
      <exmlsyntax>PUBLIC</exmlsyntax> and <exmlsyntax>SYSTEM</exmlsyntax> external identifiers.
      <featurename>make_with_defaults</featurename> uses a <link linkend="../catalogs">catalog resolver</link>, <classname>XM_CATALOG_RESOLVER</classname>,
      to look up the external identifiers in an OASIS ETRC XML catalog.
    </para>
    <para>
      You can disable the actual catalog lookup by inheriting from  <classname>XM_SHARED_CATALOG_MANAGER</classname>
      and calling <featurecall><featurename>shared_catalog_manager.suppress_catalogs</featurename></featurecall>. In which case
      you will get resolution of the <exmlsyntax>SYSTEM</exmlsyntax> identifier, providing it's URI scheme is one of the registered
      schemes. By default, only <uri>file</uri> and <uri>data</uri> are registered. You can register handlers for additional
      URI schemes by creating a descendant of <classname>XM_URI_RESOLVER</classname> and passing it as the sole argument to
      <featurecall><featurename>shared_catalog_manager.bootstrap_resolver.uri_scheme_resolver.register_scheme</featurename></featurecall>.
      You can do this even if you don't disable the catalog lookup.
    </para>
    <para>
      Despite the flexibility of the catalog resolver, you may still want to provide your own resolver (if you
      want to resolve external entities from a relational database manager, for instance). Just create your own, and
      pass it as the first argument to <featurename>make</featurename>.
    </para>
  </section>
  <section>
    <title>The URI Resolver</title>
    <para>
      The second argument is an <classname>XM_URI_REFERENCE_RESOLVER</classname>. This is used
      to resolve URIs given by the <xslt>xsl:include</xslt> and <xslt>xsl:import</xslt>
      instructions, and the <xpath>document()</xpath> function. <featurename>make_with_defaults</featurename>
      passes the same catalog resolver as it does for the first argument, but there is no obligation that the
      two arguments must receive the same object.
    </para>
  </section>
  <section>
    <title>The Output Resolver</title>
    <para>
      The third argument is an <link linkend="output_resolver"><classname>XM_XSLT_OUTPUT_URI_RESOLVER</classname></link>. This is used to resolve
      the destination URI specified by the <featurename>href</featurename> attribute of <featurename>xsl:result-document</featurename>. 
      It is <emphasis>not</emphasis> used to resolve the principal output destination, as that is under the direct control of
      the user of the XSLT library, not the stylesheet author.
    </para>
    <para>
      <featurename>make_with_defaults</featurename> passes an <classname>XM_XSLT_DEFAULT_OUTPUT_URI_RESOLVER</classname>.
    </para>
  </section>
  <section>
    <title>The Error Listener</title>
    <para>
      The fourth argument is an <link linkend="error_listener"><classname>XM_XSLT_ERROR_LISTENER</classname></link>. This receives
      notifications of warnings, recoverable errors and fatal errors.
    </para>
   <para>
      <featurename>make_with_defaults</featurename> passes an <classname>XM_XSLT_DEFAULT_ERROR_LISTENER</classname>.
    </para>
  </section>
  <section>
    <title>The Encoder Factory</title>
    <para>
      The fifth argument is an <classname>XM_XSLT_ENCODER_FACTORY</classname>. This creates
      output encoders for the various character encodings supported by the library.
    </para>
    <para>
      If you need to create output files in an encoding which is <emphasis>not</emphasis> supported
      by the library, then you will need to create a descendant of <classname>XM_XSLT_OUTPUT_ENCODER</classname>,
      and a descendant of <classname>XM_XSLT_ENCODER_FACTORY</classname> to create your encoder (but better would be to
      offer your encoder to Gobo, for inclusion in the library, if that is possible for you).
    </para>
  </section>
  <section>
    <title>Other features of the configuration</title>
    <para>
      The following other features are of interest to the Eiffel programmer:
      <variablelist>
      	<varlistentry>
	  <term><featurename>set_trace_listener (a_trace_listener: XM_XSLT_TRACE_LISTENER)</featurename></term>
	  <listitem>
	    <para>
	      This sets the <featurename>trace_listener</featurename>. Setting it to a non-<featurename>Void</featurename>
	      value turns on stylesheet execution tracing. See <link linkend="trace_listener">XM_XSLT_TRACE_LISTENER</link>
	      for more details.
	    </para>
	  </listitem>
	</varlistentry>
      	<varlistentry>
	  <term><featurename>set_line_numbering (on_or_off: BOOLEAN)</featurename></term>
	  <listitem>
	    <para>
	      Turns line numbering on and off in diagnostic messages (providing the error listener makes use of the information).
	    </para>
	  </listitem>
	</varlistentry>
     	<varlistentry>
	  <term><featurename>use_tiny_tree_model (true_or_false: BOOLEAN)</featurename></term>
	  <listitem>
	    <para>
	      Selects use of the tiny tree model for building in-memory representations of XML source documents (not used for the stylsheet).
	      This is supposed to save memory, at the possible expense of execution time. 
	      <warning>At present, it seems to leak memory, so avoid it like the plague.</warning>
	    </para>
	  </listitem>
	</varlistentry>
     	<varlistentry>
	  <term><featurename>set_digits (digits: INTEGER)</featurename></term>
	  <listitem>
	    <para>
	      Sets the number of digits to be used when performing decimal arithmetic with
	      XPath expressions. The default is 18 digits, and it may not be set lower than this.
	    </para>
	  </listitem>
	</varlistentry>
    	<varlistentry>
	  <term><featurename>set_external_function_tracing (on_or_off: BOOLEAN)</featurename></term>
	  <listitem>
	    <para>
	      Sets tracing of binding non-system functions on or off. For debugging purposes only.
	      Output goes to the standard error stream.
	    </para>
	  </listitem>
	</varlistentry>
    	<varlistentry>
	  <term><featurename>set_entity_resolver</featurename></term>
	  <listitem>
	    <para>
	      Sets the entity resolver for XML parsing.
	    </para>
	  </listitem>
	</varlistentry>
    	<varlistentry>
	  <term><featurename>set_uri_resolver</featurename></term>
	  <listitem>
	    <para>
	      Set the URI reference resolver for <xslt>xsl:import/include</xslt>
	      processing, and for the <xpath>document()</xpath> function.
	    </para>
	  </listitem>
	</varlistentry>
    	<varlistentry>
	  <term><featurename>set_recovery_policy (a_recovery_policy: INTEGER)</featurename></term>
	  <listitem>
	    <para>
	      Sets the recovery policy, but this only has effect on impure error listeners.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </para>
  </section>
</chapter>

