python: documentation

* Added long description to setup.py.in.
* Added maintenance mode details with clarification for what type of
  things would be a bug as far as MM is concerned and what wouldn't
  be.
** Includes a not too subtle hint directed towards the donations page.
* Miscellaneous tightening of documentation.

Signed-off-by: Ben McGinnes <[email protected]>

6 files changed, 141 insertions, 24 deletions

diff --git a/lang/python/doc/src/gpgme-python-howto b/lang/python/doc/src/gpgme-python-howto
index 4b02a933..fe1fc2b4 100644
--- a/lang/python/doc/src/gpgme-python-howto
+++ b/lang/python/doc/src/gpgme-python-howto
@@ -17,10 +17,11 @@
 
 | Version:        | 0.1.4                                    |
 | GPGME Version:  | 1.12.1                                   |
-| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[email protected]>             |
-| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
+| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:[email protected]][[email protected]]]>             |
+| Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] |
 | Language:       | Australian English, British English      |
 | Language codes: | en-AU, en-GB, en                         |
+#+TBLFM: 
 
 This document provides basic instruction in how to use the GPGME
 Python bindings to programmatically leverage the GPGME library.
@@ -2716,6 +2717,7 @@ Though neither requests nor pendulum are required modules for using
 the GPGME Python bindings, they are both highly recommended more
 generally.
 
+
 * Advanced or Experimental Use Cases
   :PROPERTIES:
   :CUSTOM_ID: advanced-use
@@ -3083,23 +3085,31 @@ Copyright (C) The GnuPG Project, 2018.
 Draft editions of this HOWTO may be periodically available directly
 from the author at any of the following URLs:
 
