HTMLMacro for Java TM
Docgen Ant Task

Implementation Version: private-20120911-2059
HTMLMacro Reference
The docgen.jar file contains an Ant task implementation, to run the tool from your build script. To use this, first define the task as follows: 
<taskdef name="docgen" classname="com.sun.wts.tools.htmlmacro.HtmlMacroTask">
  <classpath>
    <pathelement path="path/to/docgen.jar" />
  </classpath>
</taskdef>

When running scripts inside HTMLs, this ant task makes a lot of variables available to it. Specifically,

  1. All Ant properties implicitly visible by the <docgen> task
  2. Properties explicitly specified by the <docgen>/<property> tag
  3. All system properties visible to Ant

Therefore, for example, if your build script defines a variable env.BUILD_ID, then you can refer to it simply as ${env.BUILD_ID}. The same goes to all three kinds of variables. If there are name collisions among the variables in these groups, the later one wins. In particular, this allows a system property to override the build script setting. To pass in system property to Ant, use ANT_OPTS environment variable.

Synopsis

Parameter Attributes

Attribute Description Required
destdir The directory in which the generated HTML files are placed. For example, " build/docs". Note that non-HTML resources, such as CSS and images, need to be copied separately. Yes
xhtml By default, htmlmacro reads input documents as HTML, not XML, so that you don't have to write "<br />" or quote every attribute value. However, this process has other side effects --- for example, it moves any HTML content tags in the <head> block inside the body, and this may cause unexpected effects if you use Jelly tags like <define:taglib> inside a header. If set to true, htmlmacro will read inputs as XHTML, and disable all such side effects. No. Defaults to "false"
encoding Encoding of the generated HTML files. When HTML files are loaded from disk via the file:// protocol, they are loaded by using the system default encoding, unless otherwise stated in the meta tag. So it's hard to reliably use any encoding without the meta tag. For this reason, the default is US-ASCII, which is most likely work because most system default encoding is a superset of US-ASCII. If your document contains a lot of characters beyond US-ASCII, specify the encoding here and make sure that your documents have the proper meta tag. No. Defaults to "US-ASCII"

Nested Elements

classpath element

If your source HTMLs use additional Jelly tag libraries, refer to those jars by using this nested classpath element. For the syntax, see "path-like structure".

tags element

This fileset specifies the tag set that use (the *.tag files.)

documents element

This fileset specifies the source HTML documents to be processed. This element is required.

property element

Assign initial values to variables. See the <env> element for the syntax.

Examples

The following example picks up HTML files in docs and generates the result into build/doc. The And property value ${build.id} is used to initialze the IMPL_VERSION variable in the documentation, allowing build id to be printed everywhere in the documentation. 

<docgen destdir="build/doc">
  <documents dir="doc" includes="*.html" />
  <tags dir="doc/tags" includes="**/*.tag" />
  <property key="javaNetProjectName" value="docgen" />
  <property key="IMPL_VERSION" value="${build.id}" />
</docgen>