diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Tasks/style.html')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/manual/Tasks/style.html | 629 |
1 files changed, 629 insertions, 0 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Tasks/style.html b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/style.html new file mode 100644 index 00000000..f02b98eb --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/style.html @@ -0,0 +1,629 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>XSLT Task</title> +</head> + +<body> + +<h2><a name="style">XSLT</a></h2> +<p><em>The name <code>style</code> is a deprecated name for the same task.</em></p> +<h3>Description</h3> +<p>Process a set of documents via XSLT.</p> +<p>This is useful for building views of XML based documentation, +or for generating code.</p> +<p><b>Note:</b> If you are using JDK 1.4 or higher, this task does not require external libraries +not supplied in the Apache Ant distribution. However, often the built in XSL engine is not as up +to date as a fresh download, so an update is still highly recommended + in particular since the built-in XSLT processors of Java 5 (and to a + certain extent Java 6) are known to have serious issues. +See <a href="../install.html#librarydependencies">Library Dependencies</a> for more information.</p> +<p>It is possible to refine the set of files that are being processed. This can be +done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i> +attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to +have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify +the files you want to have excluded. This is also done with patterns. And +finally with the <i>defaultexcludes</i> attribute, you can specify whether you +want to use default exclusions or not. See the section on <a +href="../dirtasks.html#directorybasedtasks">directory based tasks</a>, on how the +inclusion/exclusion of files works, and how to write patterns.</p> +<p>This task forms an implicit <a href="../Types/fileset.html">FileSet</a> and supports all + attributes of <code><fileset></code> (<code>dir</code> becomes <code>basedir</code>) + as well as the nested <code><include></code>, <code><exclude></code> + and <code><patternset></code> elements.</p> + +<p><b>Note</b>: Unlike other similar tasks, this task treats +directories that have been matched by the include/exclude patterns of +the implicit fileset in a special way. It will apply the stylesheets +to all files contain in them as well. Since the default include +pattern is <code>**</code> this means it will apply the stylesheet to +all files. If you specify an excludes pattern, it may still work on +the files matched by those patterns because the parent directory has +been matched. If this behavior is not what you want, set the +scanincludedirectories attribute to false.</p> + +<p>Starting with Ant 1.7 this task supports nested <a +href="../Types/resources.html#collection">resource collection</a>s +in addition to (or instead of, depending on the useImplicitFileset +attribute) the implicit fileset formed by this task.</p> + +<p>This task supports the use of a nested <code><param></code> element which is used to pass values + to an <code><xsl:param></code> declaration.</p> +<p>This task supports the use of a nested <a href="../Types/xmlcatalog.html">xmlcatalog</a> +element which is used to perform Entity and URI resolution.</p> +<h3>Parameters</h3> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">basedir</td> + <td valign="top">where to find the source XML file, default is the + project's basedir.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">destdir</td> + <td valign="top">directory in which to store the results.</td> + <td align="center" valign="top">Yes, unless in and out have been + specified.</td> + </tr> + <tr> + <td valign="top">extension</td> + <td valign="top">desired file extension to be used for the targets. If not + specified, the default is ".html". Will be ignored if + a nested <code><mapper></code> has been specified.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">style</td> + <td valign="top">name of the stylesheet to use - given either relative + to the project's basedir or as an absolute path.<br/> + <br/> + Alternatively, a nested element which ant can interpret as a resource + can be used to indicate where to find the stylesheet<br/> + <em>deprecated variation :</em> <br/> + If the stylesheet cannot be found, and if you have specified the + attribute basedir for the task, ant will assume that the style + attribute is relative to the basedir of the task. + </td> + <td align="center" valign="top">No, if the location of + the stylesheet is specified using a nested <style> element</td> + </tr> + <tr> + <td valign="top">classpath</td> + <td valign="top">the classpath to use when looking up the XSLT + processor.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">classpathref</td> + <td valign="top">the classpath to use, given as <a + href="../using.html#references">reference</a> to a path defined elsewhere.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">force</td> + <td valign="top">Recreate target files, even if they are newer + than their corresponding source files or the stylesheet.</td> + <td valign="top" align="center">No; default is false</td> + </tr> + <tr> + <td valign="top">processor</td> + + <td valign="top">name of the XSLT processor to use. + Permissible value is :<ul> + <li>"trax" for a TraX compliant processor (ie JAXP interface + implementation such as Xalan 2 or Saxon)</li></ul> + Defaults to trax. + <br/> + Support for xalan1 has been removed in ant 1.7. + </td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">includes</td> + <td valign="top">comma- or space-separated list of patterns of files that must be included. + All files are included when omitted.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">includesfile</td> + <td valign="top">the name of a file. Each line of this file is taken to be + an include pattern</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">excludes</td> + <td valign="top">comma- or space-separated list of patterns of files that must be excluded. + No files (except default excludes) are excluded when omitted.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">excludesfile</td> + <td valign="top">the name of a file. Each line of this file is taken to be + an exclude pattern</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">defaultexcludes</td> + <td valign="top">indicates whether default excludes should be used or not + ("yes"/"no"). Default excludes are used when omitted.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">in</td> + <td valign="top">specifies a single XML document to be styled. Should be used + with the out attribute.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">out</td> + <td valign="top">specifies the output name for the styled result from the + in attribute.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">scanincludeddirectories</td> + <td valign="top">If any directories are matched by the + includes/excludes patterns, try to transform all files in these + directories. Default is <code>true</code></td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">reloadstylesheet</td> + <td valign="top">Control whether the stylesheet transformer is created + anew for every transform operation. If you set this to true, performance may + suffer, but you may work around a bug in certain Xalan-J versions. + Default is <code>false</code>. <em>Since Ant 1.5.2</em>.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">useImplicitFileset</td> + <td valign="top">Whether the implicit fileset formed by this task + shall be used. If you set this to false you must use nested + resource collections - or the in attribute, in which case this + attribute has no impact anyway. Default is <code>true</code>. + <em>Since Ant 1.7</em>.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">filenameparameter</td> + <td valign="top">Specifies a xsl parameter for accessing the name + of the current processed file. If not set, the file name is not + passed to the transformation. + <em>Since Ant 1.7</em>.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">filedirparameter</td> + <td valign="top">Specifies a xsl parameter for accessing the directory + of the current processed file. For files in the current directory a + value of '.' will be passed to the transformation. + If not set, the directory is not passed to the transformation. + <em>Since Ant 1.7</em>.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">suppressWarnings</td> + <td valign="top">Whether processor warnings shall be suppressed. + This option requires support by the processor, it is supported by + the trax processor bundled with Ant. + <em>Since Ant 1.8.0</em>.</td> + <td valign="top" align="center">No, default is false.</td> + </tr> + <tr> + <td valign="top">failOnError</td> + <td valign="top">Whether the build should fail if any error + occurs. Note that transformation errors can still be suppressed by + setting failOnTransformationError to false even if this attribute + is true. + <em>Since Ant 1.8.0</em>.</td> + <td valign="top" align="center">No, default is true.</td> + </tr> + <tr> + <td valign="top">failOnTransformationError</td> + <td valign="top">Whether the build should fail if an error occurs + while transforming the document. Note that this attribute has no + effect of <code>failOnError</code> is false. + <em>Since Ant 1.8.0</em>.</td> + <td valign="top" align="center">No, default is true.</td> + </tr> + <tr> + <td valign="top">failOnNoResources</td> + <td valign="top">Whether the build should fail if the nested + resource collection is empty. Note that this attribute has no + effect of <code>failOnError</code> is false. + <em>Since Ant 1.8.0</em>.</td> + <td valign="top" align="center">No, default is true.</td> + </tr> +</table> +<h3>Parameters specified as nested elements</h3> + +<h4>any <a href="../Types/resources.html#collection">resource +collection</a></h4> + +<p><em>since Ant 1.7</em></p> + +<p>Use resource collections to specify resources that the stylesheet +should be applied to. Use a nested mapper and the task's destdir +attribute to specify the output files.</p> + +<h4><a name="classpath">classpath</a></h4> +<p>The classpath to load the processor from can be specified via a +nested <code><classpath></code>, as well - that is, a +<a href="../using.html#path">path</a>-like structure.</p> + +<h4>xmlcatalog</h4> +<p>The <a href="../Types/xmlcatalog.html">xmlcatalog</a> +element is used to perform Entity and URI resolution.</p> + +<h4>param</h4> +<p>Param is used to pass a parameter to the XSL stylesheet.</p> +<blockquote> +<h4>Parameters</h4> +<table width="60%" border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">Name of the XSL parameter</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">expression</td> + <td valign="top"> + The value to be placed into the param or an XPath expression + (depending on <code>type</code>). + </td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">type</td> + <td valign="top"> + Data type of the parameter. Possible values are: + <ul> + <li><code>STRING</code></li> + <li><code>BOOLEAN</code></li> + <li><code>INT</code></li> + <li><code>LONG</code></li> + <li><code>DOUBLE</code></li> + <li><code>XPATH_STRING</code></li> + <li><code>XPATH_BOOLEAN</code></li> + <li><code>XPATH_NUMBER</code></li> + <li><code>XPATH_NODE</code></li> + <li><code>XPATH_NODESET</code></li> + </ul> + <em>since Ant 1.9.3</em> + </td> + <td align="center" valign="top">No; default is <code>STRING</code></td> + </tr> + <tr> + <td valign="top">if</td> + <td valign="top">The param will only be passed <a href="../properties.html#if+unless">if this property is set</a>.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">unless</td> + <td valign="top">The param will not be passed <a href="../properties.html#if+unless">if this property is set</a>.</td> + <td align="center" valign="top">No</td> + </tr> + +</table> +</blockquote> + + <p> + The <code>XPATH_*</code> types says that the <code>expression</code> is not just a primitive-type value but an XPath expression. + This expression will be evaluated on an empty XML document and the result will be passed to the XSLT transformer as a parameter of given type. + In these expressions the declared Ant properties can be used as XPath variables e.g. <code>$someProperty</code>. + So you can compute something using standard XPath functions and operators. + </p> + <p> + If you write <code>${someProperty}</code> instead of <code>$someProperty</code>, + the value will be simply substituted by Ant before evaluating the XPath expression + (this substitution works also for primitive types). + </p> + +<h4>outputproperty ('trax' processors only)</h4> +<p>Used to specify how you wish the result tree to be output +as specified in the <a href="http://www.w3.org/TR/xslt#output"> +XSLT specifications</a>. +<blockquote> +<h4>Parameters</h4> +<table width="60%" border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">Name of the property</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">value</td> + <td valign="top">value of the property.</td> + <td align="center" valign="top">Yes</td> + </tr> +</table> +</blockquote> + +<h4><a name="factory">factory ('trax' processors only)</a></h4> +Used to specify factory settings. +<blockquote> +<h4>Parameters</h4> +<table width="60%" border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">fully qualified classname of the + transformer factory to use. For example + <tt>org.apache.xalan.processor.TransformerFactoryImpl</tt> + or <tt>org.apache.xalan.xsltc.trax.TransformerFactoryImpl</tt> + or <tt>net.sf.saxon.TransformerFactoryImpl</tt>... + </td> + <td align="center" valign="top">No. Defaults to the JAXP lookup mechanism.</td> + </tr> +</table> +<h3>Parameters specified as nested elements</h3> +<h4>attribute </h4> +<p>Used to specify settings of the processor factory. +The attribute names and values are entirely processor specific +so you must be aware of the implementation to figure them out. +Read the documentation of your processor. +For example, in Xalan 2.x: +<ul> +<li>http://xml.apache.org/xalan/features/optimize (boolean)</li> +<li>http://xml.apache.org/xalan/features/incremental (boolean)</li> +<li>...</li> +</ul> +And in Saxon 7.x: +<ul> +<li>http://saxon.sf.net/feature/allow-external-functions (boolean)</li> +<li>http://saxon.sf.net/feature/timing (boolean)</li> +<li>http://saxon.sf.net/feature/traceListener (string)</li> +<li>http://saxon.sf.net/feature/treeModel (integer)</li> +<li>http://saxon.sf.net/feature/linenumbering (integer)</li> +<li>...</li> +</ul> +<blockquote> +<h4>Parameters</h4> +<table width="60%" border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">Name of the attribute</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">value</td> + <td valign="top">value of the attribute.</td> + <td align="center" valign="top">Yes</td> + </tr> +</table> +</blockquote> +</blockquote> +<h4>mapper</h4> + +<p><em>since Ant 1.6.2</em></p> + +<p>You can define filename transformations by using a nested <a +href="../Types/mapper.html">mapper</a> element. The default mapper +used by <code><xslt></code> removes the file extension from the +source file and adds the extension specified via the extension +attribute.</p> + +<h4>style</h4> + +<p><em>Since Ant 1.7</em></p> + +<p>The nested style element can be used to specify your stylesheet in terms +of Ant's <a href="../Types/resources.html">resource</a> types. With +this element, the stylesheet should be specified as a nested resource or +single-element collection. Alternatively, use the <code>refid</code> to +specify the resource or collection as a reference.</p> + +<h4>sysproperty</h4> +<p>Use nested <code><sysproperty></code> elements to specify +system properties required by the factory or transformation. These +properties will be made available to the VM during the execution of +the class. The attributes for this element are the same as +for <a href="exec.html#env">environment variables</a>.</p> + +<p><em>since Ant 1.8.0</em>.</p> + +<h4>syspropertyset</h4> + +<p>You can specify a set of properties to be used as system properties +with <a href="../Types/propertyset.html">syspropertyset</a>s.</p> + +<p><em>since Ant 1.8.0</em>.</p> + +<h3>Examples</h3> +<blockquote> + <pre> +<xslt basedir="doc" destdir="build/doc" + extension=".html" style="style/apache.xsl"/></pre> + <h4>Using an xmlcatalog</h4> + <pre> +<xslt basedir="doc" destdir="build/doc" + extension=".html" style="style/apache.xsl"> + <xmlcatalog refid="mycatalog"/> +</xslt> + +<xslt basedir="doc" destdir="build/doc" + extension=".html" style="style/apache.xsl"> + <xmlcatalog> + <dtd + publicId="-//ArielPartners//DTD XML Article V1.0//EN" + location="com/arielpartners/knowledgebase/dtd/article.dtd"/> + </xmlcatalog> +</xslt> +</pre> + <h4>Using XSL parameters</h4> + <p>Simple String parameter:</p> +<pre> +<xslt basedir="doc" destdir="build/doc" + extension=".html" style="style/apache.xsl"> + <param name="date" expression="07-01-2000"/> +</xslt></pre> + + <p>Then if you declare a global parameter "date" with the top-level + element <xsl:param name="date"/>, the variable + <code>$date</code> will subsequently have the value 07-01-2000. + </p> + + <p>Various data types and XPath expressions:</p> + + <pre><property name="antProperty1" value="ANT_PROPERTY_1"/> +<property name="antProperty2" value="ANT_PROPERTY_2"/> +<property name="antProperty3" value="3"/> +<property name="antProperty4" value="substring-before"/> + +<!-- + ${this} is substituted by Ant itself + and $this is evaluated by XPath as a variable +--> + +<xslt in="in.xml" out="out.xml" style="template.xsl"> + + <!-- Simple String parameter: --> + <param name="p0" expression="some nice string" type="STRING"/> + + <!-- A value substituted by Ant --> + <param name="p1" expression="some string with ${antProperty1} constructed by Ant" type="STRING"/> + + <!-- XPath resulting in: and this is done in XPath: ANT_PROPERTY_2 --> + <param name="p2" expression="concat('and this is done in XPath: ', $antProperty2)" type="XPATH_STRING"/> + + <!-- Some XPath math, result: 42 --> + <param name="p3" expression="64 * 64 div 128 + 10" type="XPATH_NUMBER"/> + + <!-- Some numeric parameter: --> + <param name="p4" expression="123.45" type="DOUBLE"/> + + <!-- XPath expression, result: true boolean --> + <param name="p5" expression="$antProperty1 = 'ANT_PROPERTY_1'" type="XPATH_BOOLEAN"/> + + <!-- First one is an XPath variable, second one is a text substituted by Ant, result: true boolean --> + <param name="p6" expression="$antProperty2 = '${antProperty2}'" type="XPATH_BOOLEAN"/> + + <!-- Some XPath math with a variable, result: 64 --> + <param name="p7" expression="$antProperty3 * 4 * 5 + 4" type="XPATH_NUMBER"/> + + <!-- + XPath expression with substituted function name and a variable: + substring-before($antProperty2, '_') + result: ANT + --> + <param name="p8" expression="${antProperty4}($antProperty2, '_')" type="XPATH_STRING"/> + + <!-- Without type attribute: --> + <param name="p9" expression="default type is String"/> +</xslt></pre> + + <h4>Using output properties</h4> +<pre> +<xslt in="doc.xml" out="build/doc/output.xml" + style="style/apache.xsl"> + <outputproperty name="method" value="xml"/> + <outputproperty name="standalone" value="yes"/> + <outputproperty name="encoding" value="iso8859_1"/> + <outputproperty name="indent" value="yes"/> +</xslt> +</pre> + + <h4>Using factory settings</h4> +<pre> +<xslt in="doc.xml" out="build/doc/output.xml" + style="style/apache.xsl"> + <factory name="org.apache.xalan.processor.TransformerFactoryImpl"> + <attribute name="http://xml.apache.org/xalan/features/optimize" value="true"/> + </factory> +</xslt></pre> + + <h4>Using a mapper</h4> +<pre> +<xslt basedir="in" destdir="out" + style="style/apache.xsl"> + <mapper type="glob" from="*.xml.en" to="*.html.en"/> +</xslt></pre> + + <h4>Using a nested resource to define the stylesheet</h4> + <pre> +<xslt in="data.xml" out="${out.dir}/out.xml"> + <style> + <url url="${printParams.xsl.url}"/> + </style> + <param name="set" expression="value"/> +</xslt></pre> + + <h4>Print the current processed file name</h4> +<pre> +<project> + <xslt style="printFilename.xsl" destdir="out" basedir="in" extension=".txt" + filenameparameter="filename" + filedirparameter="filedir" + /> +</project> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> + + <xsl:param name="filename"></xsl:param> + <xsl:param name="filedir">.</xsl:param> + +<xsl:template match="/"> + Current file is <xsl:value-of select="$filename"/> in directory <xsl:value-of select="$filedir"/>. +</xsl:template> + +</xsl:stylesheet> +</pre> + +<h4>Use an XInclude-aware version of Xerces while transforming</h4> + +<pre> +<xslt ...> + <sysproperty key="org.apache.xerces.xni.parser.XMLParserConfiguration" + value="org.apache.xerces.parsers.XIncludeParserConfiguration" + /> +<xslt> +</pre> +</blockquote> + + +</body> +</html> |