You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by ge...@apache.org on 2002/02/10 10:44:00 UTC
cvs commit: jakarta-velocity-dvsl/xdocs ant_task_reference.xml more-resources.xml project.xml users-guide.xml
geirm 02/02/10 01:44:00
Modified: xdocs more-resources.xml project.xml users-guide.xml
Added: xdocs ant_task_reference.xml
Log:
Docs for the new, enhanced ant task from Bill Burton <bi...@progress.com>
Thanks Bill!
Revision Changes Path
1.2 +1 -1 jakarta-velocity-dvsl/xdocs/more-resources.xml
Index: more-resources.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity-dvsl/xdocs/more-resources.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- more-resources.xml 18 Dec 2001 20:43:48 -0000 1.1
+++ more-resources.xml 10 Feb 2002 09:44:00 -0000 1.2
@@ -13,7 +13,7 @@
<section name="More Information">
<p>
- For a good basic tutorial on XPAth, see
+ For a good basic tutorial on XPath, see
<a href="http://www.zvon.org/xxl/XPathTutorial/General/examples.html">
this site</a> at <a href="http://www.zevon.org">Zevon.org</a>
</p>
1.2 +1 -0 jakarta-velocity-dvsl/xdocs/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity-dvsl/xdocs/project.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- project.xml 18 Dec 2001 20:43:48 -0000 1.1
+++ project.xml 10 Feb 2002 09:44:00 -0000 1.2
@@ -18,6 +18,7 @@
<menu name="Documentation">
<item name="Users Guide" href="/users-guide.html"/>
+ <item name="Ant Task Reference" href="/ant_task_reference.html"/>
<item name="More Resources" href="/more-resources.html"/>
</menu>
1.4 +8 -54 jakarta-velocity-dvsl/xdocs/users-guide.xml
Index: users-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity-dvsl/xdocs/users-guide.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- users-guide.xml 7 Feb 2002 05:39:27 -0000 1.3
+++ users-guide.xml 10 Feb 2002 09:44:00 -0000 1.4
@@ -123,6 +123,14 @@
</target>
]]></source>
+
+
+ <p>
+ For more information on using DVSL from Ant, please see the
+ <a href="ant_task_reference.html">Ant Task Reference</a>.
+ </p>
+
+
</section>
<section name="Starting with Examples">
@@ -549,61 +557,7 @@
</section>
- <section name="Using DVSL via Ant">
-
- <p>
- Here are some important notes about using DVSL with Ant. These will be
- revised into a more coherant section on using with Ant:
- </p>
- <strong>Configuring the Velocity Engine</strong>
-
- <p>
- It is now possible to configure the Velocity Engine when using DVSL
- with Ant (and from your code, of course). This feature enables you to
- set template paths, VelociMacro libraries, loggers, etc.
- </p>
-
- <p>
- To use, you need to make a public class that implements
- <code>java.util.Map</code>. Then place this class in the classpath, and
- set the property 'velocityConfigClass'
- to the name of your class :
- </p>
-
- <source><![CDATA[
- <dvsl
- basedir="${docs.src}"
- destdir="${docs.dest}/"
- extension=".html"
- style="${docs.src}/site.dvsl"
- excludes="**/project.xml"
- toolbox="toolbox.props"
- includes="**/*.xml"
-
- velocityConfigClass="ConfigVel"
-
- />
-
- ]]></source>
-
- <p>
- Please see <code>examples/simple</code> for an example of this
- technique.
- </p>
-
- <strong>Input and Output Filename</strong>
- <p>
- You can now access the name of the input file and the output file
- inside the stylesheet. They can be accessed as
- </p>
- <source><![CDATA[
- $inputfilename
- $outputfilename
- ]]>
- </source>
-
- </section>
<section name="Default Template Rules">
1.1 jakarta-velocity-dvsl/xdocs/ant_task_reference.xml
Index: ant_task_reference.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>DVSL Ant Task Reference</title>
<author email="billb@progress.com">Bill Burton</author>
<meta http-equiv="Content-Language" content="en-us" />
<base href="http://jakarta.apache.org/ant/manual/CoreTasks/" />
</properties>
<body>
<section name="DVSL Ant Task Reference">
<p>
Processes a set of XML documents using a stylesheet written in DVSL
(Declarative Velocity Style Language).
</p>
<p>
This is useful for building views of XML based documentation,
or for generating code, etc. Conceptually, this task performs the same
function as the <style> task included with the Ant distribution
but using a stylesheet with DVSL syntax instead of XSLT.
</p>
<p>
As DVSL has a tight binding with Java objects, access is provided to
the "Toolbox" which loads properties and objects which are then exposed to
the stylesheet in a transparent manner.
</p>
<p>
Since DVSL utilizes Velocity for rendering its output, access is
provided to allow configuring the Velocity runtime environment from within
this task.
</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="../CoreTypes/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>
DVSL supports the use of a <tool> element which is used to pass values
to the DVSL toolbox configuration.
</p>
</section>
<section name="Parameters">
<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".</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
</td>
<td align="center" valign="top">Yes</td>
</tr>
<tr>
<td valign="top">classpath</td>
<td valign="top">classpath to use when loading toolbox and velocity
configuration classes.</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</td>
</tr>
<tr>
<td valign="top">includes</td>
<td valign="top">comma 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 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">toolboxfile</td>
<td valign="top">specifies the toolbox properties file name.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">velocityconfigclass</td>
<td valign="top">specifies a class to load which sets Velocity properties.
The class must implement the <code>java.util.Map</code> interface.</td>
<td valign="top" align="center">No</td>
</tr>
</table>
</section>
<section name="Parameters specified as nested elements">
<subsection name="classpath">
<p>Classpath to use when loading toolbox and velocity configuration
classes. This is defined using a
<a href="../using.html#path">path</a>-like structure.</p>
</subsection>
<subsection name="tool">
<p>Set a toolbox property. Properties specified with this nested element
override those defined in a properties file specified by the
<code>toolboxfile</code> attribute.</p>
<strong>Parameters</strong>
<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 toolbox property</td>
<td align="center" valign="top">Yes</td>
</tr>
<tr>
<td valign="top">value</td>
<td valign="top">Value of the toolbox property.</td>
<td align="center" valign="top">Yes</td>
</tr>
</table>
</subsection>
<subsection name="velconfig">
<p>Velconfig is used to set a Velocity configuration property. Properties
specified with this nested element override those defined in a class loaded
via the <code>velocityconfigclass</code> attribute. </p>
<strong>Parameters</strong>
<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 Velocity configuration property</td>
<td align="center" valign="top">Yes</td>
</tr>
<tr>
<td valign="top">value</td>
<td valign="top">Value of the Velocity configuration property.</td>
<td align="center" valign="top">Yes</td>
</tr>
</table>
</subsection>
</section>
<section name="Declaring the DVSL Task in the build file">
<p>This task as with any other task not shipped with Ant must be defined
in the build file using a <code><taskdef></code> declaration. For
example, the following declaration associates a task named <dvsl>
with the class <code>org.apache.tools.dvsl.DVSLTask</code>. In addition,
the required jars for DVSL support are specified in classpath using a
FileSet.</p>
<source><![CDATA[
<taskdef name="dvsl" classname="org.apache.tools.dvsl.DVSLTask">
<classpath>
<fileset dir="${lib.dir}">
<include name="velocity-dvsl-*.jar" />
<include name="velocity-dep-*.jar" />
<include name="dom4j-*.jar" />
</fileset>
</classpath>
</taskdef>
]]></source>
</section>
<section name="Examples">
<p><strong>Simple case running a transformation on all files in a
directory:</strong></p>
<source><![CDATA[
<dvsl basedir="doc" destdir="build/doc"
extension=".html" style="style/apache.dvsl" />
]]></source>
<p><strong>Using parameters to set Toolbox and Velocity
properties:</strong></p>
<source><![CDATA[
<dvsl basedir="doc" destdir="build/doc"
extension=".html" style="style/apache.xsl"
classpath=".">
<tool name="toolbox.string.mystring" value="Some arbitrary text" />
<tool name="toolbox.tool.footool" value="Footool" />
<velconfig name="runtime.log" value="${basedir}/dvsl.log" />
</dvsl>
]]></source>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>