<?xml version="1.0"?>

<!--
	description:

		"Xslt Tasks"

	library: "Gobo Eiffel Ant"
	copyright: "Copyright (c) 2002, Sven Ehrke and others"
	license: "MIT License"
	date: "$Date: 2007-01-26 10:55:25 -0800 (Fri, 26 Jan 2007) $"
	revision: "$Revision: 5877 $"
-->

<chapter xmlns="http://www.gobosoft.com/eiffel/gobo/documentation" id="xslt_task">
<chapterinfo>
	<copyright>
		<year>2002-2005</year>
		<holder>Sven Ehrke</holder>
	</copyright>
	<author>
		<firstname>Sven</firstname><surname>Ehrke</surname>
	</author>
	<email>ericb@gobosoft.com</email>
	<date>7 July 2005</date>
</chapterinfo>

	<title>xslt</title>

	<section id="xslt_description">
		<title>Description</title>
		<para>
			Invoke XSLT Processor.
		</para>
	</section>

	<section id="xslt_parameters">
		<title>Parameters</title>

		<variablelist>
			<varlistentry>
				<term>processor</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Name of XSLT processor</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>xalan_cpp|xalan_java|xsltproc|gexslt</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>xalan_cpp</para>
				</listitem>
				<listitem>
					<para>
						<emphasis>JDK 1.4 notes: </emphasis>Since with JDK 1.4 Xalan is included
						you do not have to make any additional configuration like putting Xalan, Xerces
						into the classpath. On how to use newer versions of Xalan than the one coming
						with the JDK 1.4 refer to the Xalan homepage on http://xml.apache.org/xalan-j.
						In JDK 1.5 it changed again and by default there is no possibility anymore to invoke
						xalan from the commandline (see http://www.biglist.com/lists/xsl-list/archives/200503/msg01112.html
						for more information) and in addition the packagenames in the JDK changed (from org.apache.xalan.xslt.Process
						to com.sun.org.apache.xalan.internal.xslt.Process). Probably the easies way with JDK 1.5 is to put Xalan again
						in the classpath as it was done with JDK1.3 but I did not spend very much time yet to investigate further.
					</para>
				</listitem>
				
				<listitem>
					<para>
						<emphasis>Java 5 notes: </emphasis>In Java 5 it changed again and by default there is
						no possibility anymore to invoke
						xalan from the commandline (see http://www.biglist.com/lists/xsl-list/archives/200503/msg01112.html
						for more information) and in addition the packagenames in the JDK changed (from org.apache.xalan.xslt.Process
						to com.sun.org.apache.xalan.internal.xslt.Process). Probably the easies way with Java 5 is to put Xalan again
						in the classpath as it was done with JDK 1.3 but I did not spend a lot of time to investigate further.
					</para>
				</listitem>
				
			</varlistentry>

			<varlistentry>
				<term>input</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Name of XML input file</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid filename pointing to existing file</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>xsl</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Name of stylesheet (XSL) file</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid filename pointing to existing file</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>output</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Name of output file</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid filename</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>force</term>
				<listitem>
					<para>
						<emphasis>Description: </emphasis>Execute even if it would not be
						necessary since the outputfile is newer than both the input and the xsl file
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Boolean (true|false)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>false</para>
				</listitem>
			</varlistentry>
			
			<varlistentry>
				<term>indent</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Number of spaces for indentation of child elements</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Integer</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>4</para>
				</listitem>
			</varlistentry>

		</variablelist>
	</section>

	<section id="xslt_specification">
		<title>RNG Specification</title>

		<programlisting><![CDATA[
  <define name="xslt">
    <element name="xslt">
      <ref name="dir_if_unless"/>
      <attribute name="input"/>
      <attribute name="output"/>
      <attribute name="stylesheet"/>
      <optional>
        <attribute name="processor">
          <!-- runtime evaluation
          <choice>
            <value>xalan_cpp</value>
            <value>xalan_java</value>
            <value>xsltproc</value>
          </choice>
          -->
        </attribute>
      </optional>
      <optional>
        <attribute name="force">
          <!-- runtime evaluation
          <choice>
            <value>true</value>
            <value>false</value>
          </choice>
          -->
        </attribute>
      </optional>
      <optional>
        <attribute name="indent"/> <!-- if attribute 'processor' equals 'xalan_java' or 'xalan_cpp'--><-- TODO - implement for gexslt -->
      </optional>
      <optional>
        <attribute name="format"/> <!-- if attribute 'processor' equals 'xalan_java' -->
      </optional>
      <zeroOrMore>
        <element name="parameter">
          <attribute name="name"/>
          <attribute name="value"/>
        </element>
      </zeroOrMore>
      <optional>
        <attribute name="extdirs"/> <!-- if attribute 'processor' equals 'xalan_java' -->
      </optional>
      <optional>
        <attribute name="classpath"/> <!-- if attribute 'processor' equals 'xalan_java' -->
      </optional>
    </element>
  </define>
]]>
  </programlisting>

  </section>

  <section id="xslt_examples">
    <title>Examples</title>

    <para>
      Note that string parameters must be surrounded by a single quote
      ('), else they will be interpreted as a number.
    </para>
    <para>
      For gexslt, all parameters are string values, so the single quotes are
      not needed, unless they contain embedded blanks, which might confuse the shell.
    </para>
    <para>
      Gexslt can also take any XPath expression as a parameter value, but this
      is not possible via geant.
    </para>

  <programlisting><![CDATA[
  <xslt
    input="${GOBO}/doc/structure/index.xml"
    stylesheet="${GOBO}/doc/misc/gobo2db.xsl"
    output="${GOBO}/doc/structure/index2.xml"
  >

  <xslt
    input="${GOBO}/doc/structure/index.xml"
    stylesheet="${GOBO}/doc/misc/gobo2html.xsl"
    output="${GOBO}/doc/structure/index2.html"
  >
    <parameter name="previous" value="&quot;'../license.html'&quot;"/>
    <parameter name="next" value="&quot;'../time/index.html'&quot;"/>
    <parameter name="toc" value="&quot;'../index.html'&quot;"/>
  </xslt>
]]>
  </programlisting>
  </section>

</chapter>
