README for DTDParse version V2.0beta6

DTDParse is a tool for processing SGML and XML DTDs. The primary
motivation for writing DTDParse was to provide a framework for
building documentation for DTDs, but other applications are easy
to imagine.

Using DTDParse is a two-step process. First the DTD is parsed
with 'dtdparse'. This produces an XML version of the DTD.
Subsequent processing is performed against this XML version.

 ******************************************************************
 * THIS SOFTWARE IS IN BETA. BUGS ARE NOT UNLIKELY. PLEASE REPORT *
 * THEM, BUT DON'T BE TOO SURPRISED WHEN YOU FIND THEM.           *
 ******************************************************************

Manifest
--------
README           - This document
VERSION          - The version number of this release
dtdformat        - Format a parsed DTD into documentation
dtdparse         - Parse an SGML/XML DTD into XML
dtd.dtd          - The XML DTD for the XML instances procued by dtdparse
modules/         - Formatting modules
test/            - Test DTDs
tools/           - Tools built with DTDParse
Catalog.pm       - Catalog parsing module
ContentModel.pm  - Content model handling module
DTD.pm           - DTD handling module
Tokenizer.pm     - Tokenizing module

System Requirements
-------------------

DTDParse version V2.0beta6 requires Perl5 and the Text::DelimMatch
module available from CPAN (www.cpan.org).

Changes
-------

See the ChangeLog in each directory for additional information
about the specific changes.

See WhatsNew for changes since the last release.

Installation
------------

At this point, I haven't arranged a proper Makefile.PL for DTDParse.
Simply unpack the distribution somewhere and run the tools with Perl.
Each of the programs adjusts its @INC path to make sure it can find
the modules it needs.

Documentation
-------------

In the fullness of time, each of the applications will include
appropriate POD documentation. At present, it's pretty sparse.

Getting Started
---------------

Go to the 'test' directory, run

  perl ../dtdparse --title "Test DTD" --output test.xml test.dtd

Peek in test.xml and you'll see the XML version of the DTD. Run

  perl ../dtdformat --html test.xml

Point your favorite web browser at test/index.html and you'll see the
default HTML documentation for the DTD. 

Delete the test directory, then run 

  perl ../dtdformat --refentry test.xml

Look in test/* and you'll find DocBook RefEntry pages of
documentation for the DTD.

You can provide your own library (defining a few perl functions)
to provide additional information for the documentation (such as
reasonable descriptions).

Copyright
---------

Copyright (C) 1999, 2000, 2001 Norman Walsh

Ironically, assertion of copyright is done to make it _easier_
to distribute this application.  (At least one organization,
Software in the Public Interest, requires an explicit copyright
statement in order to redistribute the software.)

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the ``Software''), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

Except as contained in this notice, the names of individuals
credited with contribution to this software shall not be used in
advertising or otherwise to promote the sale, use or other
dealings in this Software without prior written authorization
from the individuals in question.

Any application derived from this Software that is publically
distributed will be identified with a different name and the
version strings in any derived Software will be changed so that
no possibility of confusion between the derived package and this
Software will exist.

Warranty
--------

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT.  IN NO EVENT SHALL NORMAN WALSH OR ANY OTHER
CONTRIBUTOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

Contacting the Author
---------------------

This application is maintained by Norman Walsh, <ndw@nwalsh.com>.

The best way to reach norm is by email.  You will find additional
contact information at http://nwalsh.com/people/ndw/
