Index: /waeup/branches/ulif-rewrite/src/waeup/utils/importexport.txt
===================================================================
--- /waeup/branches/ulif-rewrite/src/waeup/utils/importexport.txt	(revision 4042)
+++ /waeup/branches/ulif-rewrite/src/waeup/utils/importexport.txt	(revision 4042)
@@ -0,0 +1,104 @@
+Importing and Exporting Things
+******************************
+
+The waeup package tries to support all special object types to be
+exportable and importable.
+
+:Test-Layer: unit
+
+As imports and exports of data are a cruical point when doing updates
+or to enable data backups, this support must be considered a serious
+topic for the base functionality of the whole software.
+
+Exports and imports are implemented using the Zope component framework
+capabilities. This means we need some adapters and utilities, which we
+register, by grokking the whole package::
+
+    >>> import grok
+    >>> grok.testing.grok('waeup')
+
+
+Exporting XML
+=============
+
+One of the major formats we support for data export is XML.
+
+When we want to export an object, we can choose the kind of XML to
+generate (plain or pretty) and the destination file. If we do not give
+a file to write to, we get a StringIO object, i.e. an in-memory file.
+
+To show this basic functionality provided for all XML exportable
+objects, we choose faculties.
+
+We can export faculties. First we create a faculty::
+
+    >>> from waeup.university.faculty import Faculty
+    >>> myfaculty = Faculty()
+    >>> myfaculty.name = 'My very faculty.'
+
+Exporting plain XML
+-------------------
+
+Now let's export it to XML. To do this we first ask the framework for
+an exporter::
+
+    >>> from waeup.interfaces import IWAeUPXMLExporter
+    >>> exporter = IWAeUPXMLExporter(myfaculty)
+    >>> exporter
+    <waeup.utils.importexport.XMLExporter object at 0x...>
+
+All exporters provide an ``export(<obj>)`` method::
+
+    >>> result = exporter.export(myfaculty)
+
+The result is an object of type StringIO. We therefore use its
+`read()` method to get the actual XML data::
+
+    >>> print result.read()
+    <?xml version="1.0" encoding="UTF-8"?>...
+
+
+Exporting pretty XML
+--------------------
+
+As the result is one long string (which is necessary to preserve
+linebreaks), it is not very good readable. This special exporter
+however, can also provide ``pretty XML``::
+
+    >>> print exporter.exportPrettyXML(myfaculty).read()
+    <?xml version="1.0" encoding="UTF-8"?>
+    <waeupdata>
+    	<object type="waeup.university.faculty.Faculty">
+    		<attribute name="name" type="str">
+    			My very faculty.
+    		</attribute>
+    	</object>
+    </waeupdata>
+
+Generating XML files
+--------------------
+
+Both methods (`export` and `exportPrettyXML`) support writing the
+results to a file::
+
+    >>> result = exporter.export(myfaculty, 'myexport.xml')
+    >>> print open('myexport.xml', 'rb').read()
+    <?xml version="1.0" encoding="UTF-8"?>...
+
+We can also let the exporter format the output prettier::
+
+    >>> result = exporter.exportPrettyXML(myfaculty, 'myexport.xml')
+    >>> print open('myexport.xml', 'rb').read()
+    <?xml version="1.0" encoding="UTF-8"?>
+    <waeupdata>
+    	<object type="waeup.university.faculty.Faculty">
+    		<attribute name="name" type="str">
+    			My very faculty.
+    		</attribute>
+    	</object>
+    </waeupdata>
+
+Clean up::
+
+    >>> import os
+    >>> os.unlink('myexport.xml')
