$Id: README,v 1.3 1998/02/10 01:43:02 ken Exp $


                           Quilt for Perl

                  A Perl 5 module for transforming
                 and formatting SGML/XML documents.


                            Ken MacLeod
                        [email protected]

WARNING

   This is an early alpha!

   Though, while this may be an early alpha it's only because I had a
   brainstorm on how to handle the transformations -- I will be
   ``porting'' my existing work to this framework and should have a
   much more complete system in less time than one would normally
   expect.

   The areas undergoing a large amount of little changes are the
   details of formatting and features of the Doc Objects (DO).  The
   areas that are likely to change in big ways are the command line
   utility, file and entity handling, helper-functions for hiding
   most of the nitty-gritty of specs and transformation sequences,
   subclassing styles and browser support, formatting options, and
   further out, the language Specs are written in.

INTRODUCTION

   Quilt is a framework for loading SGML/XML documents or document
   fragments, manipulating them in interesting ways, and displaying
   or formatting them.

   Quilt can also be used from code to generate document-like items
   before formatting them -- tables for example.

   There are specs for reading DocBook, LinuxDoc, and TEI Lite
   documents, and formatters for plain Ascii and HTML (mostly 2.0).
   There's a quick and dirty frontend script for formatting
   documents.

   Quilt was formerly called Generalized Document Objects (GDO) and
   DTD Fragments.

   See the file Changes for user-visible changes.  See the `examples'
   directory for examples of using `Quilt'.

   Newer versions of this module can be found at
   <ftp://ftp.uu.net/vendor/bitsko/gdo/>.  You can join the Quilt
   mailing list by sending a message with the word `subscribe' in the
   Subject: field to <[email protected]>.

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

OVERVIEW

Formatting Documents

   Before formatting documents, make sure you have the catalogs for
   all DTDs, SPGrove's Simple Spec, and the ISO Entities in
   SGML_CATALOG_FILES, for example:

       export SGML_CATALOG_FILES=/usr/lib/sgml/docbook.2.2.1/CATALOG\
       :/usr/lib/sgml/linuxdoc-1.5/linuxdoc.cat\
       :/usr/lib/sgml/teilite-1.6/teilite.cat\
       :/usr/lib/sgml/iso-entities-8879.1986/iso-entities.cat\
       :/usr/lib/sgml/SGML-SPGrove-0.08/catalog

   A simple test to make sure everything is going to work is to run
   `nsgmls' on your document:

       nsgmls MYDOCUMENT

   Here is the synopsis for using the `tmpfront' script:

       tmpfront { --docbook | --linuxdoc | --teilite }
           { --html | --ascii }  [ --debug ]  DOCUMENT

   For now, this will format DOCUMENT to either HTML or Ascii and
   output on stdout.  `--debug' provides timing statistics.
   `tmpfront' expects to be run from the source directory.  See
   INSTALLATION below for variables to modify in `tmpfront.sh'.

The Process

             (4)         (5)              (6)          (7)
   document  -->  grove  -->  docobjects  -->  format  -->  write
              |           |                |            |
           SPGrove      input          toFORMAT     wrFORMAT
                       spec(1)          spec(2)      spec(3)


    1) load input spec (docbook, linuxdoc, teilite)

    2) load toFORMAT spec (format phase one)

    3) load wrFORMAT spec (format phase two)

    4) load document into grove

    5) transform document into doc objects (DO)

    6) transform DOs into general flow objects

    7) transform general flow objects into output

   (5), (6), and (7) are all performed with ``builders''.  A builder
   is a Perl class that uses visitor functions on it's input to
   transform the input to the output.  Most builders are generated
   from spec files (See SGML::Simple::Spec).

   The transform from document instance into DOs is almost
   one-to-one.

INSTALLATION

   Quilt requires Perl 5, James Clark's SP, SGML::Grove,
   SGML::SPGroveBuilder, Class::Visitor, Class::Template,
   Text::EntityMap, and DTDs for the documents you want to transform.
   Most of these, plus several DTDs and supporting files, are
   available in the Quilt-Kit as a single download.

<http://www.perl.com/>
<http://www.jclark.com/>
<ftp://ftp.uu.net/vendor/bitsko/gdo/>
<ftp://ftp.uu.net/vendor/bitsko/entity-map/>
<ftp://ftp.uu.net/vendor/bitsko/sgml-toolbox/>

   After you get all that installed, modify the paths in `tmpfront'
   so it can find any libraries not installed in Perl's normal spot
   and point `$specs_dir' to Quilt's `specs' directory.

   Quilt installs with just a Perl install:

       perl Makefile.PL
       make
       make test
       make install

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.