PLD-Guide python.xml,1.20,1.21

[Artur Wróblewski]

Module name:    PLD-Guide
Changes by:     wrobell

Changed RCS file: /cvsroot/LDP/guide/docbook/PLD-Guide/devel/python.xml,v
----------------------------
revision 1.21
date: 2002/12/23 21:33:08;  author: wrobell;  state: Exp;  lines: +27 -19
- .pyc files are no longer required to use .pyo module files (the
  requirement was due to bug in Python and is fixed now, as I know);
  some new thoughts about .pyc and .pyo files distribution...
- missing titles for some macros section
 

Index: python.xml
===================================================================
RCS file: /cvsroot/LDP/guide/docbook/PLD-Guide/devel/python.xml,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -d -r1.20 -r1.21
--- python.xml	10 Sep 2002 07:57:20 -0000	1.20
+++ python.xml	23 Dec 2002 21:33:08 -0000	1.21
@@ -10,9 +10,9 @@
     <section id='python.dist'>
         <title>What is distributed?</title>
         <para>
-            There is no doubt when you create package with Python modules
+            There is no doubt when you create package with Python modules,
             which sources are written in C language. Sources should be
-            compiled for given architecture, that's all. The problem arises
+            compiled for given architecture, that&apos;s all. The problem arises
             when modules are written in Python language. What should be
             distributed? Sources - *.py files? Byte compiled files - *.pyc?
             Optimized byte compiled files - *.pyo? All of them?
@@ -20,26 +20,24 @@
         <para>
             We have decided that packages with Python modules
             should contain both, byte compiled and optimized byte compiled
-            files. Yes, *.pyc and *.pyo files. PLD developers aim to 
-            provide optimized software whenever it is possible.
-        </para>
-        <para>
-            Why not to distribute only *.py files and byte compile them during
-            package installation? We want to distribute prepared packages
-            so user is not forced to compile the sources and such
-            philosophy applies to Python, too.
-        </para>
+            files. Yes, *.pyc and *.pyo files. 
+            Python interpreter cannot switch between .pyc and .pyo
+            files on runtime currently and it seems that it will never
+            be (please, read history of Python bug #570640:
+            http://sourceforge.net/tracker/index.php?func=detail&amp;aid=570640&amp;group_id=5470&amp;atid=105470).
+        </para> 
         <para>
-            Why not only *.pyo files? Firstly, optimized byte compiled modules
-            cannot be imported without *.pyc files.<!-- why cannot python
-            do it? - explanation should be here -->
-            Secondly, *.pyo do not contain docstrings - source code
-            documentation.
+            We could force lub forbid the usage of optimized byte compiled
+            modules, but it is not practical due to possible binary only
+            packages from other vendors. The vendors can provide one of the
+            types of compiled modules, so we would create the big
+            inconvenience for PLD users and administrators.
         </para>
         <para>
-            Why not only *.pyc files? As it is mentioned above, PLD
-            developers do not want to deprive users of optimized software.
-            We want to provide fully optimized Python modules
+            Why not to distribute only *.py files?
+            PLD developers aim to 
+            provide optimized software whenever it is possible.
+            We want to provide fully optimized Python modules too
             as we provide packages
             optimized for many architectures. It would be not a good idea if
             users, who want to use optimized modules, have been forced
@@ -47,6 +45,14 @@
             and creates files which are in <filename>/usr</filename> hierarchy
             and not in <application>RPM</application> database.
         </para>
+        <para>
+            Distributing sources and byte compile them during package
+            installation (to avoid manual pain) is not an option, too.  It
+            is because of general idea, which says that we distribute
+            prepared, binary packages so user is not forced to compile the
+            sources. Such philosophy applies also to Python language, which
+            should be not an exception.
+        </para>
     </section>
     <section id='python.lang'>
         <title>Python Language</title>
@@ -378,6 +384,7 @@
             Most of above macros are self explanatory... and some not, so read on. :-)
         </para>
         <section id='python.macros.comp'>
+            <title>Modules Compilation Macros</title>
             <para>
                 Macros <literal role="rpm.macro">py_comp</literal>
                 and <literal role="rpm.macro">py_ocomp</literal> should be used when
@@ -406,6 +413,7 @@
             </para>
         </section>
         <section id='python.macros.pyrequires_eq'>
+            <title>Requirements of Python Packages Macros</title>
             <para>
                 Macro <literal role='rpm.macro'>pyrequires_eq</literal> is
                 very useful for packages which require software distributed