                          4Suite 0.10.1 README
                          ====================
    
    
4Suite http://FourThought.com/4Suite

    
Copyright (c) 2000 Fourthought, Inc., USA

    
http://lists.fourthought.com/mailman/listinfo/4suite or send mail too
support@4suite.com

    
Current version: 0.10.1

  
                            License/Copyright
                            -----------------
    
    
4Suite is copyright Fourthought, Inc. (http://FourThought.com).  Please read the file COPYRIGHT for the complete copyright andterms of license.

  
                               Description
                               -----------
    
    
4Suite is a collection of Python tools for XML processing and object-databases.

    
The current version is 0.10.1. See the ChangeLog for notes on the current version.

    
4Suite is an integrated packaging of several formerly separately-distributed
components.  These are as follows.


  2001-01-16:  4Suite 0.10.1 released.

  2000-11-30:  4Suite 0.10.0 released.

  2000-11-14:  4Suite 0.9.2 released, including first public release of DbDom and 4XLink.

  2000-10-11:  4Suite 0.9.1 released, including first public release of 4XPointer.

  2000-09-20:  4Suite 0.9.0 released.  4DOM, 4XPath, 4XSLT, and 4RDF are now bundled therein.  Including first public release of 4ODS.
  
                              Installation
                              ------------
    
    
Download 4Suite install one of the binary packages.  Alternatively, you can download the source instead and install using Python distutils as follows:

    python setup.py install
    
See PACKAGES for more information about the available 4Suite packages.

    
If you have difficulty installing this software, send a problem report to 4Suite@lists.fourthought.com describing the problem.

   
For a complete installation instructions see the HOWTOs.

  
                                Platforms
                                ---------
    
    
4Suite requires Python.  4DOM and 4RDF should work on all platforms supported by Python.  The others have been tested on Red Hat Linux and Windows 98.  They should work on other UNIX variations. They will probably not yet work on Macintosh.  If anyone would like to help port and test on the Mac, please contact us.

  
                               Quick Start
                               -----------
    
    
There are demo files and test suites for each component in the
documentation directories set up by Distutils.  These should
provide useful examples.

  
                               Known Bugs
                               ----------
    
    
See the TODO file

  
                           Contact and Support
                           -------------------
    
    

      For release notes and news, see http://4Suite.org
    


    
Please consider joining the 4Suite users and support mailing list


    http://lists.fourthought.com/mailman/listinfo/4suite

    
4Suite developers monitor the above list, and prefer for support requests to come thereby so that others can benefit from the discussion.  If this is unsuitable, you can address the 4Suite developers directly:

    support@4suite.org
 
                                  4DOM
                                  ----
    
      
4DOM is an implementation of the World-Wide Web Consortium recommended standard document object model for Python.  4DOM implements DOM Core level 2, HTML level 2 and Level 2 Document Traversal.

      
4DOM is designed to allow developers rapidly design applications that read, write or manipulate HTML and XML.


      
4DOM follows the Python DOM binding, for which there is some documentation in the development version of the Python 2.0 docs.

  
    
 ** Directory Structure ** 

      
      xml/dom - Core DOM components (including XML classes)

      xml/dom/html - HTML components

      xml/dom/ext - Extensions and proprietary components

      xml/dom/docs - (currently minimal) documentation

      DOCUMENTATION_PATH/4Suite-0.10.1/demo/4DOM - Small scripts demonstrating some uses of 4DOM.  See the README in this directory.

      DOCUMENTATION_PATH/4Suite-0.10.1/test_suite/4DOM - Test scripts.
    
    
 ** Accessors/Mutators for Attributes ** 

        
        
Following discussion on the Python XML SIG mailing list, 4DOM provides two ways to access DOM interface attributes.  As an example, the DOM IDL definition for the Node interface contains readonly attribute DOMString childNodes.  This can be accessed as a simple Python attribute: node.childNodes, or as a method call using the Python/CORBA mapping for attributes: node._get_childNodes() [if childNodes were a read/write attribute, there would also be a node._set_childNodes()].  There is a slight speed advantage to using the latter convention.

    

    
 ** Document._get_ownerDocument() ** 

      
      
Document._get_ownerDocument() returns a pointer to itself.

    

    
 ** Creating HTML Element Nodes ** 

      
      
HTMLDocument.createElement() overrides the Document.CreateElement() method, looking up the specified tag and returning an instance of the propriate HTML node.  For instance:
        
          # html_doc is an instance of HTMLDocument
          table_elem = html_doc.createElement("TABLE")
          # table_elem is an instance of HTMLTableElement
        
      

    

    
 ** Deviations ** 

      
        
4DOM does not implement DOMString. Instead, the interfaces use a plain Python string or unicode object instead. Note that Python strings do not have particular length limitations, and Python 2.0 is required for unicode support.

      
The DOM Spec sections on the removeAttribute, removeAttributeNS and removeAttributeNode method of the Element interface has some rules for Attribute removal with respect to default values. 4DOM only follows these rules if you remove attributes using the removeAttribute method, and the default attribute will not be properly set if you use removeNamedItem to remove an attribute from the NamedNodeMap returned by Element.getAttributes.

      
4DOM does not implement HTMLElement features strictly for browser environment, for example, blur and focus properties of HTMLSelectElement.

      
Some methods of the DOM spec for HTML do not allow for errors associated with missing nodes. So, for example, HTMLDocument::setTitle() does not allow for the return of an error if the HTMLDocument does not have an HTMLHeadElement child. 4DOM, in these cases, will automatically add in needed elements in order to strictly follow the DOM interface spec.  The methods for which 4DOM provides automatic document completion are:
        
             *  HTMLDocument::getDocumentElement()

             *  HTMLDocument::setTitle()

             *  HTMLDocument::getBody()

             *  HTMLDocument::setBody()

             *  HTMLTableElement::insertRow()

             *  HTMLTableRowElement::insertCell()

       
     

     
See 4DOM Extensions for documentation of proprietary extensions and helper functions provided by 4DOM.

    
  
                                 4XPath
                                 ------
    
      
4XPath implements the W3C XPath language for indicating and selecting XML
document components.

      http://www.w3.org/TR/xpath
      
4XPath implements the full 4XPath specification, and is in beta stage.

    
 ** Directory Structure ** 

      
      xml/xpath - Core XPath components

      DOCUMENTATION_PATH/4Suite-0.10.1/demo/4XPath - Small scripts demonstrating some uses of 4XPath.

      DOCUMENTATION_PATH/4Suite-0.10.1/test_suite/4XPath - Test scripts.
    
    
 ** Othe Documentation ** 

      
      
See the 4XPath API documentation for an overview of the API and examples of 4XPath usage.

      
See 4XPath Extension Functions contains information and examples on how to define custom functions for use in XPath.

    
  
                                  4XSLT
                                  -----
    

    
4XSLT is an XML transformation processor based on the W3C's specification
for the XSLT transform language.


    http://www.w3.org/TR/xslt

    
Currently, 4XSLT supports all of the XSLT 1.0 Recommendation.


    
For general information on using XSLT, Here are a few sources:

    
         *  Uche Ogbuji's brief discussion of XML Namespaces and XSLT in LinuxWorld: Uses 4XSLT - http://www.linuxworld.com/linuxworld/lw-1999-09/lw-09-xml2.html

         *  Miloslav Nic has an excellent, on-line, interactive XSLT tutorial - http://zvon.vscht.cz/HTMLonly/XSLTutorial/Books/Book1/bookInOne.html

         *  Eliotte Rusty Harolde has very graciously put the XSLT chapter of his book _The XML Bible_ on the Web for all.  If you find this useful, consider buying his excellent book. - http://metalab.unc.edu/xml/books/bible/updates/14.html

         *  There is also an XSLT FAQ - http://freespace.virgin.net/b.pawson/xsl/index.html

    

    
 ** Directory Structure ** 

      
      xml/xslt - Core XSLT components

      DOCUMENTATION_PATH/4Suite-0.10.1/demo/4XSLT - Small scripts demonstrating some uses of 4XSLT.

      DOCUMENTATION_PATH/4Suite-0.10.1/test_suite/4XSLT - Test scripts.
    

  
 ** Additional documentation ** 

    
      
See the 4XSLT API documentation for an overview of the API and examples of 4XSLT usage.

      
See the 4XSLT Extension Elements documentation for information and examples on how to define custom elements for use in XSLT.

  
 
                                4XPointer
                                ---------
   
   
4XPointer is a toolkit for processing fragment identifiers for URI-
references that locate a resource of Internet media type text/xml.


   http://www.w3.org/TR/xptr

   
4XPointer features include: Base Name, Child Sequences, and Full XPointers.
Still missing is support for Points and Ranges, and the functions that
deal with them.



  
 ** Directory Structure ** 

    
    Ft/XPointer - Core XPointer components

    

    DOCUMENTATION_PATH/4Suite-0.10.1/test_suite/4XPointer - Test scripts.
  

  
 ** Additional Documentation ** 

    
    
See the 4XPointer API documentation for an the detailed API.

  

 
                                 4XLink
                                 ------
   
   
A Processor for expanding simple and extended "onLoad" links in a XML Document

   http://www.w3.org/TR/xlink
   
4XPointer features include: Simple Link expansion only.


  
 ** Directory Structure ** 

    
    Ft/Xlink - Core Xlink components

    DOCUMENTATION_PATH/4Suite-0.10.1/test_suite/4XLink - Test scripts.
  

  
 ** Additional documentation ** 

    
    
See 4Xlink API documentation for documentation of the 4XLink interfaces.

  

 
                                  4RDF
                                  ----
   
   
Resource Description Framework (RDF) is a standard for managing distributed
meta-data for on-line resources.  For more information, see the W3C's pages
on RDF


   http://www.w3.org/RDF/

   
4RDF is a toolkit and library for RDF processing.  It is written in Python.
4RDF is considered alpha software and is missing some functionality.



For a brief introduction of 4RDF, see Uche Ogbuji's article on XML.com.


  
4RDF uses drivers to provide actual storage of the RDF model.  This can be volatile using the memory driver, or persistent.  For the simplest persistence you can use the shelve driver, which doesn't support transactions, concurrency and all that.  You don't need anything special to use the shelve driver.  For more sophistication you can use the Postgres or Oracle driver as long as you have an available database connection and the Python bindings.  These can be found at:

  
PyGres for Postgres Databases.  Note, for Python 2.0 you will need to use PyGreSQL-3.2 the beta release.

  
DCOracle for Oracle Databases


  
 ** Directory Structure ** 

    

    Ft/Rdf - Core classes implementing the abstract RDF model

    Ft/Rdf/Serialization - Core classes implementing the abstract RDF model

    Ft/Rdf/Drivers - Modules implementing the actual storage for RDF models.

    Ft/Rdf/Inference - An experimental inference engine for RDF meta-data.  This feature is not yet documented, and should be more accessible in the next 4Suite release, but experts can feel free to tinker.

    Ft/Rdf/Parsers - Modules for parsing the RDF inference language (see above).

    DOCUMENTATION_PATH/4Suite-0.10.1/demo/4RDF - Some basic examples of RDF usage.

    DOCUMENTATION_PATH/4Suite-0.10.1/test_suite/4RDF - Test scripts.
   


  
 ** Additional Documentation ** 

    
    
See the 4RDF API documentation for an overview of the API and examples of 4RDF usage.

    
See the RIL Userguide documentation for an overview of the RDF Inference Language.

  

 
                                  4ODS
                                  ----
   
   
4ODS (Object Database Syatem) is an Object Database Management Group (ODMG) 3.0 standard object database management system for Python.  4ODS supports the Object Definition Language (ODL) with the exception of a few types, and operations.  A small subset of the Object Query Language (OQL) is also supported.  Most of the Object Interchange Format (OIF) is supported.


  
The actual data storage is performed by a driver.  The default driver is for the PostgresQL database.  There is also a beta Oracle driver, and a beta AnyDbm Driver.  To change which driver is used set the environment variable FTODS_DB_DRIVER to either Oracle or Dbm.  If the Postgres driver is used, PyGreSQL must be installed.  If the Oracle driver is used, DCOracle must be installed.


  
To set the directory where the Dbm driver stores data use the environment variable FT_DATABASE_DIR.  This defaults to /var/local/data/ftdatabase.

 
  
To set the directory where all of the drivers store file attributes use the environment variable FTODS_LARGE_FILE_DIR.  This defaults to /var/local/data/ftods/


  
NOTE:  The Dbm driver is not concurrent, although it does support transactions.  Concurrency is planned for future development of the driver.  Be careful when using this driver in a multi-processing/multi-threading application.


  
 ** Directory Structure ** 

    
    Ft/Ods - Core ODS files.

    Ft/Ods/Collections - ODMG standard collections.

    Ft/Ods/MetaData - Classes implementing ODMG standard meta-data.

    Ft/Ods/Parsers - ODL, OQL and OIF pasers.

    Ft/Ods/StorageManager - The back-end storage and transaction data management system.

    Ft/Ods/Tools - Utility scripts and programs.

    DOCUMENTATION_PATH/4Suite/4ODS-0.10.1/demo/4ODS - Some basic demonstrations of 4ODS.  Includes a DOM persistence system and a simple bookmark manager.

    DOCUMENTATION_PATH/4Suite-0.10.1/test_suite/4ODS - Test scripts.
   

  
 ** Additional Documentation ** 

    
    
See the 4ODS User's Guide for additional information

  
 
                                  DbDom
                                  -----
   
   
  DbDom is a Python implementation of The Document Object Model (DOM), a standard set of interfaces for accessing and modifing XML and HTML documents.  DbDom allows these documents to be accessed from a 4ODS database.


  
 ** Directory Structure ** 

    
    Ft/DbDom - Core classes implementing DbDom

    DOCUMENTATION_PATH/4Suite-0.10.1/test_suite/DbDom - Test scripts.
  

  
 ** Additional Documentation ** 

    
    
See the DbDom API documentation for an overview of the API and examples of DbDom usage.

  
 
