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.html file.
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.
- -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).
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. dtd2html
ignores general entities since they do not
define document structure.
- -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.
- -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.
- -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). This option is only valid if -tree is
specified.
Normally, dtd2html
will compute what are the top-most elements of the
DTD. This option overrides that computation for the sake of of printing
the content hierarchy trees. This option has no affect on the top-most
element list presented "TOP-ELEM.html" (or the file specified by
-topname).
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) files,
unless stated otherwise.
This page is the root of the HTML document. It contains the links to the other main
pages as described above. It also contains a brief paragraph mentioning that this
document was created by dtd2html
.
This file may (should) be editted to add further description of the DTD, and/or
contain links to other documents about the DTD.
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.
This page contains a list of all elements defined in the DTD.
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.html is the file describing the content of element. The element page is divided
into the following sections:
- element description (optional, see Element Description File).
- Links to subelements broken into three parts:
- Base content
- Inclusions (if defined)
- Exclusions (if defined)
- Tag minimization (if defined).
- Links to element's attribute (element.attr) and SGML decleration
(element.cont) pages.
- Links to all possible parent elements.
- Links to main pages as described above.
element.attr.html is the file describing the attributes of element. The element.attr
page is divided into the following sections:
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:
- Base content decleration.
- Inclusion content decleration (if defined).
- Exclusion content decleration (if defined).
- Link back to element page.
When dtd2html
is invoked, a file containing descriptions of the various elements
defined in the DTD may be specified (-descfile). These descriptions will appear in
the element.html and element.attr.html files. The syntax of the description file is as
follows:
<?DTD2HTML element1>
Description of element1 here.
<P>
<?DTD2HTML element2>
Description of element2 here.
<P>
...
The line <?DTD2HTML
element>
signifies the beginning of the element
description text. All text up to the next <?DTD2HTML
element> line or end-of-file
is used as the element description.
If element in the description file is suffixed by a "*", then the following description
text will put in the element's attribute page. Otherwise, the description text appears
in the element page.
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
. An <HR> (horizontal rule) tag is put
after the description text by dtd2html
.
To get started with a description file for a DTD, one can use the -elemlist option to
dtd2html
to generate a file with all elements defined in the DTD with empty
descriptions.
See Also
- dtdtree
- Generate content hierarchy trees of SGML elements.
- dtd.pl
- A Perl library to parse SGML DTDs.
Earl Hood, ehood@convex.com