dtd2html
is a Perl 4 program that generates an HTML document that documents
an SGML DTD and to allow hypertext navigation of 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
". User
text may be added to this page via the Element Description File.
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.
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
"http://www.oac.uci.edu/indiv/ehood/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. If the -qref
option is specified, then the string " DTD Quick Reference" is appended to
represent the title of the quick reference document.
-elemlist
-help
-homename
filename
DTD-HOME.html
".
-keepold
dtd2html
to preserve any old descriptions when updating an element
description file.
-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.
-nodocurl
dtd2html
documentation in the DTD-HOME
page.
-noreport
dtd2html
to not output a report when updating an element description
file.
-outdir
path
-qref
-qref
option.
Related options: -qrefdl, -qrefhtag.
-qrefdl
<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
<H2>
'.
-reportonly
dtd2html
to generate only a report when the -updateel option is
specified.
-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.
-updateel
file
-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 enhancements to DTDprint_tree:
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.
+
+
'. The following description text
goes after each elements listed in ALL-ELEM and in element.cont pages.
*
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 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+ > <!-- Brief description for listings --> Anchor; source and/or destination of a link <?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 are empty or 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).
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:
% dtd2html -qref html.dtd > html-qref.html
The format of the quick reference document is as follows:
<H2>
tag (or the tag specified by the -qrefhtag
option) wrapped with the '<>
' characters.
<H2>
tag is wrapped with the <A NAME=
"element">
tag so one may cross-reference the element if desired. Example: <H2><A
NAME="body"><body></A></H2>
.
<DL>
, Format
<DL>
, definition list.
<DT>
section of <DL>
.
<DD>
section of the <DL>
.
<A NAME>
statement to allow cross-referencing.
<DL>
.
dtd2html
output
would be inappropriate for a quick reference.
-HOME-
element description identifier may be used to place text
before the list of elements. One could add a link to the DTD-HOME page
that is generated by dtd2html
when the -qref
option is not used.
% dtd2html -updateel html.desc html.dtd > html-new.desc
<!-- 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 --> <!-- -->