README for perlSGML

97/09/18 14:52:07

Copyright (C) 1994-1997 Earl Hood, ehood@medusa.acs.uci.edu

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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

CHANGES/        Directory containing revision history of software.
COPYING         GNU General Public License.
MANIFEST        File listing used by install.me
README.1ST      The file you are reading.
VERSIONS        Version list of programs, libraries, and modules.
doc/            Documentation.
dtd2html       Create HTML files to navigate a DTD.
dtddiff        List changes in a DTD.
dtdtree        Output content hierarchies of SGML elements.
dtdview        Interactively query a DTD.
ebt/            Programs specific to EBT's DynaText(tm) product. 
ents/           SGML entity files.
examples/       Directory containing example files/output of programs.
install.me     Installation program.
lib/            Perl libraries and modules
old/            Old versions of programs
sgm/            Sample SGML files (mostly DTDs)
stripsgml      Strip tags from an SGML document instance.

*Denotes programs

To install the perlSGML software, type the following at your shell prompt:

perl install.me

Notes on Installation Program

• You must be in the same directory as the install.me program.
• The program requires Perl 5. If you are running Perl 4, you will have to install the software manually. Trying to run install.me with Perl 4 will generate compilation errors. See below for manual installation instructions.
• The '#!' line in the installed programs are set to point to the Perl executable specified in the installation process.
• Programs are updated to include the path location of the installed library files. Hence, you can install the library files in any location, and the program will still work.

Manual Installation

Manual installation should only be required if you are running a Perl 4 interpreter. Some parts of perlSGML are unusable using Perl 4; see the RELEASE NOTES below for the components of perlSGML that are Perl 4 compatible.

For the Perl 4 compatible components, do the following:

• Copy library (*.pl) files in the "lib" directory to the library location you desire.
• Copy the program files to the location you want them installed. After copying, you must edit the each file as follows:
  • Edit the "#!/..." line (the first line of each file) to be the complete pathname of your perl interpreter. Note, this step is unnecessary for Windows/MSDOS users.
  • Add a new line right after the "#!/..." line to contain the following:

unshift(@INC, "/path/to/lib/files");

                where "/path/to/lib/files/" is the path to where
                copied the library files to.  Note, for Windows/MSDOS
                user, you will have to use "\\" (w/o the quotes)
                as the directory separator if using double quotes
                to delimit the path.  For example:

                    unshift(@INC, "C:\\path\\to\\lib\\files");

                Note, if the location you copied the libraries are
                already part of Perl's standard library search path,
                you do not need to add the unshift() statement.

Much of the perlSGML software is still Perl 4 compatible. The following should run under Perl 4: dtd2html, dtddiff, dtdtree, dtdview, dtd.pl, sgml.pl. Perl 4 programs that have been replaced will be located in the "old" directory of distribution. As noted under INSTALLATION, if you you are using Perl 4, you will have to install the software manually since the "install.me" program requires Perl 5 to run.

Documentation is located in the directory doc/. The documentation is in HTML. The documentation is separated in multiple files. Loading "perlSGML.html" into a WWW browser will get you started.

• dtd.pl and SGML::DTD do not properly handle non-external/internal parameter entity references outside of markup declarations. Only external parameter entity references ocurring outside of markup declarations are handled properly.

            Note    The term "internal" refers to a parameter entity
                    whose content is directly defined in the parameter
                    entity declaration and not by an external
                    indentifier.  For example,

                    <!ENTITY % foo "(some|content)">

        This bug will only be a problem if you have DTDs that have
        internal parameter entities that contain complete markup
        declarations which are referenced.  These cases seem to be
        the exception instead of the norm (the bug, or limitation,
        went unnoticed for over 3 years).

If you have any bugs/comments/suggestions, feel free to drop me an e-mail message at ehood@medusa.acs.uci.edu.

If it is a bug you are reporting, please include the following in your message:

• Version of Perl (can be retrievied by "perl -v").
• Version of the program/library/module in question (See VERSIONS for a software version listing).
• The exact command-line used to invoke the program (if applicable).
• Error/diagnostic messages from the program.
• Any other information that might prove useful.

Before sending e-mail, make sure the documentation does not already have an answer to your question/problem.