[py-svn] r7000 - py/dist/doc

[hpk at codespeak.net]

Author: hpk
Date: Mon Oct 18 13:08:00 2004
New Revision: 7000

Modified:
   py/dist/doc/   (props changed)
   py/dist/doc/future.txt
   py/dist/doc/index.txt
   py/dist/doc/test.txt
Log:
- added a future chapter about lightweightly generating xml  

- some more fixes and additions 



Modified: py/dist/doc/future.txt
==============================================================================
--- py/dist/doc/future.txt	(original)
+++ py/dist/doc/future.txt	Mon Oct 18 13:08:00 2004
@@ -380,6 +380,68 @@
   in the neverending `future book`_. 
 
 
+Generating xml/html 
+===================
+
+The py-doc strives to offer enough functionality to represent
+itself and especially its API in html or xml.  Moreover,
+`py.test`_ wants to run distributedly in order to execute
+tests on different processes and platforms. It will need to
+exchange data between its running program fragments.  
+
+For example, test ``Results`` could be represented in lightweight 
+xml or we could export the whole result of the testing process
+as xml, anyway, to allow other tools to post-process the output. 
+The starting point for this, btw, is the `Reporter`_ from the
+test module. 
+
+lightweight xml generation
+-------------------------- 
+
+Besides DOM implementations there are some interesting
+techniques for marrying XML and python, most notable xist_
+which `uses python class objects`_ to build xml trees. 
+
+However, its implementation seems slightly heavy because it 
+has additional goals like transformations and supporting
+many namespaces.  
+
+Luckily the basic idea is pretty easy to implement, especially
+if we don't validate.  There already is a basic implementation 
+with a lot of *py.test-style* tests `under the
+xpy tree`_ which was mentioned in Holgers `xpython EuroPython 2004 talk`_
+at EuroPython 2004. However, this is still somewhat entangled with
+a different project (see the talk) so it would need some refactoring 
+before integrating it into the py lib. 
+
+basic example for generating html 
+---------------------------------
+
+Consider this example:: 
+
+   import py 
+   py.xml.namespace('html')
+   paras = "First Para", "Second para"
+   doc = html.html(
+       html.head(
+            html.meta(name="Content-Type", value="text/html; charset=utf8))
+       html.body(
+            [html.p(p) for p in paras]))
+   print unicode(doc).encode('latin1')
+
+this would give you a latin1 representation of the obvious document. 
+I think the beauty of this is apparent and beats string-concantentation
+or DOM-manipulations big time.  For now, i don't think we should
+strive to offer much more than the above.  Well, of course, we would
+like to access a sane object model for the generated html but this
+needs some more experimentations and a comparison with xist_ i guess. 
+
+.. _`xpython EuroPython 2004 talk`: http://codespeak.net/svn/user/hpk/talks/xpython-talk.txt
+.. _`under the xpy tree`: http://codespeak.net/svn/user/hpk/xpy/xml.py
 .. _`future book`: future.html 
 .. _`PEP-324 subprocess module`: http://www.python.org/peps/pep-0324.html
 .. _`subprocess implementation`: http://www.lysator.liu.se/~astrand/popen5/
+.. _`py.test`: test.html
+.. _`Reporter`: test.html#reporter
+.. _xist: http://www.livinglogic.de/Python/xist/index.html
+.. _`uses python class objects`: http://www.livinglogic.de/Python/xist/Howto.html

Modified: py/dist/doc/index.txt
==============================================================================
--- py/dist/doc/index.txt	(original)
+++ py/dist/doc/index.txt	Mon Oct 18 13:08:00 2004
@@ -16,7 +16,8 @@
 do not exactly reflect the current state.  Welcome to
 documentation & test driven development :-) 
 
-There is some preliminary documentation on `getting started`_ 
+There is some preliminary documentation for `getting started`_ 
+
 
 .. _`py.execnet`: execnet.html 
 .. _`py.test`: test.html 

Modified: py/dist/doc/test.txt
==============================================================================
--- py/dist/doc/test.txt	(original)
+++ py/dist/doc/test.txt	Mon Oct 18 13:08:00 2004
@@ -289,11 +289,16 @@
   the users gets informed about progress and problems
   in possibly custom ways. 
 
-Reporters process events
-------------------------
+.. _reporter:
+
+Reporters process test events
+-----------------------------
 
 A driver typically invokes certain methods of a Reporter
-for various points in the testing process::
+for various points in the testing process.  A reporter
+is reponsible for representing the testing process 
+to the user or other programs. These are the events
+(function calls) that the reporter receives::
 
     start(), end() are invoked only from the outmost driver 
                    to allow a reporter to write headers and