HTMLMacro for Java
TM
Overview
Implementation Version: private-20120911-2059
Overview
This tool is:
-
Macro-engine on top of HTML that allows portions of the documentation to be generated programatically --- it's like JSP/JSTL outside the container, or even think of it as Lisp on top of HTML. Macros can be made reusable, and such reusable macro is called
tag set.
-
Tag set for software release notes, AKA JAX-* tag set, which is built on top of the above programability. This template is ideal for generating release note documents, like the one you are seeing right now.
Why?
To satisfy common use case like the following:
-
Release notes need to refer to the version number of the software in all over the places, so you don't want to just hand-write them in HTML. Instead, you want a variable. With this tool, you can do that by writing
${variableName} and have the tool replace it by the actual value given by the Ant build script.
-
Release notes often need be slightly different depending on the delivery vehicles. This tool lets you define such conditional statement like
<j:if test="${isJWSDP}" xmlns:j="jelly:core">
... this shows up only in JWSDP ...
</j:if>
Or even a switch/case statement.
-
Release notes often need to list jar files, or list all the samples in the distribution. This tool enables complete programability over those. So instead of listing them in HTML and suffer the inevitable inconsistency, you can simply write a little script and have the tool generate it.
-
Release notes often need to list a changelog. Or a list of bugs that are fixed. And you want to format them nicely. Scriptability allows you to just write a little macro and then put the following in your source HTML:
<bugfixes>
<bug>611352</bug>
<bug>614252</bug>
<bug>611418</bug>
</bugfixes>
... and have the tool convert this into a nice table complete with hyperlink and coloring based on severity and everything else you need.
How does it work?
Typical workflow of this tool goes like this:
- You write a set of documents in HTML, images, and CSS, just like you do normally. In particular, HTMLs need not be XHTML.
- You embed macros in your HTML here and there.
- As a part of the build script, run
the docgen ant task and generate the final HTML.
Getting Started
The quickest way to get started is to use
the JAX-* tag set. For more details about how to write your own macro, see