Index: pyuno/doc/python-bridge.html
===================================================================
--- pyuno/doc/python-bridge.html.orig	2003-05-25 01:33:47.000000000 +0200
+++ pyuno/doc/python-bridge.html	2004-08-29 11:52:30.861707728 +0200
@@ -1,11 +1,17 @@
 <html>
 
+<head>
+<meta HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
+</head>
 <body>
-<h1> Python-UNO bridge for OO1.1</h1>
+<h1> Python-UNO bridge</h1>
+
 
 <p>
+- <a href="#translations">Translations</a><br>
 - <a href="#intro">Introduction</a><br>
 - <a href="#state">State</a><br>
+- <a href="#download">Download</a><br>
 - <a href="#tutorial">Tutorial</a><br>
 -- <a href="#install">PyUNO Installation</a><br>
 -- <a href="#modes">PyUNO Bridge Modes</a><br>
@@ -17,16 +23,23 @@
 -- <a href="#outparas">Out parameter handling</a><br>
 -- <a href="#exception">Exception handling</a><br>
 -- <a href="#helper">unohelper module</a><br>
--- <a href="#tips">Tips and Known Issues</a><br>
 
 - <a href="#dependencies">Dependencies</a><br>
 - <a href="#bootstrap">Bootstrapping in non-OOo environments</a><br>
 - <a href="#source">Building from source</a><br>
 - <a href="#replacing">Replacing the python runtime</a><br>
-- <a href="#changes">Changes</a><br>
+- <a href="#scripting-framework">Support for the new scripting framework </a><br>
 - <a href="#references">External references</a><br>
+- <a href="#faq">FAQ</a> (read this FIRST when you have problems)<br>
 - <a href="#authors">Authors</a><br>
 
+<a name="translations"><h2>Translations</h2></a>
+<p>
+
+Find <a href="http://www.openoffice.org/files/documents/73/1509/python_uno_bridge.htm">
+here</a>
+a shortened spanish version of this document.
+
 <a name="intro"><h2> Introduction </h2></a>
 The Python-UNO bridge allows to use the standard OpenOffice.org API from 
 the well known python scripting language. It addtionally allows to develop UNO components
@@ -38,6 +51,14 @@ from Java, C++ or the built in StarBasic
 <a href="http://udk.openoffice.org/python/python-bridge.html">
 http://udk.openoffice.org/python/python-bridge.html</a>
 
+<a name="download"><h2>Download</h2>
+You can download this documentation including examples 
+and <a href="#scripting-framework"> support for the new scripting-framework</a>
+
+for offline work.
+
+<p><strong>Download  <a href="http://udk.openoffice.org/python/pyuno-doc.zip">pyuno-doc.zip</a> </strong>( less than 0.5 MB).
+
 <a name="state"><h2>State</h2></a>
 
 <p> The Python-UNO bridge is feature complete, but has not been used by
@@ -45,12 +66,6 @@ many people up to now, so it may contain
 OpenOffice.org 1.1 source tree. It does not run with the OpenOffice.org 1.0.x
 source tree.
 
-<p> <strong> Note: </strong>
-PyUNO comes with OpenOffice.org itself, but it is (not yet) by default selected
-in the OOo
-standard installation. It can be switched on with the customized installation
-(see Optional Components/PyUNO Bridge).
-
 <p> The documentation in its current state is targeted at developers, who
 have already some experience with OpenOffice.org API and with some other
 programming language (Java/C++/StarBasic). If you are a newbie and you think,
@@ -63,8 +78,13 @@ can be used to automate OpenOffice. This
 there is lots of resources available in the office development kit and
 the developer manual.
 
-<a name="install"><h3> PyUNO Installation </h4></a>
-The PyUNO-Bridge must be explicitly selected during OOo installation. Choose
+<a name="install"><h3> PyUNO Installation </h3></a>
+With OpenOffice1.1RC4 and higher, PyUNO is included in the default installation. You
+can skip to the next paragraph.
+
+<p>
+When you use OpenOffice1.1RC3 or earlier,
+the PyUNO-Bridge must be explicitly selected during OOo installation. Choose
 therefor customized setup,
 
 <p>
@@ -79,7 +99,14 @@ therefor customized setup,
 within the office installation and selecting <code>Modify</code> in the upcoming
 dialog.
 
