dpcs: python howto

* More updates to the docs themselves and the versions to be available
  with the next release.
* .texi and .rst copies of the HOWTO and the short history of (this
  part) of the project.

lang/python/docs/rst/short-history.rst

@@ -0,0 +1,152 @@
+Overview
+========
+
+The GPGME Python bindings passed through many hands and numerous phases
+before, after a fifteen year journey, coming full circle to return to
+the source. This is a short explanation of that journey.
+
+.. _in-the-begining:
+
+In the beginning
+----------------
+
+In 2002 John Goerzen released PyME; Python bindings for the GPGME module
+which utilised the current release of Python of the time and SWIG. [1]_
+Shortly after creating it and ensuring it worked he stopped supporting
+it, though he left his work available on his Gopher site.
+
+Keeping the flame alive
+-----------------------
+
+A couple of years later the project was picked up by Igor Belyi and
+actively developed and maintained by him from 2004 to 2008. Igor\'s
+whereabouts at the time of this document\'s creation are unknown, but
+the current authors do hope he is well. We\'re assuming (or hoping) that
+life did what life does and made continuing untenable.
+
+Passing the torch
+-----------------
+
+In 2014 Martin Albrecht wanted to patch a bug in the PyME code and
+discovered the absence of Igor. Following a discussion on the PyME
+mailing list he became the new maintainer for PyME, releasing version
+0.9.0 in May of that year. He remains the maintainer of the original
+PyME release in Python 2.6 and 2.7 (available via PyPI).
+
+.. _ouroboros:
+
+Coming full circle
+------------------
+
+In 2015 Ben McGinnes approached Martin about a Python 3 version, while
+investigating how complex a task this would be the task ended up being
+completed. A subsequent discussion with Werner Koch led to the decision
+to fold the Python 3 port back into the original GPGME release in the
+languages subdirectory for non-C bindings under the module name of
+``pyme3``.
+
+In 2016 this PyME module was integrated back into the GPGME project by
+Justus Winter. During the course of this work Justus adjusted the port
+to restore limited support for Python 2, but not as many minor point
+releases as the original PyME package supports. During the course of
+this integration the package was renamed to more accurately reflect its
+status as a component of GPGME. The ``pyme3`` module was renamed to
+``gpg`` and adopted by the upstream GnuPG team.
+
+In 2017 Justus departed G10code and the GnuPG team. Following this Ben
+returned to maintain of gpgme Python bindings and continue building them
+from that point.
+
+.. _relics-past:
+
+Relics of the past
+==================
+
+There are a few things, in addition to code specific factors, such as
+SWIG itself, which are worth noting here.
+
+The Annoyances of Git
+---------------------
+
+As anyone who has ever worked with git knows, submodules are horrible
+way to deal with pretty much anything. In the interests of avoiding
+migraines, that was skipped with addition of the PyME code to GPGME.
+
+Instead the files were added to a subdirectory of the ``lang/``
+directory, along with a copy of the entire git log up to that point as a
+separate file within the ``lang/python/docs/`` directory. [2]_ As the
+log for PyME is nearly 100KB and the log for GPGME is approximately 1MB,
+this would cause considerable bloat, as well as some confusion, should
+the two be merged.
+
+Hence the unfortunate, but necessary, step to simply move the files. A
+regular repository version has been maintained should it be possible to
+implement this better in the future.
+
+The Perils of PyPI
+------------------
+
+The early port of the Python 2 ``pyme`` module as ``pyme3`` was never
+added to PyPI while the focus remained on development and testing during
+2015 and early 2016. Later in 2016, however, when Justus completed his
+major integration work and subsequently renamed the module from
+``pyme3`` to ``gpg``, some prior releases were also provided through
+PyPI.
+
+Since these bindings require a matching release of the GPGME libraries
+in order to function, it was determined that there was little benefit in
+also providing a copy through PyPI since anyone obtaining the GPGME
+source code would obtain the Python bindings source code at the same
+time. Whereas there was the potential to sew confusion amongst Python
+users installing the module from PyPI, only to discover that without the
+relevant C files, header files or SWIG compiled binaries, the Python
+module did them little good.
+
+There are only two files on PyPI which might turn up in a search for
+this module or a sample of its content:
+
+#. gpg (1.8.0) - Python bindings for GPGME GnuPG cryptography library
+#. pyme (0.9.0) - Python support for GPGME GnuPG cryptography library
+
+.. _pypi-gpgme-180:
+
+GPG 1.8.0 - Python bindings for GPGME GnuPG cryptography library
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the most recent version to reach PyPI and is the version of the
+official Pyhon bindings which shipped with GPGME 1.8.0. If you have
+GPGME 1.8.0 installed and *only* 1.8.0 installed, then it is probably
+safe to use this copy from PyPI.
+
+As there have been a lot of changes since the release of GPGME 1.8.0,
+the GnuPG Project recommends not using this version of the module and
+instead installing the current version of GPGME along with the Python
+bindings included with that package.
+
+.. _pypi-gpgme-90:
+
+PyME 0.9.0 - Python support for GPGME GnuPG cryptography library
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the last release of the PyME bindings maintained by Martin
+Albrecht and is only compatible with Python 2, it will not work with
+Python 3. This is the version of the software from which the port from
+Python 2 to Python 3 code was made in 2015.
+
+Users of the more recent Python bindings will recognise numerous points
+of similarity, but also significant differences. It is likely that the
+more recent official bindings will feel \"more pythonic.\"
+
+For those using Python 2, there is essentially no harm in using this
+module, but it may lack a number of more recent features added to GPGME.
+
+Footnotes
+=========
+
+.. [1]
+   In all likelihood thos would have been Python 2.2 or possibly Python
+   2.3.
+
+.. [2]
+   The entire PyME git log and other preceding VCS logs are located in
+   the ``gpgme/lang/python/docs/old-commits.log`` file.

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

