dtd2html
is a Perl program that generates an HTML document (composed of
several files) to allow hypertext navigation through an SGML DTD.
dtd2html
generates various HTML files for hypertext navigation of a SGML
DTD. The files generated are as follows:
html
html
html
html
html
.html
".
html
html
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.
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
ALL-ELEM.html
".
-descfile
filename
-docurl
URL
dtd2html
. The default URL is
"dtd2html.doc.html
".
-dtdname
string
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
-help
-homename
filename
DTD-HOME.html
".
-level
#
-mapfile
filename
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
-topname
filename
TOP-ELEM.html
".
-tree
-treelink
-treename
filename
DTD-TREE.html
". This option is only
valid if -tree is specified.
-treeonly
-treetop
string
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
dtd2html
is doing. This option
generates much output, and is used mainly for debugging purposes.
One can add documentation to the home page via the Element Description File or by manually editting the file.
html
is the file describing the content of element. The element page is
divided into the following sections:
attr.html
is the file describing the attributes of element. The element.attr
page is divided into the following sections:
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:
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:
*
*
'. The following description text
will go at the top of the element's attribute page.
*
attribute
*
' 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
*
' 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,
...
,
'. 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 -->
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 commentIf you want to put line breaks in the description file without them being applied to an element description, then use the SGML short comment:
that spans more than one line.
-->
<!>
.
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:
dtd2html
ignores element descriptions that contain only the <P> tag.
dtd2html
to generate a file with all elements and attributes
defined in the DTD with empty descriptions (i.e they only contain the <P>
tag).