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.

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

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

### 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:

- 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

element.attr.html is the file describing the attributes of element. The element.attr page is divided into the following sections:

- attribute(s) description (optional, see Element Description File).
- List of attributes with possible values and default value.
- 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:

- Base content decleration.
- Inclusion content decleration (if defined).
- Exclusion content decleration (if defined).
- Link back to element page.

## Element Description File

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.