-<a name="modes"><h3>PyUNO bridge modes</h4></a>
+<p> <strong> Note:</strong> When you choose the <code>install</code> script
+(e.g. <code>install --prefix=/usr/local</code>) for installation, you can
+only activate pyuno after the installation by starting <code>setup /net</code>
+and choosing Modify. Note, that in OOorc2, there is a bug which does not install
+two .ini files as they should in this case.
+
+
+<a name="modes"><h3>PyUNO bridge modes</h3></a>
 PyUNO can be used in two different modes 
 
 <ol>
@@ -132,19 +159,27 @@ ctx = resolver.resolve( "uno:socket,host
 smgr = ctx.ServiceManager
 
 # get the central desktop object
-desktop = smgr.createInstanceWithContext( "com.sun.star.frame.Desktop",remoteContext)
+desktop = smgr.createInstanceWithContext( "com.sun.star.frame.Desktop",ctx)
 
 # access the current writer document
 model = desktop.getCurrentComponent()
 
 # access the document's text property
-text = doc.Text
+text = model.Text
 
 # create a cursor
 cursor = text.createTextCursor()
 
 # insert the text into the document
 text.insertString( cursor, "Hello World", 0 )
+
+# Do a nasty thing before exiting the python process. In case the
+# last call is a oneway call (e.g. see idl-spec of insertString),
+# it must be forced out of the remote-bridge caches before python
+# exits the process. Otherwise, the oneway call may or may not reach
+# the target object.
+# I do this here by calling a cheap synchronous call (getPropertyValue).
+ctx.ServiceManager
 </pre></font></td></tr></table>
 
 <p>
@@ -153,8 +188,14 @@ Now start the above script with the pyth
 <table width="100%" bgcolor="lightgrey"><tr><td><font size="-1"><pre>
 
 c:\Program Files\OpenOffice1.1\program> .\python hello_world.py 
-
 </pre></font></td></tr></table>
+
+<font size="-2"><strong>Note:</strong> You must use the script/batch file in the
+program directory to start python, simply starting the python executable
+in the runtime directory (or from python installation installed somewhere else
+on your machine) will not work.
+</font><br>
+
 <p>
 This scripts prints "Hello World" into the current writer document.
 
@@ -261,6 +302,15 @@ zip hello_world.zip Addons.xcu hello_wor
 This package can then be deployed into an OpenOffice installation using the
 <code>pkgchk</code> tool, which is located in the OOo program directory. Note,
 that the office must have been terminated before.
+<p>
+<font size="-2"><strong>Note:</strong> Make sure, that the PYTHONPATH
+environment variable is NOT set when you start pkgchk or soffice
+(see <a href="http://www.openoffice.org/issues/show_bug.cgi?id=17339">#i17339#</a>).
+This may require, that you create a batch file for soffice on windows,
+unset PYTHONPATH in the system configuration or always start soffice from the
+shell with set PYTHONPATH=  (windows) or unsetenv PYTHONPATH (unix tcsh shell).
+
+</font>
 
 
 <table width="100%" bgcolor="lightgrey"><tr><td><font size="-1"><pre>
@@ -306,7 +356,7 @@ retrieve the office component context di
 In the following you find the full description about how UNO features are mapped to the
 python language.
 
-<a name="mapping"><h3>UNO Type mapping </h2></a>
+<a name="mapping"><h3>UNO Type mapping </h3></a>
 
 <table border>
 <tr>
@@ -354,7 +404,7 @@ and boolean values.
 
 
 <p> As long as a boolean is specified in the interface method signature,
-you may also you numbers. In the following example, all calls are valid:
+you may also use numbers. In the following example, all calls are valid:
 
 <table width="100%" bgcolor="lightgrey"><tr><td><font size="-1"><pre>
 #idl signature void takeBool( [in] boolean bool )
@@ -552,7 +602,7 @@ However, simply assigning a struct to an
 create a copy, but simply creates an alias to the original instance.
 
 <table width="100%" bgcolor="lightgrey"><tr><td><font size="-1"><pre>
-struct = uno.createIdlStruct( "com.sun.star.beans.PropertyValue" )
+struct = uno.createUnoStruct( "com.sun.star.beans.PropertyValue" )
 
 struct.Name = "foo"
 struct2 = struct
@@ -1000,101 +1050,6 @@ supported interfaces, supported methods 
 </table>
 
 
-<a name="tips"><h3> General tips and known issues </h3></a>
-
-<ul>
-<li> When you package your code as a python component, there is
-     currently a bug which lets the office crash in case you have
-     any syntax error in your code, see
-
-     <a href="http://www.openoffice.org/issues/show_bug.cgi?id=13377">
-     http://www.openoffice.org/issues/show_bug.cgi?id=13377</a>.
-
-     You may workaround this bug by adding a <code>try: except:</code> level
-     in your trigger code.
-
-<li> The semantics of the OpenOffice API is a very complex topic, which can't be
-     discussed in this python document. Try to gather information from other
-     resources, especially from the developer manual (see below). Most sample
-     code you find there is written in Java. It is not so difficult to translate
-     java code to python, when you know the following differences:
-     <p>
-
-     In python you don't need <code>queryInterface</code>. E.g. Java code like
-
-<table width="100%" bgcolor="lightgrey"><tr><td><font size="-1"><pre>
-            oInterface = (XInterface) oMSF.createInstance(
-	                         "com.sun.star.frame.Desktop" );
-            oCLoader = ( XComponentLoader ) UnoRuntime.queryInterface(
-	                         XComponentLoader.class, oInterface );
-	    PropertyValue [] szEmptyArgs = new PropertyValue [0];
-	    aDoc = oCLoader.loadComponentFromURL(
-                     "private:factory/swriter" , "_blank", 0, szEmptyArgs );
-</pre></font></td></tr></table>
-
-      becomes in python simply   
-
-<table width="100%" bgcolor="lightgrey"><tr><td><font size="-1"><pre>
-            oCLoader = oMSF.createInstance( "com.sun.star.frame.Desktop" )
-	    aDoc = oCLoader.loadComponentFromURL(
-	                 "private:factory/swriter", "_blank", 0, () )
-</pre></font></td></tr></table>
-      . You don't need this intermediate oInterface variable anymore.
-      So, here python code simplifies a lot, with a little training, one
-      shouldn't have too many problems to translate java to python code.
-     
-<li> There are some places, where the loss in type safety leads to difficulties,
-     as e.g. bug
-     <a href="http://www.openoffice.org/issues/show_bug.cgi?id=12504">
-     http://www.openoffice.org/issues/show_bug.cgi?id=12504</a>. The problem
-     here is, that the C++ implementation within the office expects a
-     <code>sequence&lt; PropertyValue &gt;</code>, while the PyUNO runtime
-     converts it to a <code>sequence&lt; any&gt;</code>, where each <code>any</code>
-     contains a <code>PropertyValue</code>. In my eyes, this is a bug within
-     the C++ code. There is has been added a workaround to pyuno.
-     See the below sample:
-
-<table width="100%" bgcolor="lightgrey"><tr><td><font size="-1"><pre>
-import uno
-import unohelper
-
-localContext = uno.getComponentContext()
-
-resolver = localContext.ServiceManager.createInstanceWithContext(
-    "com.sun.star.bridge.UnoUrlResolver", localContext)
-ctx = resolver.resolve(
-    "uno:socket,host=localhost,port=2002;urp;StarOffice.ComponentContext")
-smgr= ctx.ServiceManager
-desktop = smgr.createInstanceWithContext("com.sun.star.frame.Desktop",ctx)
-doc = desktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, ())
-            
-style = doc.createInstance("com.sun.star.style.NumberingStyle")
-family = doc.getStyleFamilies().getByName('NumberingStyles')
-family.insertByName('List test', style)
-
-rule = style.getPropertyValue('NumberingRules')
-level = rule.getByIndex(0)
-
-# the normal call would have been:
-# rule.replaceByIndex( 0, level )
-# but this will end up in a excpetion
-# magic to pass the exact type to the callee
-uno.invoke( rule , "replaceByIndex", (0, uno.Any("[]com.sun.star.beans.PropertyValue",level)) )
-</pre></font></td></tr></table>
-
-<p>This is the only place, where the uno.Any is used. Using the uno.Any in normal
-calls will lead to RuntimeExceptions. A python uno object implementation will never
-receive an instance of uno.Any() as a incoming parameter, instead always the value within the
-is passed.
-
-<p> This solution looks really ugly, but it allows you to continue, where you otherwise
-can only give up or switch to another implementation language.
-
-     <p> Problems like above are not very frequently found, but in case they
-     hit you, there is not much you can do, this API is then locked up
-     for the python programmer.
-     
-</ul>
 
 <a name="dependencies"><h2> Dependencies</h2></a>
 This chapter is most interesting for people who want to use the Python-UNO bridge
@@ -1186,7 +1141,7 @@ ret,seq = pipe.readBytes( None, 3 )
 
 
 
-<a name="source"><h2> Building from source</h4></a>
+<a name="source"><h2> Building from source</h2></a>
 The Python-UNO Bridge consists of two source modules,
 
 <ol>
@@ -1231,7 +1186,7 @@ using dmake runtest, you shouldn't get a
 <a name="replacing"><h2>Replacing the default python core with your system's python installation</h2></a>
 OOo by default ships with the Python-2.2.2 core runtime. This is fine for most
 users, but some hackers may want to replace the runtime with either a newer python
-runtime (e.g. Python-2.3a) or with the python system's installation, which e.g.
+runtime (e.g. Python-2.3) or with the python system's installation, which e.g.
 may contain more optional packages, which you also want to use in python.
 
 <p>This shall not be a full explanation, on how you can exchange the python runtime. Also
@@ -1244,7 +1199,7 @@ help you doing this.
 directory and the python shared library in the program directory itself.
 <li> On unix systems, python itself is linked to the compilers standard C++ library.
      In most cases, this requires, that python and office must be built with the
-     the same C++ compiler. For the standard OpenOffic.org build, this is the gcc-3.0.3
+     the same C++ compiler. For the standard OpenOffic.org build, this is the GCC 3.2.2
      (at the time of writing this document). Other builds may use different
      compilers.
 <li> On some unix distributions, no libpython.so gets build, you need to do this yourself
@@ -1253,89 +1208,123 @@ directory and the python shared library 
      tested.
 </ul>
 
-<a name="changes"><h2> Changes </h2></a>
-<ul>
-<li> Version OO1.1
-<pre>
-    As PyUNO is now packaged with OpenOffice.org itself, it carries
-    now the identical version number as OOo itself.
+<a name="scripting-framework"><h2>Support for the new scripting framework</h2></a>
+There is now a uno-package available, which allows the support of the new scripting
+framework for OpenOffice.org 2.0. It is included in the <a href="#download">above download</a>
+. It allows to execute python scripts in the new framework.
+This paragraph shall just explain how to install and use the python part of the new
+framework, it shall not explain the framework itself.
 
-   changes:
-     - You get now readable python stacktraces, when e.g. from StarBasic a
-       python method is called, which throws an exception.
-     - The python component loader supports additionally to the vnd.openoffice.pymodule)
-       the file and the vnd.sun.star.expand protocol.
-     - Python UNO components can now be added to UNO packages.
-     - #i12504# UNO any handling has been added, it is now possible
-       to pass uno.Any with a distinict type to the caller. The syntax for this is really
-       ugly, it should only be used in cases, where the usual callee code does not
-       correctly convert the incoming parameter (see the new any row in the
-       uno type table).
-     - unohelper.inspect has been added. This functions inspects a uno object
-       and dumps all known reflection information like supported services,
-       interfaces, methods and properties. Nice debugging tool.
+<h3> Installation</h3>
+<ol>
+<li> Install an OpenOffice.org 1.1rc or newer with PyUNO activated
+     ( see <a href="install">above</a> ).
         
