livedtd.pl - generate an html version of a DTD

# livedtd.pl

generate an html version of a DTD

- SYNOPSIS
- DESCRIPTION
- OPTIONS
- ACKNOWLEDGEMENTS

## SYNOPSIS

    livedtd.pl [options] dtdfile

Where options are:

      --catalog catalogs          [if catalog used by the DTD]
      --outdir outputdirectory    [default is ./livedtd]
      --label xxx                 [add xxx prefix on output filenames]
      --sgml                      [case insensitive element names]
      --title "displayed title"   [default is main DTD filename]
      --nousage                   [does not generate usage tables]
      --verbose                   [lists details to STDOUT]

## DESCRIPTION

This program scans through an XML or SGML Document Type Definition (DTD) to locate element and parameter entity definitions. Then it constructs an HTML version of the DTD with hot links from element references to element declarations, and from entity references to entity declarations. These links let you navigate through the DTD with ease. Just point your favorite frames-capable browser at index.html in the output directory to see the results.

This program was written for use by maintainers of highly parameterized DTDs such as Docbook or TEI. It allows you to quickly see how a parameter entity or element is defined, following it through many levels of indirection to its source. It also helps you find the active definition when more than one is supplied, as when a customization layer is used.

The program takes a single command line argument (after any options) that is the pathname to the main DTD file. Any additional arguments are ignored. DTD files referenced by the main DTD as SYSTEM entities are processed when they are encountered, unless they are in a marked section whose status is IGNORE. Catalogs are supported to locate system files, but http URLs are not supported.

The program handles marked sections properly. That is, marked sections whose status is IGNORE are output as plain text and do not have any live links. Those whose status is INCLUDE are made live by adding links. Parameter entities are also handled properly. That is, if there is more than one declaration for the same name, only the first one is active.

Livedtd parses a DTD for display purposes, but it does not validate it. In performing its function, it will flag many common validation errors. But lack of such errors does not necessarily mean the DTD is valid.

This program generates an HTML file for each DTD file used. The content is displayed within a <PRE> element to preserve the white space and line breaks of the original DTD file. The only difference from the original file is the HTML markup to make it live. In fact, removing the HTML markup leaves you with an identical copy of the original.

It outputs them into a single output directory, even if the originals are scattered all over the place. It also constructs lists of elements, entities, and filenames, and constructs an HTML framework file to display it all.

The program generates name usage tables as well. These are accessed by clicking on the ``+'' marker next to an element or entity name in the left-frame tables of contents. A usage listing shows where the name itself was seen in the DTD. It is not a complete list of element usage, however. To get that, you have to follow the various parameter entities that contain the element name.

The program is not for authoring or editing a DTD. However, if you have a good HTML editor that preserves lines endings and whitespace, you can edit the HTML version with it. When you are done, you can scrub out the HTML markup using the program scrubdtd.pl included with the distribution. That program converts a LiveDTD file back to a "dead" DTD file without HTML markup. It is used on each file that makes up the DTD:

       scrubdtd.pl file.dtd.html > file.dtd

If your HTML editor doesn't mess with the text, you should have a working DTD file. Test it by doing a round trip: use livedtd.pl to generate the HTML version, make some editing changes with your HTML editor, save it, and then apply scrubdtd.pl to each generated HTML file. The only differences with the original DTD files should be the changes you made.

## OPTIONS

The --catalog option lets you specify a catalog path (such as that used in SGML_CATALOG_PATH) to be used to resolve PUBLIC identifiers in your DTD. It can include more than one path, separated by colons. Note that the OASIS/Catalog.pm module located below the location of the livedtd.pl program is needed to process a catalog file. Your environment variable SGML_CATALOG_PATH is not automatically used, because you may be processing in a mixed XML and SGML environment. If it is set, you can use: --catalog ``$SGML_CATALOG_PATH''

The --label option lets you add a prefix to each of the generated filenames. That allows you to output several different liveDTDs to the same directory without filename conflict as long as the labels are different.

The --outdir option lets you specify an output directory for the generated HTML files. If not specified, the program uses ./livedtd. That is, it creates a subdirectory livedtd below the current working directory. You can specify the current directory with `--outdir .` (dot is current directory).

The --sgml option alters how names are parsed. Without this option, the program defaults to XML name parsing, which is always case sensitive. With this option, livedtd treats element names as not being case sensitive. That is a feature of the reference concrete syntax for SGML DTDs. Entity names remain case sensitive, but entity names may include only characters from the class [-A-Za-z0-9.] and not underscore or colon as are permitted in XML. Note that the program does not automatically detect that a DTD is SGML. Also, if your SGML declaration deviates from the reference concrete syntax. you can adjust the variables `$SGMLEntname` and `$SGMLElemName` defined at the top of the program.

The --title option lets you specify a printed title to appear in the HTML display, such as ``DocBook XML 4.1''.

The --nousage option turns off the generation of tables showing where each element and entity name are used in declarations. The usage tables are useful for tracking down potential effects of any changes you want to make to a DTD, so it is on by default.

The --verbose option provides many details during the processing that can be useful for diagnosis of problems. It also provides tables of element and parameter entity definitions. It writes to standard output.

## ACKNOWLEDGEMENTS

Thanks for Norm Walsh for permission to use code fragments from his flatten program for catalog and DTD parsing.

© Copyright 2000 Robert Stayton