PLD-Guide python.xml,1.18,1.19

[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.19
date: 2002/07/30 14:23:46;  author: wrobell;  state: Exp;  lines: +58 -31
- more info about pyrequires_eq macro
- descriptions of py_*comp macros and pyrequires_eq macros go into
  subsections
 

Index: python.xml
===================================================================
RCS file: /cvsroot/LDP/guide/docbook/PLD-Guide/devel/python.xml,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -d -r1.18 -r1.19
--- python.xml	30 Jul 2002 13:55:26 -0000	1.18
+++ python.xml	30 Jul 2002 14:23:46 -0000	1.19
@@ -377,40 +377,67 @@
         <para>
             Most of above macros are self explanatory... and some not, so read on. :-)
         </para>
-        <para>
-            Macros <literal role="rpm.macro">py_comp</literal>
-            and <literal role="rpm.macro">py_ocomp</literal> should be used when
-            software installation routine does
-            not provide byte compiled modules installation.
-        </para>
-        <para>
-            The macros use Python <literal role="lib">compileall</literal>
-            module which scans given directory and its subdirectories for Python modules and compiles
-            them into bytecode.
-            <example>
-                <title>
-                    Compiling Python modules into bytecode.
-                </title>
-                <screen>%install
+        <section id='python.macros.comp'>
+            <para>
+                Macros <literal role="rpm.macro">py_comp</literal>
+                and <literal role="rpm.macro">py_ocomp</literal> should be used when
+                software installation routine does
+                not provide byte compiled modules installation.
+            </para>
+            <para>
+                The macros use Python <literal role="lib">compileall</literal>
+                module which scans given directory and its subdirectories for Python modules and compiles
+                them into bytecode.
+                <example>
+                    <title>
+                        Compiling Python modules into bytecode.
+                    </title>
+                    <screen>%install
 ...
 %py_comp $RPM_BUILD_ROOT%{py_sitedir}
 %py_ocomp $RPM_BUILD_ROOT%{py_sitedir}</screen>
+                </example>
+                Please note, that compilation must be performed after module source files installation, because
+                the directory path, where the sources reside, is put into binary files
+                during byte compilation.
+                Information about correct directory path in compiled modules is useful, due to
+                thrown exceptions which display it.
+                <!-- todo: example of thrown exception -->
+            </para>
+        </section>
+        <section id='python.macros.pyrequires_eq'>
+            <para>
+                Macro <literal role='rpm.macro'>pyrequires_eq</literal> is
+                very useful for packages which require software distributed
+                with Python language.
+            </para>
+            <para>
+                It creates dependency on specified package with main
+                version unchanged. For example, when you want
+                dependency on <literal role='rpm.package'>python-libs</literal> package and use this
+                macro, then created package will require
+                <literal role='rpm.package'>python-libs</literal> with
+                version greater or equal to 2.2 and less then 2.3 (when
+                Python 2.2.x is installed, of course).
+            </para>
+            <example>
+                <title>
+                    Using <literal role='rpm.macro'>pyrequires_eq</literal>
+                    macro.
+                </title>
+                <screen>...
+URL:              http://daa.com.au/~james/pygtk
+%pyrequires_eq    python-modules
+BuildRequires:    libglade2-devel >= 2.0.0
+...</screen>
             </example>
-            Please note, that compilation must be performed after module source files installation, because
-            the directory path, where the sources reside, is put into binary files
-            during byte compilation.
-            Information about correct directory path in compiled modules is useful, due to
-            thrown exceptions which display it.
-        </para>
-        <!-- para>
-            more info about: py_?comp and pyrequires_eq macros
-            For example, when you want
-            dependency on python-libs package and use this
-            macro, then created package will require
-            python-libs with version greater or equal to 2.2 and less
-            then 2.3.
-
-            This macro is very usefull, because 
-        </para -->
+            <para>
+                The macro is very useful, because new minor Python
+                language versions do not (or should not) introduce
+                any incompatible modifications such as library API.
+                Such way, it is easy to upgrade distribution software
+                without unnecessary recompilation of several modules.
+            </para>
+        </section>
     </section>
 </section>