packages icon
README

This is the distribution of Perl program(s) and library(s) dealing with
SGML DTDs.

---------------------------------------------------------------------------
    Copyright (C) 1994  Earl Hood, ehood@convex.com

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
---------------------------------------------------------------------------

CONTENTS of distribution:

CHANGES.dtd.pl	  Revision history of dtd.pl
CHANGES.dtd2html  Revision history of dtd2html
COPYING		  GNU General Public License
README		  The file you are reading
doc/		  Documentation
dtd/		  Location of Perl libraries
dtd.pl		  Symbolic link to dtd/dtd.pl
dtd2html*	  Perl program to create HTML files to navigate a SGML DTD
dtdtree*	  Perl program to output content hierarchies of SGML elements
ents/		  SGML entity files
examples/	  Directory containing example output of dtd2html
install_dtd*	  Installation (csh) script
map.txt		  Sample entity map file
newgetopt.pl	  Perl library for parsing command-line options
sgm/		  SGML files (mostly DTDs)


---------------------------------------------------------------------------
INSTALLATION

For installation, do the following:

	1. Read and edit the csh script, install_dtd.
	2. Run install_dtd.

You might have to run the script as root.

    Note:
	The Perl programs might need the first line editted to point
	to the location of the Perl interpreter at your site.  By 
	default, the programs assume /usr/local/bin/perl.

See NOTES below for further information.
    
---------------------------------------------------------------------------
DOCUMENTATION

Documentation is located in the directory doc/.  The documentation is in
FrameMaker 4.0, HTML, and plain text.  Reading the files in doc/ should
get you started on how to the programs.  Here's the list of files in the
doc directory.

    dtd.pl files:
	dtd.pl.doc
	dtd.pl.doc.html
	dtd.pl.doc.txt
	dtd_data_routines.doc
	dtd_data_routines.doc.html
	dtd_data_routines.doc.txt
	dtd_parse_routines.doc
	dtd_parse_routines.doc.html
	dtd_parse_routines.doc.txt
	dtd_util_routines.doc
	dtd_util_routines.doc.html
	dtd_util_routines.doc.txt

    dtd2html files:
	dtd2html.doc
	dtd2html.doc.html
	dtd2html.doc.txt

    dtdtree files:
	dtdtree.doc
	dtdtree.doc.html
	dtdtree.doc.txt

Files with just the ".doc" extension are in Frame 4.0.  The ".doc.html"
files are the Frame files converted to HTML.  The ".doc.txt" files are
the HTML files converted to plain text (via "lynx -dump").

I put considerable time in documenting the tools, so pleeeease read
them :-)

If you have a Web client like Mosaic, you can load the HTML files into
the viewer for reading.  The HTML files contain cross-references (that
hopefully help in describing things) to each other.

---------------------------------------------------------------------------
NOTES

 o  The Perl programs make use of the file "dtd.pl".  The installation
    script trys to install this file in a standard Perl library
    location in a sub-directory called "dtd".  However, if you
    install it in a location that Perl does not look for when
    requiring files, then make sure you set the PERLLIB environment
    variable.

 o  newgetopt.pl (written by Johan Vromans) is provided in the distribution
    in case you do not have the library at your site.  This library is
    needed inorder for the programs to parse the command-line.  This
    library is normally included in the Perl distribution.

    If you do not have this library installed, then copy it into the
    location of Perl's standard libraries.

 o  The examples/ directory contains the HTML conversion of the
    HTML DTD.  The file "sgm/html.desc" is the element description file
    used for the HTML DTD.  See documentation for more information on
    element description files.

 o  dtd.pl is the guts of everything.  I tried to write so it can be
    used in any Perl program dealing with SGML DTDs.  If you come up
    with a nifty program that uses dtd.pl, please drop me a message.
    I'd like to see if others are making any use of it.

---------------------------------------------------------------------------
BUGS/COMMENTS/SUGGESTIONS?

    If you have any bugs/comments/suggestions, feel free to drop me
    an e-mail message at ehood@convex.com.

    If you have questions on what the tools can, or cannot do, please
    read the documnetation first.  If the docs do not answer your
    question(s), feel free to e-mail me.

---------------------------------------------------------------------------
Earl Hood, ehood@convex.com