-- [[https://files.au.adversary.org/crypto/gpgme-python-howto.html][GPGME Python Bindings HOWTO draft (XHTML AWS S3 SSL)]]
-- [[http://files.au.adversary.org/crypto/gpgme-python-howto.html][GPGME Python Bindings HOWTO draft (XHTML AWS S3 no SSL)]]
-- [[https://files.au.adversary.org/crypto/gpgme-python-howto.texi][GPGME Python Bindings HOWTO draft (Texinfo file AWS S3 SSL)]]
-- [[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.html][GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 SSL)]]
+- [[http://files.au.adversary.org/crypto/gpgme-python-howto.html][GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no SS)]]
+- [[https://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html][GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 SSL)]]
+- [[http://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html][GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 no SSL)]]
 
 All of these draft versions except for one have been generated from
-this document via Emacs [[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][file]] [[http://files.au.adversary.org/crypto/gpgme-python-howto.org][version]] used will be on the same server with
-the generated output formats.
+this document via GNU Emacs [[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][file]] [[http://files.au.adversary.org/crypto/gpgme-python-howto.org][version]] used will be on the same server
+with the generated output formats.
+
+The GNU Texinfo and reStructured Text versions ship with the software,
+while the GNU Emacs Info verseion is generated from the Texinfo
+version using GNU Texinfo or GNU Makeinfo.  The Texinfo format is
+generated from the original Org mode source file in Org mode itself
+either within GNU Emacs or via the command line by invoking Emacs in
+batch mode:
+
+#+BEGIN_SRC shell
+  emacs gpgme-python-howto.org --batch -f org-texinfo-export-to-texinfo --kill
+  emacs gpgme-python-howto --batch -f org-texinfo-export-to-texinfo --kill
+#+END_SRC
 
-The one exception is the reStructuredText version, which was converted
-using the latest version of Pandoc from the Org mode source file using
-either of the following two commands:
+The reStructuredText format is also generated from the Org-mode source
+file, except it is generated using [[https://pandoc.org][Pandoc]] with either of the following
+commands:
 
 #+BEGIN_SRC shell
   pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto.org
diff --git a/lang/python/doc/src/index b/lang/python/doc/src/index
index ce347ea7..ec13c9a1 100644
--- a/lang/python/doc/src/index
+++ b/lang/python/doc/src/index
@@ -24,5 +24,6 @@
 
 - [[file:short-history][A short history of the project]]
 - [[file:what-is-new][What's New]]
+  - [[file:maintenance-mode][Maintenance Mode]] (from January, 2019)
 - [[file:what-was-new][What Was New]]
 - [[file:gpgme-python-howto][GPGME Python Bindings HOWTO]]
diff --git a/lang/python/doc/src/maintenance-mode b/lang/python/doc/src/maintenance-mode
new file mode 100644
index 00000000..ef56e4e6
--- /dev/null
+++ b/lang/python/doc/src/maintenance-mode
@@ -0,0 +1,93 @@
+# -*- mode: org -*-
+#+TITLE: Maintenance Mode
+#+AUTHOR: Ben McGinnes
+#+LATEX_COMPILER: xelatex
+#+LATEX_CLASS: article
+#+LATEX_CLASS_OPTIONS: [12pt]
+#+LATEX_HEADER: \usepackage{xltxtra}
+#+LATEX_HEADER: \usepackage[margin=1in]{geometry}
+#+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Times New Roman}
+#+LATEX_HEADER: \author{Ben McGinnes <[email protected]>}
+
+
+* Maintenance Mode from 2019
+  :PROPERTIES:
+  :CUSTOM_ID: maintenance-mode
+  :END:
+
+| Version:        | 0.0.1-draft                              |
+| GPGME Version:  | 1.13.0                                   |
+| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:[email protected]][[email protected]]]>             |
+| Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] |
+| Language:       | Australian English, British English      |
+| xml:lang:       | en-AU, en-GB, en                         |
+
+From the beginning of 2019 the Python bindings to GPGME will enter
+maintenance mode, meaning that new features will not be added and only
+bug fixes and security fixes will be made.  This also means that
+documentation beyond that existing at the end of 2018 will not be
+developed further except to correct errors.
+
+Though use of these bindings appears to have been quite well received,
+there has been no indication of what demand there is, if any for
+either financial backing of the current Python bindings development or
+support contracts with g10code GmbH citing the necessity of including
+the bindings.
+
+
+** Maintainer from 2019 onward
+   :PROPERTIES:
+   :CUSTOM_ID: maintenance-mode-bm
+   :END:
+
+How does this affect the position of GnuPG Python Bindings Maintainer?
+
+Well, I will remain as maintainer of the bindings; but without funding
+for that position, the amount of time I will be able to dedicate
+solely to this task will be limited and reduced to volunteered time.
+As with all volunteered time and effort in free software projects,
+this will be subject to numerous external imperatives.
+
+
+** Using the Python Bindings from 2019 and beyond
+   :PROPERTIES:
+   :CUSTOM_ID: maintenance-mode-blade-runner
+   :END:
+
+For most, if not all, Python developers using these bindings; they
+will continue to “just work” the same as they always have.  Expansions
+of GPGME itself are usually handled by SWIG with the existing code and
+thus bindings are generated properly when the bindings are installed
+alongside GPGME and when the latter is built from source.
+
+In the rare circumstances where that is not enough to address some new
+addition to GPGME, then that is a bug and thus subject to the
+maintenance mode provisions (i.e. it will be fixed following a bug
+report being raised and your humble author will need to remember where
+the timesheet template was filed, depending on how many years off such
+an event is).
+
+All the GPGME functionality will continue to be accessible via the
+lower level, dynamically generated methods which match the GPGME C
+documentation.  While the more intuitively Pythonic higher level layer
+already covers the vast majority of functionality people require with
+key generation, signatures, certifications (key signing), encryption,
+decryption, verification, validation, trust levels and so on.
+
+Any wanted features lacking in the Python bindings are usually lacking
+because they are missing from GPGME itself (e.g. revoking keys via the
+API) and in such cases they are usually deliberately excluded.  More 
+
+Any features existing in the dynamically generated layer for which
+people want a specific, higher level function included to make it more
+Pythonic (e.g. to avoid needing to learn or memorise cryptographic
+mode values or GnuPG status code numbers), would be a feature request
+and /not/ a bug.
+
+It is still worthwhile requesting it, but the addition of such a
+feature would not be guaranteed and provided on a purely volunteer
+basis.  Expediting such a request would require funding that request.
+
+Those with a commercial interest in expediting such a feature request
+already know how to [[https://gnupg.org/cgi-bin/procdonate.cgi?mode=preset][expedite it]] (use the message field to state what
+feature is being requested).
diff --git a/lang/python/doc/src/short-history b/lang/python/doc/src/short-history
index 6c5c96ec..c91f0298 100644
--- a/lang/python/doc/src/short-history
+++ b/lang/python/doc/src/short-history
@@ -5,13 +5,20 @@
 #+LATEX_CLASS_OPTIONS: [12pt]
 #+LATEX_HEADER: \usepackage{xltxtra}
 #+LATEX_HEADER: \usepackage[margin=1in]{geometry}
-#+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Latin Modern Roman}
+#+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Times New Roman}
 
 * Overview
   :PROPERTIES:
   :CUSTOM_ID: overview
   :END:
 
+| Version:        | 0.0.1-draft                              |
+| GPGME Version:  | 1.13.0                                   |
+| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:[email protected]][[email protected]]]>             |
+| Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] |
+| Language:       | Australian English, British English      |
+| xml:lang:       | en-AU, en-GB, en                         |
+
 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.
@@ -27,6 +34,7 @@ return to the source.  This is a short explanation of that journey.
    supporting it, though he left his work available on his Gopher
    site.
 
+
 ** Keeping the flame alive
    :PROPERTIES:
    :CUSTOM_ID: keeping-the-flame-alive
@@ -38,6 +46,7 @@ return to the source.  This is a short explanation of that journey.
    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
    :PROPERTIES:
    :CUSTOM_ID: passing-the-torch
@@ -50,6 +59,7 @@ return to the source.  This is a short explanation of that journey.
    the original PyME release in Python 2.6 and 2.7 (available via
    PyPI).
 
+
 ** Coming full circle
    :PROPERTIES:
    :CUSTOM_ID: ouroboros
@@ -74,6 +84,7 @@ return to the source.  This is a short explanation of that journey.
    Ben returned to maintain of gpgme Python bindings and continue
    building them from that point.
 
+
 * Relics of the past
   :PROPERTIES:
   :CUSTOM_ID: relics-past
@@ -103,6 +114,7 @@ SWIG itself, which are worth noting here.
    files.  A regular repository version has been maintained should it
    be possible to implement this better in the future.
 
+
 ** The Perils of PyPI
    :PROPERTIES:
    :CUSTOM_ID: the-perils-of-pypi
@@ -145,6 +157,7 @@ SWIG itself, which are worth noting here.
     module and instead installing the current version of GPGME along
     with the Python bindings included with that package.
 
+
 *** PyME 0·9·0 - Python support for GPGME GnuPG cryptography library
     :PROPERTIES:
     :CUSTOM_ID: pypi-gpgme-90
@@ -164,6 +177,7 @@ SWIG itself, which are worth noting here.
     this module, but it may lack a number of more recent features
     added to GPGME.
 
+
 * Footnotes
 
 [fn:1] In all likelihood this would have been Python 2.2 or possibly
diff --git a/lang/python/doc/src/what-is-new b/lang/python/doc/src/what-is-new
index 5bcb5aeb..ab94e3ed 100644
--- a/lang/python/doc/src/what-is-new
+++ b/lang/python/doc/src/what-is-new
@@ -17,15 +17,13 @@
 
 | Version:        | 0.0.1-draft                              |
 | GPGME Version:  | 1.13.0                                   |
-| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[email protected]>             |
-| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
+| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:[email protected]][[email protected]]]>             |
+| Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] |
 | Language:       | Australian English, British English      |
 | xml:lang:       | en-AU, en-GB, en                         |
 
 Last time the most obviously new thing was adding the /What's New/
-section to the HOWTO.  Now it's moving it out of the HOWTO.  Not to
-mention expanding on the documentation both generally and
-considerably.
+section to the HOWTO.  Now it's moving it out of the HOWTO.
 
 
 ** New in GPGME 1·13·0
@@ -42,3 +40,4 @@ Additions since GPGME 1.12.0 include:
 - Added =gpg.version.versionintlist= to make it easier for Python
   developers to check for a specific version number, even with beta
   versions (it will drop the "-betaN" part).
+- Bindings enter [[file:maintenance-mode][maintenance mode]] from January, 2019.
diff --git a/lang/python/doc/src/what-was-new b/lang/python/doc/src/what-was-new
index 7c851b1e..1d3494cb 100644
--- a/lang/python/doc/src/what-was-new
+++ b/lang/python/doc/src/what-was-new
@@ -17,8 +17,8 @@
 
 | Version:        | 0.0.1-draft                              |
 | GPGME Version:  | 1.13.0                                   |
-| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[email protected]>             |
-| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
+| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:[email protected]][[email protected]]]>             |
+| Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] |
 | Language:       | Australian English, British English      |
 | xml:lang:       | en-AU, en-GB, en                         |