README for Alexandra

These are XSLT stylesheets to be used with a Relax NG schema.
Alexandra uses the RNG schema to create a roundtripping forms
interface in HTML to edit an instance document that conforms
to the schema.

This is version 0.01, a pre-alpha release.

For more information, see 
    http://simonwoodside.com/dev/xml/alexandra/


Manifest
--------

README         this file
TODO           planned features not yet implemented (may be incomplete :-)
BUGS           known problems (may also be incomplete :-)
VERSION        the current version number (note that this is an XSL stylesheet,
               included by both fo/docbook.xsl and html/docbook.xsl)
LICENSE        The GPL license

update.xsl     primitive update for inst.xml
rng2rngsub.xsl converts RNG to truncated RNG starting at a given xpath
rng2mid.xsl    converts RNG schema to an intermediate forms dialect
mid2html.xsl   converts intermediate forms dialect to HTML

schema/        tools to expand RNG schemas for use with Alexandra
schema/schema-example   some example schemas to play with

Installation
------------

If you do not already have it, install Apache.
    http://httpd.apache.org/
    
If you do not already have it, install AxKit.
    http://axkit.org

Use libxslt with AxKit for your processor for EXSLT support needed
by Alexandra.
    http://xmlsoft.org/XSLT/

Unpack the Alexandra distribution somewhere AxKit can find it.

If you do not already have one, install a CSS2 capable web browser.


Use
---

0. If you have any problems following these instructions,
please contact the author, Simon Woodside <sbwoodside@yahoo.com>

1. RNG
Choose an RNG (Relax NG) schema to use. Alexandra currently only
supports schemas with a finite tree depth (no transitive loops in
the elements).

2. Expand
Expand the schema using the shell script in the schema/ directory.
To do this, name the schema input.rng. Then run expand.sh. This
will begin expansion of the schema. Keep a close eye on the sizes
of the files that the shell script is generating. If their sizes
are exploding exponentially, your schema has infinite depth 
(contains transitive loops) and cannot be used with Alexandra
currently. If it doesn't, the output files should stabilize at a 
certain file size after all of the ref/define have been expanded.
Use any of the stabilized size output files as your schema file
for Alexandra.

Now that you have an expanded schema, that is your document that
users will load in AxKit. You may name it whatever you like.

3. Configure AxKit
Configure AxKit to apply the Alexandra XSLT stylesheets to your
expanded schema file in the following order:

update.xsl
rng2rngsub.xsl
rng2mid.xsl
mid2html.xsl

If you are using processor instructions, you can put this at the 
top of your schema file:

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="update.xsl" ?>
<?xml-stylesheet type="text/xsl" href="rng2rngsub.xsl" ?>
<?xml-stylesheet type="text/xsl" href="rng2mid.xsl" ?>
<?xml-stylesheet type="text/xsl" href="mid2html.xsl" ?>

This defines an XSLT pipeline. The results of each XSLT transformation
will be automatically passed by AxKit to the next stylesheet. The
results from the last stylesheet will be sent to the browser.

If you want to simulate the pipeline without AxKit, just apply the
transformations one at a time, with something like this:

xsltproc update.xsl schema-expanded.xml > 1.xml
xsltproc rng2rngsub.xsl 1.xml > 2.xml
xsltproc rng2mid.xsl 2.xml > 3.xml
xsltproc mid2html.xsl 3.xml > output.html

The results will be the same.

You also need to put the following AxKit command into your
.htaccess file:

AxNoCache On

Without this it may not work properly (? testing needed)

4. instance file
Create a file called inst.xml in the same directory as the
expanded schema file, and make sure it is writeable by apache.

    touch inst.xml
    chmod [something] inst.xml

inst.xml has to be a valid XML file even if it's empty, it must
contain a root tag. It doesn't matter what that tag is when
you are installing.

Alternatively just move the provided instance.xml file to inst.xml
(and make sure it's writable by apache).

5. browser interface
Now point your browser at the correct URL to load the 
expanded schema file from your apache installation. At this point
you will see the beautiful ;-) CSS2 rendered page with
forms for your schema. You may enter data into the fields and use
the (+) button to submit a textarea value. The page should
reload with a notice that the inst.xml file has been updated with
the new content you just entered. It will also show your data
in the proper textarea field in the HTML forms.

Alexandra will automatically truncate deep subtrees to 
improve performance. You can expand them by clicking on the (>>>)
button. When you are browsing a subtree, a breadcrumbs display
will appear at the top of the page to facilitate navigation.


Copyright
---------

Copyright (C) 2002-3 Simon Woodside


License
-------

    Alexandra - RNG (Relax NG)-based roundtripping for HTML forms
    Copyright (C) 2002-3 Simon Woodside

    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


Warranty
--------

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT.  IN NO EVENT SHALL SIMON WOODSIDE OR ANY OTHER
CONTRIBUTOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.


Contacting the Author
---------------------

Simon Woodside, <sbwoodside@yahoo.com>
