--- a/src/doc/user/usermanual.xml
+++ b/src/doc/user/usermanual.xml
@@ -4354,23 +4354,27 @@
         <title>Introduction</title>
 
         <para>&RCL; versions after 1.11 define a Python programming
-          interface, both for searching and indexing. The indexing
-          portion has seen little use, but the searching one is used
-          in the Recoll Ubuntu Unity Lens and Recoll Web UI.</para> 
-
-        <para>The API is inspired by the Python database API
-          specification. There were two major changes in recent &RCL;
-          versions:
-          <itemizedlist>
-            <listitem>The basis for the &RCL; API changed from Python
-              database API version 1.0 (&RCL; versions up to 1.18.1),
-              to version 2.0 (&RCL; 1.18.2 and later).</listitem>
-            <listitem>The <literal>recoll</literal> module became a
-              package (with an internal <literal>recoll</literal>
-              module) as of &RCL; version 1.19, in order to add more
-              functions. For existing code, this only changes the way
-              the interface must be imported.</listitem>
-          </itemizedlist>
+        interface, both for searching and indexing.</para>
+
+        <para>The search interface is used in the Recoll Ubuntu Unity Lens
+        and Recoll WebUI.</para>
+
+        <para>The indexing section of the API has seen little use, and is
+        more a proof of concept. In truth it is waiting for its killer
+        app...</para>
+        
+        <para>The search API is modeled along the Python database API
+        specification. There were two major changes along &RCL; versions:
+        <itemizedlist>
+          <listitem><para>The basis for the &RCL; API changed from Python
+          database API version 1.0 (&RCL; versions up to 1.18.1),
+          to version 2.0 (&RCL; 1.18.2 and later).</para></listitem>
+          <listitem><para>The <literal>recoll</literal> module became a
+          package (with an internal <literal>recoll</literal>
+          module) as of &RCL; version 1.19, in order to add more
+          functions. For existing code, this only changes the way
+          the interface must be imported.</para></listitem>
+        </itemizedlist>
         </para>
 
         <para>We will mostly describe the new API and package
@@ -4392,13 +4396,33 @@
           </screen>
         </para> 
 
-        <para>The normal &RCL; installer installs the Python
-          API along with the main code.</para>
+        <para>As of &RCL; 1.19, the module can be compiled for
+        Python3.</para>
+
+        <para>The normal &RCL; installer installs the Python2
+          API along with the main code. The Python3 version must be
+        explicitely built and installed.</para>
 
         <para>When installing from a repository, and depending on the
-          distribution, the Python API can sometimes be found in a
-          separate package.</para>
-
+        distribution, the Python API can sometimes be found in a
+        separate package.</para>
+
+        <para>The following small sample will run a query and list
+        the title and url for each of the results. It would work with &RCL;
+        1.19 and later. The <filename>python/samples</filename> source directory
+        contains several examples of Python programming with &RCL;,
+        exercising the extension more completely, and especially its data
+        extraction features.</para>
+        <programlisting>
+          from recoll import recoll
+
+          db = recoll.connect()
+          query = db.query()
+          nres = query.execute("some query")
+          results = query.fetchmany(20)
+          for doc in results:
+              print(doc.url, doc.title)
+        </programlisting>
       </sect3>
 
       <sect3 id="RCL.PROGRAM.PYTHON.PACKAGE">
@@ -4460,7 +4484,6 @@
             a <literal>connect()</literal> call and holds a 
             connection to a Recoll index.</para>
           <variablelist>
-            <title>Methods</title>
             <varlistentry>
               <term>Db.close()</term>
               <listitem>Closes the connection. You can't do anything
@@ -4511,7 +4534,6 @@
             execute index searches.</para>
 
           <variablelist>
-            <title>Methods</title>
 
             <varlistentry>
               <term>Query.sortby(fieldname, ascending=True)</term>
@@ -4659,7 +4681,6 @@
             module for accessing document contents.</para> 
 
           <variablelist>
-            <title>Methods</title>
 
             <varlistentry>
               <term>get(key), [] operator</term>
@@ -4694,7 +4715,6 @@
             for now...</para>
 
           <variablelist>
-            <title>Methods</title>
 
             <varlistentry>
               <term>addclause(type='and'|'or'|'excl'|'phrase'|'near'|'sub',
@@ -4729,7 +4749,6 @@
             <title>The Extractor class</title>
 
             <variablelist>
-              <title>Methods</title>
 
               <varlistentry>
                 <term>Extractor(doc)</term>