-</pre>
+<li> Install the <a href="http://framework.openoffice.org/scripting">scripting framework</a>
+(tested with version 0.3)
+
+<li> Copy the file scriptrt4python-0.1.0.zip into
+ &lt;office-install&gt;/user/uno_packages
 
-<li> Version 0.9.3<p>
+<li> run pkgchk in &lt;office-install&gt;/program
+
+<li> Deploy the sample script stored in the
+  samples/hello-framework-python.sxp parcel into the office
+  (e.g. with the scripting-framework CommandLineTools, for example
+<p>
 <pre>
-  changes:
-    - pyuno now runs on the OO1.1beta version
-      (use older versions for OO643C).
-
-  fixed bugs:
-    - #i12613# setPropertyValue('ParaAdjust', 1) does not set ParaAdjust
-          ( python longs are now treated like python integers, when they are converted
-	    to UNO [narrowing to the smallest possible UNO value])
-    - #i12673# Cosmetic and other changes to uno.py
-          ( Patch by Christian Zagrodnick )
+  java CommandLineTools -d hello-framework-python.sxp  \
+           /usr/local/joerg/OpenOffice.org1.1/user/Scripts
 </pre>
-</li>
-<li> Version 0.9.2<p>
-<pre>
-  fixed bugs:
-    - #i11487# PyUNO interfaces are not transitive
-    - python list aren't accepted anymore in place of UNO
-      sequences. Only tuples are accepted.
-    - unicode string conversions should now also work on systems
-      where sizeof( wchar_t ) == 4
-
-  changes:
-    - The source is now available from the OOo CVS repository.
-    - uno.ByteSequence (idl sequence<byte>) is now treated
-      differently than before (this is an incompatible change).
-      See documentation for more information)
-    - file url conversion routines added (API calls need file urls)
-      ( unohelper.systemPathToFileUrl(), unohelper.fileUrlToSystemPath(),
-        unohelper.absolutize())
-    - added two more samples.
-      * ooextract.py extracts pure text from a given OOo document
-      and dumps it on stdout (which allows you to grep through
-      OOo documents :o) )
-
-      * biblioaccess.py is a small example showing how
-        to access the database API within OOo.
-    - uno.Bool is now deprecated, instead python True and False
-      are used.	
-
-  changes in source distribution:
-    - build -i for the windows python build is not
-      necessary anymore.
-    - Build environment has changed. Only the d.lst and the
-      makefile in the python module depends now on the concrete
-      used python version. This should make python version
-      changes easier in future. 
-
-  changes in binary distribution:
-    - pyuno ships now with a precompiled python runtime.
-      This is necessary, because pyuno and python must
-      be compiled with the same compiler version of gcc
-      on unix platforms. 
-    - therefor, pyuno's environment files pyunoenv.[bat|tcsh]
-      have simplified a little.
+  ).
+</ol>
+
+
+<h3> Deinstallation </h3>
+
+<ol>
+<li> Uninstall the hello-framework-python.sxp
+<li> delete the file &lt;office-install&gt;/user/uno_packages/scriptrt4python-0.1.0.zip
+<li> run pkchk
+</ol>
+
+<h3> Writing your own scripts</h3>
+You can write scripts simply by defining python functions. You can
+have multiple functions within one file, but the file must be selfcontained
+meaning that it may only reference the core python library but not any self written
+scripting files (may be a future extension).
+
+<p>
+Below you can find the sample script, which just pastes a
+'Hello Scriptingframework' into the current document. The following
+script is stored as <code>HelloFramework.py</code>.
+
+<table width="100%" bgcolor="lightgrey"><tr><td><font size="-1"><pre>
+# Sample python script for the scripting framework
+
+# scriptCtx supports getDocument(), getComponentContext(), getDesktop()
+def Hello( scriptCtx ):
+    print "entering HelloFramework.Hello"
+    
+    model = scriptCtx.getDocument()
+
+    # access the document's text property
+    text = model.Text
+
+    # create a cursor
+    cursor = text.createTextCursor()
+
+    # insert the text into the document
+    text.insertString( cursor, "Hello Scriptingframework", 0 )
+
+    return None
+</pre></font></td></tr></table>
+
+Beside the script file you must provide a <code>parcel-descriptor.xml</code>
+file which describes all functions, that shall be callable fromt the office.
+Here is the sample file for the above script.
+
+<table width="100%" bgcolor="lightgrey"><tr><td><font size="-1"><pre>
+&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;parcel language="Python" xmlns:parcel="scripting.dtd"&gt;
+    &lt;script language="Python"&gt;
+        &lt;locale lang="en"&gt;
+            &lt;displayname value="HelloFramework.Hello"/&gt;
+            &lt;description&gt;
+                Prints a 'Hello Framework' into the current document
+            &lt;/description&gt;
+        &lt;/locale&gt;
+        &lt;functionname value="HelloFramework.Hello"/&gt;
+        &lt;logicalname value="HelloFramework.Hello"/&gt;
+    &lt;/script&gt;
+&lt;/parcel&gt;
+</pre></font></td></tr></table>
+
+Note, that the each reference to the script must be written as
+<code>&lt;source-file-name-without-.py&gt;.&lt;function-name&gt;</code>.
+
+<p>
+The function gets called with a XScriptContext implementation as the first parameter.
+It provides the UNO component context (getComponentContext()), the desktop
+(getDesktop()) and the current document model (getDocument()) (if any).
+
+<p>
+Zip these two files as a .sxp file and deploy it into the office using
+the scripting frameworks commandlinetool. When you restart the office, you
+should be able to select the new script in the scriptinframework's dialogs.
+
+<p>
+Things to keep in mind:
+<ul>
+<li> each function must leave with <code>return None</code></a>
+<li> live editing while the office is running is possible (when you edit
+     the file at the place, where the CommandLineTool deploys it)
+<li> performance is poor (script is recompiled for every execution), no caching </li>
+<li> interface to the script may change in future releases
+(e.g. the first parameter of the function)
+<li> error messages are currently printed to stderr (only readable
+on unix systems)
 
