Tutorial: Intro & simple example

This tutorial will guide you into the work with Natural DTD, a documentation generator for DTD files.

The name for this project comes from the transformation of an abstract DTD into an (natural) easier human readable document.

The call of the programm is also oriented on the natural human language.

Note: For easier handling of java classpath settings, a batch file called "naturalDTD.bat" has been created. It does nothing else than calling java -cp [some-required-jar-files] com.reboo.naturaldtd.NaturalDTD %1 %2 %3 %4 %5 %6 %7 %8 %9. The numbers at the end of the call just delegate the command line arguments to the java program.

This means you may call the programm typing either java -cp [some-required-jar-files] com.reboo.naturaldtd.NaturalDTD param 1 param 2 param 3 or naturalDTD param 1 param 2 param 3. In this tutorial the easier latter version will always be used.

To get an overview over all possible command line argurments of Natural DTD, type naturalDTD help.

Most important parameters:

from <sourcefile> Defines the source DTD you want to create a documentation for.
to <target-path> Detefines the directory used for output
like <Template-XML-file> Defines the xml template to use

Example call:
NaturalDTD from MyDTD.dtd to ./result like MyTemplate.xml

Details on sample calls follow later in this tutorial. First start with a simple example.

Simple example

NaturalDTD translates a DTD into a readable document. For this you need two basic components for a translation: A DTD that's information is used as the document data, a XML file that determines how this data will be layouted in the final document.

Let's start with the creation of a sample DTD:

<!ENTITY nbsp "&amp;nbsp;" >
<!ELEMENT fruitbox (apple,orange+)>
<!ATTLIST fruitbox label CDATA #IMPLIED>
<!ELEMENT apple EMPTY>
<!ELEMENT orange EMPTY>

We'll save this file named mysource.dtd to a subfolder called "tutorial" inside the root folder of the NaturalDTD parser.

This tells only DTD validators what the structure of a XML document has to look like, but it doesn't tell a human much about the purpose of each element.

Let's change this by adding comments into the DTD:

<!ENTITY nbsp "&amp;nbsp;" >
<!--
This is the nbsp entity that's equal to the HTML &amp;nbsp;!
-->
<!ELEMENT fruitbox (apple,orange+)>
<!--
A fruitbox is box of fruits. ;-) It may contain <b>one</b> apple and as many oranges as you want!
-->
<!ATTLIST fruitbox label CDATA #IMPLIED>
<!--
The fruitbox may have a label where you can write something down.
-->
<!ELEMENT apple EMPTY>
<!-- There's a huge variety of apple grades.-->
<!ELEMENT orange EMPTY>
<!-- What adelicious fruit! -->

Note that there's html allowed inside the comments! (<b> and &nbps;)

To translate this into a HTML document, we need a XML file that contains the processing script for the translation. This script will tell the parser how each element should be handled and what files are created.

Create a new file called mytemplate.xml in the tutorial subfolder where the dtd already lies. Fill the file with the following content:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE news SYSTEM "../NaturalDTD.dtd">
<naturalDTDTemplate version="1.0.3">

<!--// Entry point and "main" command queue. -->
<index>
 <write file="tutorial.html">
  Test!
 </write>
</index>

</naturalDTDTemplate>

This is the basic scheme for a NaturalDTD template. Take care of the Doctype DTD file path that is relative to the current directory. When you move the document to antoher folder you may need to update this. This could be a popular error source.

Inside the root element naturalDTDTemplate you find an element called index. This element is required in each template and is where the parser starts working.

The element write with property file tell the parser that the following content should be written inside the file "tutorial.html". This element in turn contains only a text string "Test!".

So this template just writes "Test!" into the file tutorial.html.

You can try this now yourself by calling the parser with the following line (from a command window opened in the parent directory of your tutorial folder):

naturaldtd from tutorial/mysource.dtd to tutorial/html like tutorial/mytemplate.xml

After successfull execution you can open the file tutorial/html/tutorial.html in the web browser.

Up to now no information from the DTD have been processed. Change this by editing the mytemplate.xml file:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE news SYSTEM "../NaturalDTD.dtd">
<naturalDTDTemplate version="1.0.3">

<!--// Entry point and "main" command queue. -->
<index>
 <write file="tutorial.html">
   <forEachElement>
   This is element <elementName/>! &lt;br&gt;
   </forEachElement>
 </write>
</index>

</naturalDTDTemplate>

Save the file and execute NaturalDTD again.Then view the result html file again. It should contain the Text:

This is element apple!
This is element orange!
This is element fruitbox!

The parser read the XML template, started with execution of index element, set tutorial.html as output target and printed for each element in the DTD the text "This is element" followed by the name of the corresponding element.

Note that for the HTML element <br> the special characters < and > had to be replaced by their entites < and >. This is needed because the parser would otherwise think that <br> is a XML element and try to interpret it. (Which would cause an error here.)

You have now learned the basics of Natural DTD. For further information see the Element Reference and the default Natural DTD XML template, which contains most possibile features.