JPlate Environment 1.2

"How To"

How To

This section describes how to use portions of the Environment but does not describe it all. In most cases, there is sufficiently generated HTML from the included XML files (described below as Ant Doc) that should show enough information to be understandable and usable.

Running The Environment

Utilizing Third Party Libraries

Portions of the Environment rely upon third party libraries (refer to the downloads section of the project requirements). In order to utilize those libraries, Ant versions prior to 1.7.1 require the inclusion of the lib directory as follows:

ant -lib <path to lib directory> [task to execute]

For example, assuming the Environment is installed on a Linux system in /home/shared/jplate-environment-1.0:

ant -lib /home/shared/jplate-environment-1.0/lib [task to execute]

To determine the version of Ant used, enter the following on the command line:

ant -version

Please note: Ant versions 1.7.1 and later require no configuration - meaning the lib directory will be "automagically" extrapolated. Earlier versions have a bug dealing with taskdef's and classpath (meaning the classpath is ignored in the taskdef declaration).

Include The Environment (or only the pieces needed)

As described in the summary, the Environment is reusable - simply include the portions needed:

Macros are provided that act like reusable functions or cross platform scripting. For example, assume one wishes to create a property named CURRENT_TIME whose prefix is "The current date is: " plus the current date/time. The following script illustrates this:

<project name = "ComputeCurrentTime"  xmlns:jplate-utility = "http://jplate.sourceforge.net/"
	<import  file = "/some/dir/to/jplate/ant/utility-macros.xml"/>

	<jplate-utility:compute-timestamp  property = "CURRENT_TIME"  prefix = "The current date is:  "/>

	<echo  message = "${CURRENT_TIME}"/>
</project>

Above, the only portion of the Environment included is utility.xml - nothing more.

XSLT's are provided to convert Ant scripts and/or Subversion log files to HTML. Additionally utility XSLT functions are included as well. The section below, Generate Documentation, provides further examples.

A build environment that can perform such things as generating code, compiling Java, generating documentation and releases, etc. For example, assume one has development needs that include JavaCC generation and Java compilation. The following Ant script will support this functionality:

<project  name = "ExampleOne"  default = "Main"  xmlns:jplate-development = "http://jplate.sourceforge.net/development">
	<import file = "/some/dir/to/jplate/ant/jplate-build.xml"/>
	<target  name = "Main"  depends = "generate-javac, compile-java"/>
</project>

Please note: this is a contrived example but illustrates the simplicity in reusing the build portion of the Environment. The following will do the same as above:

<project  name = "ExampleOne"  default = "Main"  xmlns:jplate-development = "http://jplate.sourceforge.net/development">
	<import file = "/some/dir/to/jplate/ant/jplate-build.xml"/>
	<target  name = "Main"  depends = "compile"/>
</project>

Generate Documentation

The Environment can generate HTML documentation as found below.

Ant Doc

Ant Doc is a macrodef that performs a similar function to Java Doc - usage is expressed in an XML comment preceeding the following elements: import, taskdef, macrodef, scriptdef, and target. Keywords are expanded to represent more meaningful HTML representations as follows:

Keyword	HTML Replacement
@Attributes	<p/><b>Attributes</b>
@Elements	<p/><b>Elements</b>
@Example	<p/><b>Example</b>
@Result	<p/><b>Result</b>
@{	<code>@{
}	}</code>
@attribute:	<br/>
@result:	<br/>
Please note:	<i>Please note:</i>

Consider the following example from utility-macros' assert-equal comment header:

    

When applied using Ant Doc, the HTML result is as follows:

Determines if @{str1} is equal to @{str2}. If the two are not equal, message defined in @{error-msg} is displayed.

Attributes
@{str1} = compared to @{str2}.
@{str2} = compared to @{str1}.
@{error-msg} = if @{str1} not equal to @{str2}, the message when failing will be displayed.

Please note: Ant Doc by itself simply performs a replace of the aforementioned keywords on all files contained within a directory. Therefore, ideally one should use this macrodef after HTML documentation has been generated to a directory. The macrodef's ant2htmlWithNavLinks and ant2html first generate HTML from Ant scripts and then run Ant Doc against the generated HTML.

The following example illustrates using Ant Doc on a directory entitled /some/generated/dir (this is also an example of a cross-platform script):

<project  name = "AntDocExample"  xmlns:jplate-documentation = "http://jplate.sourceforge.net/documentation">
	<import file = "/some/dir/to/jplate/ant/documentation-macros.xml"/>
	<jplate-documentation:antDoc  dir = "/some/generated/dir"/>
</project>

After executing, all the files contained in /some/generated/dir will have the keywords defined above replaced as described.

Ant To HTML

Ant To HTML and Ant To HTML With Navigation Links are macrodefs for converting Ant scripts to HTML documents. Both macrodef's make use of the same XSLT for HTML conversion. Additionally, after conversion both call Ant Doc against the converted HTML files.

The following example illustrates using Ant To HTML to convert an Ant script, /some/project/dir/build.xml, to HTML:

<project  name = "Ant2htmlExample"  xmlns:jplate-documentation = "http://jplate.sourceforge.net/documentation">
	<import file = "/some/dir/to/jplate/ant/documentation-macros.xml"/>
	<jplate-documentation:ant2html  basedir = "/some/project/dir"  destdir = /some/output/dir"  includes = "build.xml"/>
</project>

The HTML conversion is generated to /some/output/dir/build.html. If there had been a number of Ant scripts to convert, the includes attribute might resemble:

<project  name = "Ant2htmlExample"  xmlns:jplate-documentation = "http://jplate.sourceforge.net/documentation">
	<import file = "/some/dir/to/jplate/ant/documentation-macros.xml"/>
	<jplate-documentation:ant2html  basedir = "/some/project/dir"  destdir = /some/output/dir"  includes = "**/*.xml"/>
</project>

Subversion To HTML

Subversion To HTML and Subversion To HTML With Navigation Links are macrodefs for converting Subversion logs to HTML documents. Both macrodef's make use of the same XSLT for HTML conversion.

The following example illustrates using Subversion To HTML to convert the Subversion log a project starting with the initial check in all the way through the current check in:

<project  name = "Svn2htmlExample"  xmlns:jplate-documentation = "http://jplate.sourceforge.net/documentation">
	<import file = "/some/dir/to/jplate/ant/documentation-macros.xml"/>
	<jplate-documentation:ant2html  srcdir = "/some/project/dir"  destdir = /some/output/dir"/>
</project

Above, srcdir is a directory where Subversion files are checked out and destdir is the directory where the converted HTML will be generated.

Building The Environment

To build the Environment simply download the latest source release and use the included build.xml with no targets defined on the command line.