dtd2html 1.3.0


dtd2html

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

Note
Later versions of dtd2html may come out without a public announcement (especially for bux fix releases). For the latest release and information on dtd2html, look at my home page at the University of California: Irvine.

Contents


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. User text may be added to this page via the Element Description File.
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". User text may be added to this page via the Element Description File.
element.attr.html
For each element defined in the DTD, a file is generated describing the attributes defined for the element. User text may be added to this page via the Element Description File.
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.

Note
If you have a Web client that can load local files, than linking the DTD-HOME page to the Web server is unnecessary.
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. If the -qref option is specified, then the string " DTD Quick Reference" is appended to represent the title of the quick reference document.

-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".
-keepold
This option is only valid if -updateel is specified. This option tells dtd2html to preserve any old descriptions when updating an element description file.
-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.

-noreport
This option is only valid if -updateel is specified. This options tells dtd2html to not output a report when updating an element description file.
-outdir path
Set destination of generated HTML files to path. Defaults to the current working directory.
-qref
Output a quick reference document of the DTD. The document is outputted to standard output (STDOUT). When this option is specified, only the quick reference document is generated. Therefore, the tree page and the -outdir options are ignored. See Quick Reference Mode for more information on the -qref option. Related options: -qrefdl, -qrefhtag.

-qrefdl
Output a quick reference document of the DTD using the <DL>, definition list, HTML tag. When this option is specified, only the quick reference document is generated. Therefore, the tree page and the -outdir options are ignored. See Quick Reference Mode for more information. This option overrides the behavior of the -qref option.

-qrefhtag htag
Use htag as the header tag for the element names when the -qref option is specified. Defaults to '<H2>'.
-reportonly
This option is only valid if -updateel is specified. This options tells dtd2html to generate only a report when the -updateel option is specified.
-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. Related options: -treelink, -treename, -treeonly, -treetop.

-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.

-updateel file
Perform an update of the element description file specified by file. This option allows one to update an element description to contain any new elements/attributes that have been added to the DTD without affecting element descriptions already defined. See Updating Element Description File for more information. Related options: -keepold, -noreport, -reportonly.

-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 an alphabetic 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).

HTML enhancements to DTDprint_tree:

       

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:


Quick Reference Mode

dtd2html supports the ability to generate a quick reference document of a DTD with the -qref option. The document generated is sent to standard output (STDOUT). Therefore, one should redirect STDOUT to a file:

Example:
% dtd2html -qref html.dtd > html-qref.html
No other output/files are generated while in quick reference mode.

The format of the quick reference document is as follows:

Defintion List, <DL>, Format

An alternative format for the quick reference document may be generated with the -qrefdl command-line option. The format of the document shares the same properties as those of the -qref option, with the following exceptions:

Each element is still wrapped in a <A NAME> statement to allow cross-referencing.

Notes

Tips


Updating Element Description File

As a DTD changes, one can automatically update the element description file for the DTD to reflect the changes via the -updateel command line option. The new updated element description file is sent to standard output (STDOUT). Therefore, one should redirect STDOUT to a file:

Example:
% dtd2html -updateel html.desc html.dtd > html-new.desc
When updating an element description file, a report is prependend to the new element description file. The report is contained in SGML comment declaration statements. Here's an example of what the report looks like:

<!-- Element Description File Update                                      -->
<!-- Source File:  sgm/html.desc                                          -->
<!-- Source DTD:  sgm/html.2.0/html.dtd                                   -->
<!-- Deleting Old?  Yes                                                   -->
<!-- Date:  Mon Jun 27 00:25:41 EDT 1994                                  -->
<!-- New identifiers:                                                     -->
<!--    br, dl*, dl*compact, form, form*, form*action, form*enctype,      -->
<!--    form*method, img*ismap, input, input*, input*align,               -->
<!--    input*checked, input*maxlength, input*name, input*size,           -->
<!--    input*src, input*type, input*value, option, option*,              -->
<!--    option*selected, option*value, select, select*,                   -->
<!--    select*multiple, select*name, select*size, strike, textarea,      -->
<!--    textarea*, textarea*cols, textarea*name, textarea*rows            -->
<!-- Old identifiers:                                                     -->
<!--    dir*, dir*compact, key, link*name, menu*, menu*compact, ol*,      -->
<!--    ol*compact, u, ul*, ul*compact                                    -->
<!--                                                                      -->

Notes


See Also

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

Glossary

DTD
Document Type Definition. A DTD defines the structure of an SGML document.
HTML
HyperText Markup Language. HTML is mainly used to represents documents in the World Wide Web.
Perl
Practical Extraction and Report Language. Perl is developed by Larry Wall and is designed to manipulate text, files, and processes.
SGML
Standard Generalized Markup Language. SGML is defined by ISO 8879. SGML's purpose is for document representation.

References

HyperText Markup Language (HTML)
http://info.cern.ch/hypertext/WWW/MarkUp/MarkUp.html.
Programming perl
Larry Wall and Randal L. Schwartz. O'Reilly & Associates, Inc. 1990.
SGML: An Author's Guide to the Standard Generalized Markup Language
Martin Bryan. Addison-Wesley. 1988.
UF/NA Perl Archive
http://www.cis.ufl.edu/perl/.
World Wide Web Initiative
http://info.cern.ch/hypertext/WWW/TheProject.html.

Earl Hood, ehood@convex.com
dtd2html 1.3.0