From ehood@imagine.convex.com Sat Jul 9 00:26:06 1994
Subject: ANNOUNCE: dtd2html 1.3.0
Date: Fri, 08 Jul 94 17:21:58 CDT
From: Earl Hood
Summary:
dtd2html is a Perl program that generates an HTML document
that documents an SGML DTD and to allow hypertext navigation
of an SGML DTD.
Version 1.3.0 supports the ability to create a "quick reference"
of a DTD, and the ability to automatically update an element
description file as a DTD changes.
dtd2html 1.3.0 is available for use at the following URL:
ftp://ftp.uci.edu/pub/dtd2html/ as dtd2html.1.3.0.tar.gz
You can also access via my Web page here
My web page contains sample DTDs filtered with dtd2html and the
HTML page documenting the complete capabilities of dtd2html.
Following is the revision history for dtd2html:
==============================================================================
1.3.0 (July 08, 1994)
New Functionality/Enhancements:
o A "quick reference" output (-qref or -qrefdl).
o Support for updating the element description file when a DTD
changes (-updateel).
o In the spirit of SGML, only the first element description
encountered is used. However, an empty description, or a
description with only the tag, is ignored.
o Removed the word "Goto" in the links at the bottom of each
page. It was bad style.
o The footer on each page containing the name of the DTD links
to the home page.
o New command-line options:
-keepold -noreport -qref -qrefdl -qrefhtag -reportonly
-updateel
==============================================================================
1.2.1 (June 01, 1994)
New Functionality/Enhancements:
o Tree elements with "..." now link to the 'complete' entry
in the tree, and the 'complete' entry links to the element
page.
o "Goto Tree" link on an element page, goes to tree page
scrolled to the location of the 'complete' element entry.
==============================================================================
1.2.0 (May 31, 1994)
New Functionality/Enhancements:
o Support for shared attribute and element descriptions in the
element description file.
o Comment support in element description file.
o Formatting of content model declarations for better readablity.
o Attribute page is not created for an element if the element
has no attributes.
o Content declaration page is not created if the element is
defined with EMPTY content.
o Now hyperlinks exist for elements listed in the content
declaration page.
o Added the -verbose option. Now one can get the gory details
of what dtd2html is doing.
o A list of anchors of top-most elements are created at the
top of the tree page if more than one top-most element is
defined in the DTD. The anchors allow quick scrolling to
top of each tree.
Bug Fixes:
o NOTATION declared value keyword attributes are recognized.
==============================================================================
1.1.0 (May 18, 1994)
New Functionality/Enhancements:
o The following command-line options were added:
-docurl, -treelink, -treeonly
o Support for descriptions for specific attributes of an element.
o The -elemlist option will create empty entries for attributes.
o A special element, "-HOME-", is recognized in the element
description file. The HTML text for this element is placed
in the DTD-HOME page.
Bug Fixes:
o The #FIXED default value of an attribute is recognized.
==============================================================================
1.0.0 (May 12, 1994)
The original version (no version number was given out when this
was released).
----
Earl Hood | CONVEX Computer Corporation
ehood@convex.com | 3000 Waterview Parkway
Phone: (214) 497-4387 | P.O. Box 833851
FAX: (214) 497-4500 | Richardson, TX 75083-3851
From ehood@convex.com Mon Jun 13 10:40:18 1994
Article: 244 of comp.infosystems.announce
From: ehood@convex.com (Earl Hood)
Subject: dtd2html version 1.1.0 avaliable
Date: Thu, 9 Jun 94 20:58:01 GMT-1:00
Organization: Engineering, Convex Computer Corporation, Richardson, Tx USA
dtd2html: A Perl program that generates an HTML document to allow
hypertext navigation through an SGML DTD.
For those unfamiliar with dtd2html, see the attached documentation
describing it at the end of this message.
URLs for dtd2html 1.1.0 (available, or soon to be):
ftp://ftp.utdallas.edu/pub/dtd2html/
ftp://ftp.ifi.uio.no/pub/SGML/DTD2HTML/
ftp://ftp.uci.edu/pub/dtd2html/
You can also obtain more information about dtd2html/dtd.pl at the
following URLs:
http://www.oac.uci.edu/indiv/ehood/
http://www.utdallas.edu/dtd2html/home.html
For others who have archived the first version of dtd2html, feel free
to copy over the later version. The name of the file is
"dtd2html.1.1.0.tar.gz".
Following is the list of changes from the first release:
-----------------------------------------------------------------------------
List of changes to dtd.pl (SGML DTD parser library):
New Functionality/Enhancements:
o General entities are supported, however, external ones are
still ignored (needed for IBMIDDoc).
o General entities are expanded when found in the DTD.
I.e. General entities are not expanded when found in a parameter
entity definition, but are expanded when the parameter entity is
referenced (needed for IBMIDDoc).
Bug Fixes:
o The #FIXED default value of an attribute is recognized.
o <!ATTLIST #NOTATION is ignored properly.
o Putting parenthesis around an external parameter entity reference
could have cause element names to be stored with a parenthesis.
This has been fixed.
o Fixed bug in parsing string values.
o Semi-colons were missing in some Perl statements that
caused older Perl interpreters to complain.
o Recognizes a parameter enitity being used to define an element's
tag minimization.
-----------------------------------------------------------------------------
List of changes to dtd2html:
New Functionality/Enhancements:
o The following command-line options were added:
-docurl, -treelink, -treeonly
o Support for descriptions for specific attributes of an element.
o The -elemlist option will create empty entries for attributes.
o A special element, "-HOME-", is recognized in the element
description file. The HTML text for this element is placed
in the DTD-HOME page.
Bug Fixes:
o The #FIXED default value of an attribute is recognized.
-----------------------------------------------------------------------------
ASCII documentation for dtd2html:
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.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.
-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). 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). 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).
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) files, 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:
o element description (optional, see Element
Description File).
o Links to subelements broken into three parts:
o Base content
o Inclusions (if defined)
o Exclusions (if defined)
o Tag minimization (if defined).
o Links to element's attribute (element.attr) and
SGML decleration (element.cont) pages.
o Links to all possible parent elements.
o Links to main pages as described above.
element.attr
+++++++++++++
element.attr.html is the file describing the attributes of
element. The element.attr page is divided into the
following sections:
o attribute(s) description (optional, see Element
Description File).
o List of attributes with possible values and default
value.
o Link back to element page.
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:
o Base content decleration.
o Inclusion content decleration (if defined).
o Exclusion content decleration (if defined).
o Link back to element page.
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 page and/or the attribute page.
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.
If the special element, -HOME-, is specified in the
description file, then its description text will be put on the
DTD-HOME 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.
Example:
<?DTD2HTML a >
An anchor is a piece of text which marks the beginning and/or the
end of a hypertext link.
Click <a href="../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>
If duplicate descriptions exist, the latest one defined is
used.
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 and attributes 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
dtd2html 1.1.0
----
Earl Hood | CONVEX Computer Corporation
ehood@convex.com | 3000 Waterview Parkway
Phone: (214) 497-4387 | P.O. Box 833851
FAX: (214) 497-4500 | Richardson, TX 75083-3851