Python: docs tweaks

* Fixed a minor error in how the reST version of the HOWTO is
  generated.
* Updated the help() in __init__.py with a little more detail as to
  why not to use the lower level functions.

lang/python/doc/src/gpgme-python-howto.org

@@ -2980,7 +2980,7 @@ using the latest version of Pandoc from the Org mode source file using
 the following command:
 
 #+BEGIN_SRC shell
-  pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto.org
+  pandoc -f org -t rst -o gpgme-python-howto.rst gpgme-python-howto.org
 #+END_SRC
 
 In addition to these there is a significantly less frequently updated

lang/python/src/__init__.py

@@ -55,10 +55,10 @@ GENERAL OVERVIEW
 For those of you familiar with GPGME, you will be right at home here.
 
 The python gpg module is, for the most part, a direct interface to the C GPGME
-library.  However, it is re-packaged in a more Pythonic way --
+library.  However, it is re-packaged in a more Pythonic way -- object-oriented
-object-oriented with classes and modules.  Take a look at the classes
+with classes and modules.  Take a look at the classes defined here -- they
-defined here -- they correspond directly to certain object types in GPGME
+correspond directly to certain object types in GPGME for C.  For instance, the
-for C.  For instance, the following C code:
+following C code:
 
 gpgme_ctx_t context;
 gpgme_new(&context);
@@ -71,26 +71,50 @@ context = core.Context()
 ...
 context.op_encrypt(recp, 1, plain, cipher)
 
-The Python module automatically does error-checking and raises Python
+The Python module automatically does error-checking and raises Python exception
-exception gpg.errors.GPGMEError when GPGME signals an error. getcode()
+gpg.errors.GPGMEError when GPGME signals an error. getcode() and getsource() of
-and getsource() of this exception return code and source of the error.
+this exception return code and source of the error.
 
 IMPORTANT NOTE
 --------------
-This documentation only covers a small subset of available GPGME functions and
-methods.  Please consult the documentation for the C library
-for comprehensive coverage.
 
-This library uses Python's reflection to automatically detect the methods
+This documentation only covers a small subset of available GPGME functions and
-that are available for each class, and as such, most of those methods
+methods.  Please consult the documentation for the C library for comprehensive
-do not appear explicitly anywhere. You can use dir() python built-in command
+coverage.
-on an object to see what methods and fields it has but their meaning can
+
-be found only in GPGME documentation.
+This library uses Python's reflection to automatically detect the methods that
+are available for each class, and as such, most of those methods do not appear
+explicitly anywhere. You can use dir() python built-in command on an object to
+see what methods and fields it has but their meaning can often only be found in
+the GPGME documentation.
+
+HIGHER LEVEL PYTHONIC LAYER
+---------------------------
+
+A more pythonic or intuitive layer is being added above the automatically
+generated lower level bindings.  This is the recommended way to access the
+module as if it is ever necessary to modify the underlying GPGME API, the
+higher level methods will remain the same.
+
+The quick example above is an example of this higher layer in action, whereas
+the second example demonstrating the mapping to GPGME itself is the lower
+layer.  The second example in the higher layer would be more like the encrypt
+line in the quick example.
 
 FOR MORE INFORMATION
 --------------------
+
 GnuPG homepage: https://www.gnupg.org/
 GPGME documentation: https://www.gnupg.org/documentation/manuals/gpgme/
+GPGME Python HOWTO: http://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html
+
+To view this documentation, run help(gpg) in Python or one of the following
+commands outside of Python:
+
+        pydoc gpg
+        pydoc3 gpg
+        python -m pydoc gpg
+        python3 -m pydoc gpg
 
 """