Introduction :: News :: Installation :: Documentation :: Mailing list :: Example :: To do's :: Credits
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 :
example/dtddoc_features.dtd. You'll see that it's fairly natural to document a DTD.
example/dynamiclist.dtd. For additional examples.
buildant.xmlto see how to call DTDDoc from an Ant script.
And that's it for the introduction.
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,
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:
<p>tag will be added around them automatically.
>characters will be escaped. If you want to control everything, use the
<pre>tag instead. Nothing will be escaped there.
||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.|
||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.|
||A note indicating a problem that shall be fixed in a near future.|
||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 !
||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 :)|
||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.|
||Should appear in the first comment of the DTD. Allows to give the
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
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
as well as direct
<exclude> as child elements.
It can also be further configured by using additional attributes.
Here's the list:
||Tells if the content of the
||Tells if the content of the
||Name of the documentation, it will appear at the top of the index.||empty|
||Tells where to get the files from. All the files location expressed in the children elements will be relative to this path.||current dir|
||Tells where to put the documentation.||current dir.|
||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.||-|
||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|
see the Maven2 plugin documentation