-</pre>
-</li>
 </ul>
 
 
@@ -1360,6 +1349,272 @@ directory and the python shared library 
 
 </table>
 
+
+
+<a name="faq"><h2>Frequently Asked Questions </h2></a>
+
+<ol>
+
+<li> <h4> Why do I get a 'bus error' when starting the hello-world-script on solaris ?</h4>
+There seems to be a corrupted version of the libpyuno.so in the OpenOffice.org1.1.0
+installation set. The reason is not yet clear, might be either a bug in pyuno code or
+a build error. Please download <a href="libpyuno.so.gz">libpyuno.so.gz</a>
+to patch OOo1.1.0 version (do not apply
+this patch on any other version than OOo1.1.0 solaris sparc!).
+
+
+
+<li> <h4> Why do I get a 'SystemError: pyuno runtime is not initialized, ...' when starting the script ?</h4>
+<ul>
+
+<li> Pyuno was not installed correctly (OO1.1RC2 and earlier, fixed with RC3). Please check
+<p>
+<code>&lt;openoffice-install&gt;/program $ ls -c1d py*</code>
+<pre>
+    pyunorc
+    pythonloader.py
+    pythonloader.unorc
+    python
+    python.sh
+    python-core
+    python-core-2.2.2
+    pythonloader.uno.so
+    pyuno.so
+</pre>
+
+    Under certain circumstances, it may occur, that the following ini files are missing
+
+    <p>
+pyunorc (or pyuno.ini on windows):
+<table width="100%" bgcolor="lightgrey"><tr><td><font size="-1"><pre>
+[Bootstrap]
+UNO_TYPES=$ORIGIN/types.rdb
+UNO_SERVICES=$ORIGIN/services.rdb
+</pre></font></td></tr></table>
+
+<p>
+pythonloader.unorc (or pythonloader.unorc on windows):
+<table width="100%" bgcolor="lightgrey"><tr><td><font size="-1"><pre>
+[Bootstrap]
+PYTHONHOME=$ORIGIN/python-core
+PYTHONPATH=$ORIGIN/python-core/lib $ORIGIN/python-core/lib/lib-dynload $ORIGIN
+</pre></font></td></tr></table>
+Simply cut and paste them into a texteditor to create them.
+    
+<li> There have been reported some failures with the above error message, which have not been
+    resolved yet. You may e.g. want to follow
+    <a href="http://www.openoffice.org/issues/show_bug.cgi?id=17339">#i17339#</a>.
+</ul>
+
+<li> <h4>Why do I get a 'SystemError: _PyImport_FixupExtension: module pyuno not loaded' when starting the script ? </h4>
+
+This in general happens, when you still start the system's python installation.
+OpenOffice.org ships a python installation (because python and the office must
+have been built with the identical compiler version).
+Please check this with 'which python'. Simply address OpenOffice.org's python absolutely, e.g. use
+/usr/local/OpenOffice.org1.1/program/python myscript.py.
+
+<li> <h4>Why do I get a "error: python-loader:'No module named pythonloader'" when running pkgchk with a python component ?</h4>
+     Make sure to unset PYTHONPATH and PYTHONHOME (which you may have set, because you have
+     an own python installed on your system) environment variables before running
+     soffice AND pkgchk. This is a workaround, it is currently thought about a better
+     solution.
+     
+
+<li> <h4>Why do I get an error message 'msvcr70.dll or python22.dll not found' when starting python ?<br>
+ (or  Why do I get an 'error while loading shared libraries: libstdc++.so.x' ? ) 
+</h4>
+You probably try to start python from e.g. c:\program files\OpenOffice.org1.1\program\python-runtime\bin\python.exe, but you have to use c:\program files\OpenOffice.org1.1\program\python.bat.
+
+
+<li> <h4>Why do I get 'PYTHONPATH=... is not an identifier' when starting python ?</h4>
+      This is a bug in the python script which occurs with older bash shell versions. Simply
+      use a text editor to change the following lines in the OOo-install/program/python.sh script
+      
+<table width="100%" bgcolor="lightgrey"><tr><td><font size="-1"><pre>
+export PYTHONPATH="$sd_prog":"$sd_prog/python-core/lib":"$sd_prog/python-core/lib/lib-dynload":"$PYTHONPATH"
+export PYTHONHOME="$sd_prog"/python-core
+</pre></font></td></tr></table>
+
+to
+
+<table width="100%" bgcolor="lightgrey"><tr><td><font size="-1"><pre>
+PYTHONPATH="$sd_prog":"$sd_prog/python-core/lib":"$sd_prog/python-core/lib/lib-dynload":"$PYTHONPATH"
+export PYTHONPATH
+PYTHONHOME="$sd_prog"/python-core
+export PYTHONHOME
+</pre></font></td></tr></table>
+
+. This bug is fixed with OOo 1.1.1.
+
+
+<li> <h4>I already have python installed on my system, why does the office ship another python ? </h4>
+     Python itself is shipped with OpenOffice.org, because
+     <ul>
+     <li> python must have been compiled with the same C++ compiler as the office itself on
+          all platforms that use the gcc compiler (e.g. linux, bsd, etc.).
+     <li> On most unix platforms, no python shared libraries are available by default
+          (though some distributions do so). This would have meant, that python UNO
+	  components cannot be executed within the office process.
+     <li> Python component developers need a minimal platform, which they can rely on. 
+     <li> Recognition of a python runtime at the installation system would have been an
+          extremly difficult and time consuming task as so many different python
+	  installation schemes exist.
+     </ul>
+
+<li> <h4>Can I use system's python installation ? </h4>
+     In general this is possible on unix like systems, but needs a lot of work. Have a look at
+     <a href="#replacing">this paragraph</a> to understand the basic ideas.
+     On windows, this is only possible, when you relink pyuno itself, which means that
+     you need to use the OOo build environment to do this.
+
+<li> <h4>Why crashes the office with a self written UNO component, while
+        the sample UNO component runs fine  ? </h4>
+
+     There is a known bug in the office, see 
+
+     <a href="http://www.openoffice.org/issues/show_bug.cgi?id=13377">
+     #i13377#</a>, which was not fixed for OpenOffice.org1.1.
+     The office in general crashes, when the python script lead to an unhandled exception
+     (e.g. attribute error etc.).
+
+     <p>
+     You may try to workaround this bug by adding a <code>try: except:</code> level
+     in your trigger() implementation, which dumps an error message to stdout/stderr, but
+     sadly this will not help in all cases (e.g. compilation failure for some reason :o( ).
+
+     <p> Of course, there may be other reasons for a crash, you will only know, when you
+     try to retrieve a native callstack (e.g. using the gdb).
+
+<li> <h4> Why don't work Python's xml parser (expat) and the zip module for me ?</h4>
+     These libraries don't yet get built for OOo1.1. This will change for OOo2.0. Alternatively
+     you may use OpenOffice.org's xml parser service (see service com.sun.star.xml.sax.Parser)
+     or the zip content provider
+     (see <a href="http://ucb.openoffice.org"> http://ucb.openoffice.org</a>).
+
+<li> <h4> Why do not work socket and sre module in OOo1.1. python distribution on windows ?</h4>
+     This is a known bug on windows in the OOo1.1 build. This should be fixed for OOo1.1.1
+     (see issue <a href="http://www.openoffice.org/issues/show_bug.cgi?id=21281">21281</a> ).
+     It should work for the other platforms. You can workaround this by downloading the
+     officical windows python distribution
+     (see <a href="http://www.python.org">http://www.python.org</a>) and replacing the
+     appropriate .pyd files in the OOo's python installation.
+     
+<li> <h4>The samples are running fine, but how do I get more information about the API ?</h4>
+
+     The semantics of the OpenOffice API is a very complex topic, which can't be
+     discussed in this python document. Try to gather information from other
+     resources, especially from the developer manual (see <a href="#references#">below</a>).
+<li> <h4>Most examples in the devguide are in Java. How do I translate them to python code ?</h4>
+     Most sample code you find there is written in Java. It is not so difficult to translate
+     java code to python, when you know the following differences:
+     <p>
+
+     In python you don't need <code>queryInterface</code>. E.g. Java code like
+
+<table width="100%" bgcolor="lightgrey"><tr><td><font size="-1"><pre>
+            oInterface = (XInterface) oMSF.createInstance(
+	                         "com.sun.star.frame.Desktop" );
+            oCLoader = ( XComponentLoader ) UnoRuntime.queryInterface(
+	                         XComponentLoader.class, oInterface );
+	    PropertyValue [] szEmptyArgs = new PropertyValue [0];
+	    aDoc = oCLoader.loadComponentFromURL(
+                     "private:factory/swriter" , "_blank", 0, szEmptyArgs );
+</pre></font></td></tr></table>
+
+      becomes in python simply   
+
+<table width="100%" bgcolor="lightgrey"><tr><td><font size="-1"><pre>
+            oCLoader = oMSF.createInstance( "com.sun.star.frame.Desktop" )
+	    aDoc = oCLoader.loadComponentFromURL(
+	                 "private:factory/swriter", "_blank", 0, () )
+</pre></font></td></tr></table>
+      . You don't need this intermediate oInterface variable anymore.
+      So, here python code simplifies a lot, with a little training, one
+      shouldn't have too many problems to translate java to python code.
+     
+<li> <h4>Why can't I call the print method ?</h4>
+     In python, 'print' is a very basic method for every object, which cannot
+     be overriden so easily. E.g. the below code does not work.
+
+<pre>
+     doc = desktop.loadComponentFromURL(infileurl, "_blank", 0, ())
+     doc.storeAsURL(outfileurl, ())
+     doc.print( () )
+</pre>
+     You can workaround the problem by using the <code>uno.invoke()</code>
+     function like below :
+<pre>
+     uno.invoke( doc , "print" , ( (), ) )
+</pre>
+
+<li> <h4>Why can't I do a replace on the 'NumberingRules' object ? </h4>
+
+     There are some places, where the loss in type safety leads to difficulties,
+     as e.g. bug
+     <a href="http://www.openoffice.org/issues/show_bug.cgi?id=12504">
+ http://www.openoffice.org/issues/show_bug.cgi?id=12504</a>. The problem
+     here is, that the C++ implementation within the office expects a
+     <code>sequence&lt; PropertyValue &gt;</code>, while the PyUNO runtime
+     converts it to a <code>sequence&lt; any&gt;</code>, where each <code>any</code>
+     contains a <code>PropertyValue</code>. In my eyes, this is a bug within
+     the C++ code. However, there has been added a workaround for pyuno, which the
+     scripter can use.
+     See the below sample:
+
+<table width="100%" bgcolor="lightgrey"><tr><td><font size="-1"><pre>
+import uno
+import unohelper
+
+localContext = uno.getComponentContext()
+
+resolver = localContext.ServiceManager.createInstanceWithContext(
+    "com.sun.star.bridge.UnoUrlResolver", localContext)
+ctx = resolver.resolve(
+    "uno:socket,host=localhost,port=2002;urp;StarOffice.ComponentContext")
+smgr= ctx.ServiceManager
+desktop = smgr.createInstanceWithContext("com.sun.star.frame.Desktop",ctx)
+doc = desktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, ())
+            
+style = doc.createInstance("com.sun.star.style.NumberingStyle")
+family = doc.getStyleFamilies().getByName('NumberingStyles')
+family.insertByName('List test', style)
+
+rule = style.getPropertyValue('NumberingRules')
+level = rule.getByIndex(0)
+
+# the normal call would have been:
+# rule.replaceByIndex( 0, level )
+# but this will end up in a excpetion
+# magic to pass the exact type to the callee
+uno.invoke( rule , "replaceByIndex", (0, uno.Any("[]com.sun.star.beans.PropertyValue",level)) )
+</pre></font></td></tr></table>
+
+<p>This is the only place, where the uno.Any is used. Using the uno.Any in normal
+calls will lead to RuntimeExceptions. A python uno object implementation will never
+receive an instance of uno.Any() as a incoming parameter, instead always the value within the
+is passed.
+
+<p> This solution looks really ugly, but it allows you to continue, where you otherwise
+can only give up or switch to another implementation language.
+
+
+<li> <h4>How can I activate encoding iso8859-1 for OpenOffice.org's python installation ?</h4>
+In the &lt;openoffice-install&gt;/program/python-core/lib/site.py file, you can replace the line
+
+<pre>
+encoding = "ascii" # Default value set by _PyUnicode_Init()
+</pre>
+
+with
+<pre>
+encoding = "is8859-1" # Default value set by _PyUnicode_Init()
+</pre>
+(or any other encoding you wish). However, note that this is a per installation configuration.
+It would be better to do the necessary conversions explicitly in the code.
+
+</ol>
+
 <a name="authors"><h2> Authors </h2></a>
 The UNO python bridge was initially created by <a href="mailto:ralpht@sgi.com">Ralph Thomas</a>
 and is now
