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
To get an overview over all possible command line argurments of Natural DTD, type naturalDTD help.
Most important parameters:
Details on sample calls follow later in this tutorial. First start with a 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 "&nbsp;" >
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 "&nbsp;"
Note that there's html allowed inside the comments!
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"
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
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
Up to now no information from the DTD have been processed. Change this by editing the mytemplate.xml file:
Save the file and execute NaturalDTD again.Then view the result html file again. It should contain the Text:
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
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.