@@ -131,7 +131,16 @@ The bullet points of new additiions are:
 - Semi-formalised the location where [[#draft-editions][draft versions]] of this HOWTO may
   periodically be accessible.  This is both for the reference of
   others and testing the publishing of the document itself.  Renamed
-  the file at around the same time.
+  this file at around the same time.
+- The Texinfo documentation build configuration has been replicated
+  from the parent project in order to make to maintain consistency
+  with that project (and actually ship with each release).
+- a reStructuredText (=.rst=) version is also generated for Python
+  developers more used to and comfortable with that format as it is
+  the standard Python documentation format and Python developers may
+  wish to use it with Sphinx.  Please note that there has been no
+  testing of the reStructuredText version with Sphinx at all.  The
+  reST file was generated by the simple expedient of using [[https://pandoc.org/][Pandoc]].
 - Added a new section for [[#advanced-use][advanced or experimental use]].
 - Began the advanced use cases with [[#cython][a section]] on using the module with
   [[http://cython.org/][Cython]].
@@ -804,7 +813,7 @@ print("""
 """.format(secnum, pubnum))
 #+END_SRC
 
-*NOTE:* The [[#cython][Cython]] introduction in the [[#advanced-use][Advanced and Experimental]]
+NOTE: The [[#cython][Cython]] introduction in the [[#advanced-use][Advanced and Experimental]]
 section uses this same key counting code with Cython to demonstrate
 some areas where Cython can improve performance even with the
 bindings.  Users with large public keyrings or keyboxes, for instance,
@@ -911,7 +920,7 @@ else:
     pass
 #+END_SRC
 
-*NOTE:* When searching for a key ID of any length or a fingerprint
+NOTE: When searching for a key ID of any length or a fingerprint
 (without spaces), the SKS servers require the the leading =0x=
 indicative of hexadecimal be included.  Also note that the old short
 key IDs (e.g. =0xDEADBEEF=) should no longer be used due to the
@@ -2958,13 +2967,23 @@ from the author at any of the following URLs:
 - [[http://files.au.adversary.org/crypto/gpgme-python-howto.texi][GPGME Python Bindings HOWTO draft (Texinfo file AWS S3 no SSL)]]
 - [[https://files.au.adversary.org/crypto/gpgme-python-howto.info][GPGME Python Bindings HOWTO draft (Info file AWS S3 SSL)]]
 - [[http://files.au.adversary.org/crypto/gpgme-python-howto.info][GPGME Python Bindings HOWTO draft (Info file AWS S3 no SSL)]]
+- [[https://files.au.adversary.org/crypto/gpgme-python-howto.rst][GPGME Python Bindings HOWTO draft (reST file AWS S3 SSL)]]
+- [[http://files.au.adversary.org/crypto/gpgme-python-howto.rst][GPGME Python Bindings HOWTO draft (reST file AWS S3 no SSL)]]
 - [[https://files.au.adversary.org/crypto/gpgme-python-howto.xml][GPGME Python Bindings HOWTO draft (Docbook 4.2 AWS S3 SSL)]]
 - [[http://files.au.adversary.org/crypto/gpgme-python-howto.xml][GPGME Python Bindings HOWTO draft (Docbook 4.2 AWS S3 no SSL)]]
 
-All of these draft versions are generated from this document via Emacs
+All of these draft versions except for one have been generated from
-[[https://orgmode.org/][Org mode]] and [[https://www.gnu.org/software/texinfo/][GNU Texinfo]].  Though it is likely that the specific [[https://files.au.adversary.org/crypto/gpgme-python-howto.org][file]]
+this document via Emacs [[https://orgmode.org/][Org mode]] and [[https://www.gnu.org/software/texinfo/][GNU Texinfo]].  Though it is likely
-[[http://files.au.adversary.org/crypto/gpgme-python-howto.org][version]] used will be on the same server with the generated output
+that the specific [[https://files.au.adversary.org/crypto/gpgme-python-howto.org][file]] [[http://files.au.adversary.org/crypto/gpgme-python-howto.org][version]] used will be on the same server with
-formats.
+the generated output formats.
+
+The one exception is the reStructuredText version, which was converted
+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
+#+END_SRC
 
 In addition to these there is a significantly less frequently updated
 version as a HTML [[https://files.au.adversary.org/crypto/gpgme-python-howto/webhelp/index.html][WebHelp site]] (AWS S3 SSL); generated from DITA XML
@@ -2997,7 +3016,7 @@ PURPOSE.
 
 * Footnotes
 
-[fn:1] =Short_History.org= and/or =Short_History.html=.
+[fn:1] =short-history.org= and/or =short-history.html=.
 
 [fn:2] The =lang/python/docs/= directory in the GPGME source.
 

lang/python/docs/texinfo/short-history.texi

@@ -0,0 +1,209 @@
+\input texinfo    @c -*- texinfo -*-
+@c %**start of header
+@setfilename short-history.info
+@settitle A Short History of the GPGME bindings for Python
+@documentencoding UTF-8
+@documentlanguage en
+@c %**end of header
+
+@finalout
+@titlepage
+@title A Short History of the GPGME bindings for Python
+@author Ben McGinnes
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top A Short History of the GPGME bindings for Python
+@end ifnottex
+
+@menu
+* Overview::
+* Relics of the past::
+
+@detailmenu
+--- The Detailed Node Listing ---
+
+Overview
+
+* In the beginning::
+* Keeping the flame alive::
+* Passing the torch::
+* Coming full circle::
+
+Relics of the past
+
+* The Annoyances of Git::
+* The Perils of PyPI::
+
+The Perils of PyPI
+
+* GPG 1.8.0 - Python bindings for GPGME GnuPG cryptography library: GPG 180 - Python bindings for GPGME GnuPG cryptography library. 
+* PyME 0.9.0 - Python support for GPGME GnuPG cryptography library: PyME 090 - Python support for GPGME GnuPG cryptography library. 
+
+@end detailmenu
+@end menu
+
+@node Overview
+@chapter Overview
+
+The GPGME Python bindings passed through many hands and numerous
+phases before, after a fifteen year journey, coming full circle to
+return to the source.  This is a short explanation of that journey.
+
+@menu
+* In the beginning::
+* Keeping the flame alive::
+* Passing the torch::
+* Coming full circle::
+@end menu
+
+@node In the beginning
+@section In the beginning
+
+In 2002 John Goerzen released PyME; Python bindings for the GPGME
+module which utilised the current release of Python of the time and
+SWIG.@footnote{In all likelihood thos would have been Python 2.2 or possibly
+Python 2.3.}  Shortly after creating it and ensuring it worked he stopped
+supporting it, though he left his work available on his Gopher
+site.
+
+@node Keeping the flame alive
+@section Keeping the flame alive
+
+A couple of years later the project was picked up by Igor Belyi and
+actively developed and maintained by him from 2004 to 2008.  Igor's
+whereabouts at the time of this document's creation are unknown,
+but the current authors do hope he is well.  We're assuming (or
+hoping) that life did what life does and made continuing untenable.
+
+@node Passing the torch
+@section Passing the torch
+
+In 2014 Martin Albrecht wanted to patch a bug in the PyME code and
+discovered the absence of Igor.  Following a discussion on the PyME
+mailing list he became the new maintainer for PyME, releasing
+version 0.9.0 in May of that year.  He remains the maintainer of
+the original PyME release in Python 2.6 and 2.7 (available via
+PyPI).
+
+@node Coming full circle
+@section Coming full circle
+
+In 2015 Ben McGinnes approached Martin about a Python 3 version,
+while investigating how complex a task this would be the task ended
+up being completed.  A subsequent discussion with Werner Koch led
+to the decision to fold the Python 3 port back into the original
+GPGME release in the languages subdirectory for non-C bindings
+under the module name of @samp{pyme3}.
+
+In 2016 this PyME module was integrated back into the GPGME project
+by Justus Winter.  During the course of this work Justus adjusted
+the port to restore limited support for Python 2, but not as many
+minor point releases as the original PyME package supports.  During
+the course of this integration the package was renamed to more
+accurately reflect its status as a component of GPGME.  The @samp{pyme3}
+module was renamed to @samp{gpg} and adopted by the upstream GnuPG team.
+
+In 2017 Justus departed G10code and the GnuPG team.  Following this
+Ben returned to maintain of gpgme Python bindings and continue
+building them from that point.
+
+@node Relics of the past
+@chapter Relics of the past
+
+There are a few things, in addition to code specific factors, such as
+SWIG itself, which are worth noting here.
+
+@menu
+* The Annoyances of Git::
+* The Perils of PyPI::
+@end menu
+
+@node The Annoyances of Git
+@section The Annoyances of Git
+
+As anyone who has ever worked with git knows, submodules are
+horrible way to deal with pretty much anything.  In the interests
+of avoiding migraines, that was skipped with addition of the PyME
+code to GPGME.
+
+Instead the files were added to a subdirectory of the @samp{lang/}
+directory, along with a copy of the entire git log up to that point
+as a separate file within the @samp{lang/python/docs/} directory.@footnote{The entire PyME git log and other preceding VCS logs are
+located in the @samp{gpgme/lang/python/docs/old-commits.log} file.}
+As the log for PyME is nearly 100KB and the log for GPGME is
+approximately 1MB, this would cause considerable bloat, as well as
+some confusion, should the two be merged.
+
+Hence the unfortunate, but necessary, step to simply move the
+files.  A regular repository version has been maintained should it
+be possible to implement this better in the future.
+
+@node The Perils of PyPI
+@section The Perils of PyPI
+
+The early port of the Python 2 @samp{pyme} module as @samp{pyme3} was never
+added to PyPI while the focus remained on development and testing
+during 2015 and early 2016.  Later in 2016, however, when Justus
+completed his major integration work and subsequently renamed the
+module from @samp{pyme3} to @samp{gpg}, some prior releases were also
+provided through PyPI.
+
+Since these bindings require a matching release of the GPGME
+libraries in order to function, it was determined that there was
+little benefit in also providing a copy through PyPI since anyone
+obtaining the GPGME source code would obtain the Python bindings
+source code at the same time.  Whereas there was the potential to
+sew confusion amongst Python users installing the module from PyPI,
+only to discover that without the relevant C files, header files or
+SWIG compiled binaries, the Python module did them little good.
+
+There are only two files on PyPI which might turn up in a search
+for this module or a sample of its content:
+
+@enumerate
+@item
+gpg (1.8.0) - Python bindings for GPGME GnuPG cryptography library
+@item
+pyme (0.9.0) - Python support for GPGME GnuPG cryptography library
+@end enumerate
+
+@menu
+* GPG 1.8.0 - Python bindings for GPGME GnuPG cryptography library: GPG 180 - Python bindings for GPGME GnuPG cryptography library. 
+* PyME 0.9.0 - Python support for GPGME GnuPG cryptography library: PyME 090 - Python support for GPGME GnuPG cryptography library. 
+@end menu
+
+@node GPG 180 - Python bindings for GPGME GnuPG cryptography library
+@subsection GPG 1.8.0 - Python bindings for GPGME GnuPG cryptography library
+
+This is the most recent version to reach PyPI and is the version
+of the official Pyhon bindings which shipped with GPGME 1.8.0.  If
+you have GPGME 1.8.0 installed and @emph{only} 1.8.0 installed, then it
+is probably safe to use this copy from PyPI.
+
+As there have been a lot of changes since the release of GPGME
+1.8.0, the GnuPG Project recommends not using this version of the
+module and instead installing the current version of GPGME along
+with the Python bindings included with that package.
+
+@node PyME 090 - Python support for GPGME GnuPG cryptography library
+@subsection PyME 0.9.0 - Python support for GPGME GnuPG cryptography library
+
+This is the last release of the PyME bindings maintained by Martin
+Albrecht and is only compatible with Python 2, it will not work
+with Python 3.  This is the version of the software from which the
+port from Python 2 to Python 3 code was made in 2015.
+
+Users of the more recent Python bindings will recognise numerous
+points of similarity, but also significant differences.  It is
+likely that the more recent official bindings will feel "more
+pythonic."
+
+For those using Python 2, there is essentially no harm in using
+this module, but it may lack a number of more recent features
+added to GPGME.
+
+@bye