$Id: README,v 1.1.1.1 1998/01/17 23:47:37 ken Exp $

SGML::SPGroveBuilder

                   A Perl 5 module for loading SGML,
                   XML, and HTML document instances
                       into SGML::Grove objects
                   using James Clark's SGML Parser.

                             Ken MacLeod
                         ken@bitsko.slc.ut.us

OVERVIEW

The SGML::SPGrove module links with James Clark's SGML Parser (SP) to load SGML, XML, and HTML document instances into SGML::Grove objects.

SGML::SPGroveBuilder takes a system identifier and passes it to SP to parse, as each element is parsed from the document SPGrove builds SGML::Grove objects to match. When done parsing, SPGrove returns the SGML::Grove object that contains the root element of the parsed document and an array (hopefully empty :-) of parser errors.

See the man/pod for SGML::SPGroveBuilder for details on calling SGML::SPGroveBuilder. See the file Changes for user-visible changes. See the Perl module SGML::Grove for details on using the grove built by SGML::SPGroveBuilder.

Newer versions of this module can be found at <ftp://ftp.uu.net/vendor/bitsko/gdo/>. SGML::SPGroveBuilder shares a mailing list with Quilt. To subscribe to the Quilt mailing list, send a message with the word `subscribe' in the Subject: field to <quilt-request@bitsko.slc.ut.us>.

Copyright (C) 1997 Ken MacLeod
SGML::SPGroveBuilder is distributed under the same terms as SP. See the file COPYING for distribution terms.

DIFFERENCES FROM SGML::SPGrove

SGML::SPGrove was split into SGML::SPGroveBuilder (the module that compiles and links with SP to build groves) and SGML::Grove (the module that implements the grove objects). The module name was changed from SGML::SPGrove to SGML::SPGroveBuilder.

INSTALLATION

SGML::SPGroveBuilder requires Perl 5 and James Clark's SP (from the Jade distribution). SP requires a C++ compiler. Although not strictly a requirement, you will probably want to also install SGML::Grove.

<http://www.perl.com/>
<http://www.jclark.com/>
<http://www.perl.com/CPAN/modules/by-module/SGML/> or <ftp://ftp.uu.net/vendor/bitsko/gdo/>

WARNING: Remove SGML::SPGrove before installing SGML::SPGroveBuilder and SGML::Grove.

1. SPGrove needs SP's `libsp.a' and include files. SP's `make install' does not install these. Create a workarea for compiling SP, compile it and keep the workarea until SPGrove is done.

   Edit SPGrove's Makefile.PL to point `LIBS' to SP's `lib' directory and `INC' to SP's three include directories. I've left my templates in to point the way.

2. standard Perl module after that,

            perl Makefile.PL
            make
            make test
            make install

        Just so you know, SPGrove's copy of SP's library is included
        in the install, that's over a megabyte and a half.

        FYI, a statically linked perl executable (`make perl') appears
        to run significantly faster, in one test, 17 seconds instead
        of 25 seconds.