Documentation

Introduction

Well, I don't think a lot of documentation is really necessary here. The task is pretty easy to achieve and going through the example provided in the package will teach you 90% of what you need to know. So here are some steps you should follow :

Think about javadoc, that's exactly the same principle applied to a DTD.
Look at example/dtddoc_features.dtd. You'll see that it's fairly natural to document a DTD.
Look at example/dynamiclist.dtd. For additional examples.
Look at buildant.xml to see how to call DTDDoc from an Ant script.
look at the Maven2 plugin documentation to see how to call DTDDoc as a Maven2 report.

And that's it for the introduction.

Comment composition

The basic idea is that if you want to comment a an element (or an attribute or anything else) in a DTD, you put your comment just before the element. The comment is delimited by , that is, pure XML.

Like in javadoc, DTDDoc comments can be completed with a special structure, delimited by tags. A tag is a single word preceded by @. Here is an example :

<!-- There is no shuffle here, under the north pole, on this quiet dome.

     @title Dynamic List Box
     @doctype dynamiclist SYSTEM "http://dtddoc.sf.net/dynamiclist.dtd"
     @hidden some things should never be told. But everybody should
       know them.
     @root dynamiclist -->

Tags are not always necessary. If you want to comment a simple element (or attribute), just type your comment without any tag. That will do the job. For example :

<!-- A parameter to the filter. For example a filter can ask to get
     elements belonging to a list.-->
<!ELEMENT parameter (#PCDATA)>

If you want to document a list of several attributes, then you have to provide a comment for each of them. Here's an example :

<!-- @attr repository The repository on which to apply the query.
     @attr numberitems The maximum number of items. -->

<!ATTLIST query
        repository (backgrounder) #REQUIRED
        numberitems (1 | 2 | 3 | 4 | 5) "1"
>

Comment's language is HTML. Whatever you'll type will end up "as is" on the HTML pages. Therefore, you have some flexibility in presentation.

To ease the comment writing, a few functionalities have been added:

Auto-paragraphing : Your comment will be cut into paragraphs on blank lines. the <p> tag will be added around them automatically.
XML example can be rendered "as is" by surrounding them with "%". Please note that the < and > characters will be escaped. If you want to control everything, use the <pre> tag instead. Nothing will be escaped there.

Recognized tags

Name	Description

`@attr`	To give a comment to a particular attribute in an attributes list. This tag is only valid for commenting attributes list. This tags require a parameter : the name of the attribute to which it's related.
`@example`	Allows to provide an example for the value of the tag. This example will stand out in the presentation. This tag is more or less to remind the comment author to give a proper example whenever necessary.
`@fixme`	A note indicating a problem that shall be fixed in a near future.
`@hidden`	Allows to write a comment that won't be shown in the documentation. Very useful when you have to transmit the DTD to a customer :) WARNING ! Right now, the comment is not removed from the DTD source code !
`@root`	Must appear in the first comment of the DTD. Gives the root node of the DTD (DTDDoc can not always guess it, to find the reason is left as an exercise :)
`@title`	Should appear in the first comment of the DTD. Allows to give a title to the document. This title will then be used to refer to the DTD instead of using its name. This simple mechanism allows for a much easier readability. If you don't provide it the filename of the DTD will be taken as the title.
`@doctype`	Should appear in the first comment of the DTD. Allows to give the preferred `DOCTYPE` directive to insert in an XML file referencing this DTD.

DTDDoc is an Ant task

Well, more precisely, it's an external Ant task. Therefore, you'll have to work a (very) little to get it running with your Ant. Please note that I have developped the Task mechanism with Ant 1.5. Everything should run fine with older Ant's but I didn't test anything. Success or failure reports in this area would be very helpful.

The basic principle is that you tell the DTDDoc task which DTD files build the documentation for and a few options. It does the rest, outputting a lot of interesting comments.

Here's a copy of buildant.xml showing how to use DTDDoc in a Ant build file :

<?xml version="1.0"?>

<project name="DTDDocAnt" default="main">

    <description>
    This file shows how to call DTDDoc from within Ant.
    </description>

    <!-- Tell ant where to find the code of the DTDDoc task.
            You may have to change this if the two jars are not in your
            path. -->

    <taskdef name="DTDDoc"
             classname="DTDDoc.DTDDocTask"
             classpath="DTDDoc.jar"/>

    <!-- Execute DTDDoc -->

    <target name="main">
        <DTDDoc showHiddenTags="true"
                showFixmeTags="false"
                sourceDir="example"
                destDir="example_doc"
                docTitle = "DTDDoc test title">
            <include name="*.dtd"/>
        </DTDDoc>
    </target>

</project>

So, the work you have to do is to set up the taskdef tag correctly. In our case, it simply tells where to find the DTDDoc.jar files (here, it's assumed to be the current directory). That's all there's to do. Please refer to the Ant documentation for further information.

As an Ant task, DTDDoc accepts <fileset>'s parameters as well as direct <include> and <exclude> as child elements. It can also be further configured by using additional attributes. Here's the list:

Name	Description	Default

`showHiddenTags`	Tells if the content of the `@hidden` tag must be part of the documentation.	no
`showFixmeTags`	Tells if the content of the `@fixme` tag must be part of the documentation.	yes
`docTitle`	Name of the documentation, it will appear at the top of the index.	empty
`sourceDir`	Tells where to get the files from. All the files location expressed in the children elements will be relative to this path.	current dir
`destDir`	Tells where to put the documentation.	current dir.
`styleSheet`	Path to the stylesheet to use to render the documentation. This stylesheet will be copied into the documentation. If not specified, a default stylesheet is generated.	-
`getAroundNetBeansComments`	In case you have comments that start with three hyphens this option will tell DTDDoc to interpret them as regular double hyphens. This was introduced to support NetBeans comments.	true

DTDDoc is a Maven2 plugin

see the Maven2 plugin documentation