dtd2html

dtd2html is a Perl program that generates an HTML document (composed of several files) to allow hypertext navigation through an SGML DTD.


Description

dtd2html generates various HTML files for hypertext navigation of a SGML DTD. The files generated are as follows:

DTD-HOME.html
This file is the home page of the HTML document. This file contains to the basic links to start navigating through the DTD. The name of this file can be changed with the -homename option.
TOP-ELEM.html
This file lists the top-most elements of the DTD, and contains the links to element pages describing each top-most element. The name of this file can be changed with the -topname option.
ALL-ELEM.html
This file contains a list of all elements defined in the DTD. This page allows quick access to any individual element description page. The name of this file can be changed with the -allname option.
DTD-TREE.html
(Optional) This file contains the content heierachy tree(s) of the top-most element(s) in the DTD. This file is only generated if the -tree option is specified during program invocation. The name of this file can be changed with the -treename option.
element.html
For each element defined in the DTD, an element description file is generated with a filename of the element name suffixed by ".html".
element.attr.html
For each element defined in the DTD, a file is generated describing the attributes defined for the element.
element.cont.html
For each element defined in the DTD, a file is generated listing the content model decleration of the element as declared in the DTD.
       
Once all the files are generated, one needs only to create a link in the Web server being used to the DTD-HOME page.

More information on the content of each file is in the HTML File Descriptions section.


Usage

dtd2html is invoked from a Unix shell, with the following syntax:

% dtd2html [options] filename

filename is the SGML DTD to be parsed for generating the HTML files. The following is the list of options available:

-allname filename
Set the filename for file listing all elements in the DTD to filename. The default name is "ALL-ELEM.html".
-descfile filename
Use filename as the source for element descriptions in the DTD. If this argument is not specified, no description file is used. See Element Description File for more information.
-docurl URL
Use URL for location of documentation on dtd2html. The default URL is "dtd2html.doc.html".
-dtdname string
Set the name of the DTD to string. If not specified, dtd2html determines the name of the DTD by its filename with the extension stripped off. If reading from standard input, then this argument should be specified. Otherwise, "Unknown" is used.

The string " DTD" will be appended to the name of the DTD.

-elemlist
Generate a blank element description file (see Element Description File) to STDOUT. No HTML files are generated and all other options are ignored when this option is specified.
-help
Print out a terse description of all options available. No HTML files are generated and all other options are ignored when this option is specified.
-homename filename
Set the filename for the HTML home page for the DTD to filename. The default name is "DTD-HOME.html".
-level #
Set the prune level of the content hierachy tree to #. This option is only valid if -tree is specified.
-mapfile filename
Set the entity to map file to filename. The default is "map.txt". See DTDread_mapfile of package dtd for more information.

The entity map file is only necessary if element/attribute markup are contained in multiply files, and the files are referenced by external parameter entities.

-outdir path
Set destination of generated HTML files to path. Defaults to the current working directory.
-topname filename
Set the filename for file listing the top-most elements in the DTD to filename. The default name is "TOP-ELEM.html".
-tree
Generate the content hierarchy of the top-most elements defined in the DTD.
-treelink
Create anchor in HTML pages to the tree page, even if -tree is not specified.
-treename filename
Set the filename for file containing the content hierarchy tree(s) of the DTD to filename. The default name is "DTD-TREE.html". This option is only valid if -tree is specified.
-treeonly
Create only the tree page. This option implies -tree.
-treetop string
Set the top-most elements to string. String is a comma separated list of elements that dtd2html should treat as the top-most elements when printing the content hierarchy tree(s), and/or which elements get listed in the TOP-ELEM page.

Normally, dtd2html will compute what are the top-most elements of the DTD. This option overrides that computation.

-verbose
Print status messages to STDERR of what dtd2html is doing. This option generates much output, and is used mainly for debugging purposes.

HTML File Descriptions

All HTML files/pages generated contain hypertext links at the end of the page to the DTD-HOME, TOP-ELEM, ALL-ELEM, and DTD-TREE (if specified) pages, unless stated otherwise.

       

