jaxml v2.22 - April 23rd 2001
(C) Jerome Alet <alet@unice.fr> 2000-2001
You're welcome to redistribute this software under the
terms of the GNU General Public Licence version 2.0
or, at your option, any higher version.

You can read the complete GNU GPL in the file COPYING
which should come along with this software, or visit
the Free Software Foundation's WEB site http://www.fsf.org

----------------------------------------------------------

I was recently asked if the GPL meant that if you just import this
module then you should license your software under the GPL, here's
the answer:

You've written a software which uses (import) my GPLed module.

- If you don't plan to redistribute your software (e.g. internal use only),
  then you can do whatever you want, and hide your software's sources from
  your co-workers if you want (but not my software's sources).

- BUT, if you want to redistribute your software to a third party,
  then your software MUST be GPLed too, and distributed with all its sources.

Please consider this module just like a GPLed C library, not a LGPLed
one.

I hope this is clearer now. Just refer to the GPL (the file COPYING)
for details.

FYI I've choosen to GPL this module because I strongly believe
in the Free Software movement, and want to discourage the
creation of proprietary software.

----------------------------------------------------------

This python module defines a class named XML_document which will
allow you to generate XML documents (yeah !) more easily than
using print or similar functions.

Here's a list of available methods:
===================================

	__init__(version, encoding)
		The instance constructor, automatically called
		when you create a new instance of XML_document.
		you can optionnally pass a version and encoding
		string, the defaults are "1.0" and "iso-8859-1".

	_indentstring(istr)
		istr is the new indentation string used
		to nicely present your XML documents. By
		default istr is equal to 4 space characters.

	_output(filearg)
		use it to save the XML document to a file.
		The optionnal filearg argument may be:
		    None, "", or "-" which stands for sys.stdout.
		    a file name.
		    any file object.

	_text(sometext)
		use it to insert plain text at the current position
		in the document.

	_push()
		saves the current position in the XML document.
		use it if you're going to create a bunch of nested
		XML tags and want to escape from them later to continue
		your document at the same indentation level.

	_pop()
		restores the latest saved position.
		use it to escape from nested tags and continue
		your XML document at the same indentation level than
		the latest time you called _push().

	_template(file, **vars)
		loads a template file and insert it as plain text at the current
		position in the document, replacing ##varname## variables
		in the template file with their corresponding value passed
		in vars[varname]

	_updatemapping(newmap)
		updates the internal mapping used for replacing some strings with
		others when rendering. This can be used as an easy way to
		do templating without the need of an external file.
		Pass None or no argument to reset the mapping to an empty one.
		This method returns the new mapping's content.

	Some more methods are available but not meant to be used directly, they
are: __nonzero__, __getitem__, __setitem__, __delitem__, __coerce__, __add__,
__radd__, __mul__, __rmul__, and __copy__. They are used automatically when doing
special things, read the source for details.

	ANY and ALL other method you may call will be treated as an XML
tag, unless it already exists as a method in XML_document or a subclass of it,
or its name begins with "__". I suggest you to only add methods whose names
begin with '_' to keep things simple and clear: "__" is reserved for future
use.

The file test/test.py is an example program which generates
some documents, just play with it (use and modify) and you'll
learn quickly how to use jaxml. Its source code is documented and
attempts at describing and trying all jaxml's possibilities, so reading
it is probably the best way to become powerful with jaxml in less than
10 minutes.

=========================================================================

Since version 2.00, jaxml integrates the full functionnalities of the
old jahtml module via the HTML_document and CGI_document classes, however
the API for these two classes has changed to be cleaner and don't use any
predefined set of tags.

The HTML_document() and CGI_document() classes both inherit from XML_document()
and all its methods (see above), but also feature some useful helper methods.

Please read the jaxml module sources and the test/test.py program to learn how
to use them.

=========================================================================

The only difficult things are:
------------------------------

	* you have to use the _push() and _pop() methods if you need
	  to get out of a bunch of nested tags.

	* if you call a method (tag) with a string as the first
	  unnamed parameter, you won't need _push() or _pop()
	  because your tag will be automatically closed immediately.

----------------------------------------------------------

INSTALLATION:
=============

If you don't have Distutils installed (e.g. python version <= 1.5.2)
then first download it from:

	http://www.python.org/sigs/distutils-sig/

then follow the installation instructions for Distutils and install
it on your system.

Download the latest jaxml version from:

	http://cortex.unice.fr/~jerome/jaxml/

Extract it:

	gzip -d jaxml-x.xx.tar.gz | tar -xf -

	where x.xx is jaxml's latest version number.

Go to jaxml directory:

	cd jaxml-x.xx

Just type:

	python setup.py install

You may need to be logged in with sufficient privileges (e.g. root)

You can optionnaly go to the test subdirectory and run test.py,
this should produce some XML output both on the screen and in
a file named sampleXML.xml

If you've got the old jahtml module, then you can remove it from your
disk, after having modified your programs to use the new jaxml API.

Voil !

----------------------------------------------------------

You're very welcome to send me any idea or patch about this module.

See the CREDITS file for credits.

Always remember that the test/test.py program and the jaxml.py
module's source code are your best friends.

I hope this will be helpful to someone else.

Feedback is very welcome.

Jerome Alet - <alet@unice.fr>
