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. --------------------------------------------------------------------------- CONTENTS of distribution: 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 --------------------------------------------------------------------------- INSTALLATION To install the perlSGML software, type the following at your shell prompt: perl install.me Notes on Installation Program o You must be in the same directory as the install.me program. o 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. o The '#!' line in the installed programs are set to point to the Perl executable specified in the installation process. o 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: o Copy library (*.pl) files in the "lib" directory to the library location you desire. o 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. --------------------------------------------------------------------------- RELEASE NOTES 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 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. --------------------------------------------------------------------------- KNOWN BUGS o 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, 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). --------------------------------------------------------------------------- BUGS/COMMENTS/SUGGESTIONS? 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: o Version of Perl (can be retrievied by "perl -v"). o Version of the program/library/module in question (See VERSIONS for a software version listing). o The exact command-line used to invoke the program (if applicable). o Error/diagnostic messages from the program. o 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. --------------------------------------------------------------------------- 97/09/18 14:52:07 Earl Hood, ehood@medusa.acs.uci.edu