DTD-HOME

This page is the root of the HTML document. It contains the links to the other main pages as described above.

One can add documentation to the home page via the Element Description File or by manually editting the file.

       

TOP-ELEM

This page contains the list of all top-most elements defined in the DTD. A top-most element is defined as: An element which cannot be contained by another element or can be only contained by itself.

       

ALL-ELEM

This page contains a list of all elements defined in the DTD.

       

DTD-TREE

This page contains the content hierarchy tree(s) of the top-most elements of the DTD. See DTDprint_tree of package dtd for a detailed description about the content hierarchy tree(s).

       

element

element.html is the file describing the content of element. The element page is divided into the following sections:

       

element.attr

element.attr.html is the file describing the attributes of element. The element.attr page is divided into the following sections:

This page is not created if no attributes are defined for element.

       

element.cont

element.cont.html is the file giving the element content model decleration as it appears in the DTD. The element.cont page is divided into the following sections:

This page is not created if element is defined with empty content.

       

Element Description File

dtd2html supports the ability to add documentation to the HTML files generated from a DTD through the -descfile option. Documentation can be added to the element pages and/or the attribute pages.

The basic syntax of the description file is as follows:

         <?DTD2HTML identifier>
Description of identifier here.
<P>
<?DTD2HTML identifier>
Description of identifier here.
<P>
...
       
The line <?DTD2HTML identifier> signifies the beginning of the description text. All text up to the next <?DTD2HTML identifier> line or end-of-file is used as the identifier description.

The identifier can be one of the following formats:

element
An element name in the DTD. The following description text will go at the top of the element's page.
element*
An element in the DTD followed by a `*'. The following description text will go at the top of the element's attribute page.
element*attribute
An element in the DTD followed by a `*' which is followed by an attribute name of the element. The following description text will go below the attribute heading of the element's attribute page.
*attribute
A `*' followed by an attribute name. The following description text will go to any attribute named attribute, unless a specific description is given to the attribute via an element*attribute. This identifier allows to add descriptions to commonly shared attributes in one locale.
identifier,identifier,...
A sequence of identifiers separated by commas, `,'. This allows a description to be shared among muliple identifiers (which are normally element names). NOTE: there should be NO whitespace between the identifiers and the commas.
       
If the special element, -HOME-, is specified in the description file, then its description text will be put on the DTD-HOME page.

SGML comments are also supported in the description file. Comments are skipped by dtd2html. The syntax for a comment is the following:

         <!-- This is a comment -->
Warning:
dtd2html can only handle a comment that spans a single line (to make the parsing simple). Therefore, the following will cause dtd2html to add the comment text beyond the first line of the comment to an element description:
         <!-- This is a comment
that spans more than one line.
-->
If you want to put line breaks in the description file without them being applied to an element description, then use the SGML short comment: <!>.

       
The description text can be any valid HTML markup. It is recommended to end each description with the <P> tag so the description is separated from any other HTML markup generated by dtd2html.

Example:

<!-- The Anchor Element -->
<!>
<?DTD2HTML a >
An anchor is a piece of text which marks the beginning and/or the
end of a hypertext link.
Click <a href="http://info.cern.ch/hypertext/WWW/MarkUp/Elements/A.html">
here</a> for more information on an anchor.
<P>
<?DTD2HTML a* >
<P>
<?DTD2HTML a*HREF >
OPTIONAL. If the HREF attribute is present, the anchor
is sensitive text: the start of a link. If the reader selects this
text, (s)he should be presented with another document
whose network address is defined by the value of the
HREF attribute.
<P>
<?DTD2HTML a*METHODS >
OPTIONAL. The value of this field is a string which if
present must be a comma separated list of HTTP
METHODS supported by the object for public use.
<P>
       
Miscellaneous Notes:


See Also

dtdtree
Generate content hierarchy trees of SGML elements.
dtd.pl
A Perl library to parse SGML DTDs.

Earl Hood, ehood@convex.com
dtd2html 1.2.0