OOoPy: Modify OpenOffice.org documents in Python
================================================

OpenOffice.org (OOo) documents are ZIP archives containing several XML
files.  Therefore it is easy to inspect, create, or modify OOo
documents. OOoPy is a library in Python for these tasks with OOo
documents. To not reinvent the wheel, OOoPy uses an existing XML
library, ElementTree_ by Fredrik Lundh. OOoPy is a thin wrapper around
ElementTree_ using Python's ZipFile to read and write OOo documents.

.. _ElementTree: http://effbot.org/zone/element-index.htm

In addition to being a wrapper for ElementTree_, OOoPy contains a
framework for applying XML transforms to OOo documents. Several
Transforms for OOo documents exist, e.g., for changing OOo fields (OOo
Insert-Fields menu) or using OOo fields for a mail merge application.
Some other transformations for modifying OOo settings and meta
information are also given as examples.

Applications like this come in handy in applications where calling
native OOo is not an option, e.g., in server-side Web applications.

Don't be alarmed by the Alpha-Status of the Software: Reading and
writing of OOo documents is stable as well as most transforms.

The only problematic transform is mailmerge: The OOo format is well
documented but there are ordering constraints in the body of an OOo
document. I've not yet figured out all the tags and their order in the
OOo body.  Another known shortcoming of OOoPys mailmerge is the
renumbering of body parts of an OOo document. Individual parts (like
e.g., frames, sections, tables) need to have their own unique names.
After a mailmerge, there are duplicate names for some items. So far I'm
renumbering only frames, sections, and tables. See the renumber objects
at the end of ooopy/Transforms.py. So if you encounter missing parts of
the mailmerged document, check if there are some renumberings missing or
send me a `bug report`_.

Another reason for the Alpha-Status is stability of the API. I may
still change the API slightly.

.. _`bug report`: http://ooopy.sourceforge.net/#reporting-bugs

For running the doctest on python2.3 with the metaclass trickery of
autosuper, see the file run_doctest.py.

Resources
---------

Project information and download from `Sourceforge main page`_

.. _`Sourceforge main page`: http://sourceforge.net/projects/ooopy/

You need at least version 2.3 of python. I have *not* tested with 2.4,
so if you do and encounter bugs, please file a bug report.

For using OOoPy, you need to download and install the
`ElementTree Library`_ by Fredrik Lundh. For documentation about the OOo
XML file format, see the book by J. David Eisenberg called
`OpenOffice.org XML Essentials`_ which is under the Gnu Free
Documentation License and will probably be printed soon. For a reference
document you may want to check out the `XML File Format Specification`_
(PDF) by OpenOffice.org.

A german page for OOoPy exists at `runtux.com`_

.. _`ElementTree Library`: http://effbot.org/downloads/#elementtree
.. _`OpenOffice.org XML Essentials`: http://books.evc-cit.info/
.. _`XML File Format Specification`: http://xml.openoffice.org/xml_specification.pdf
.. _`runtux.com`: http://www.runtux.com/ooopy.html

Reporting Bugs
--------------
Please use the `Sourceforge Bug Tracker`_ and

 - attach the OOo document that reproduces your problem
 - give a short description of what you think is the correct behaviour
 - give a description of the observed behaviour
 - tell me exactly what you did.

.. _`Sourceforge Bug Tracker`:
    http://sourceforge.net/tracker/?group_id=134329&atid=729727
