python: documentation
authorBen McGinnes <ben@adversary.org>
Fri, 30 Nov 2018 20:45:50 +0000 (07:45 +1100)
committerBen McGinnes <ben@adversary.org>
Fri, 30 Nov 2018 20:45:50 +0000 (07:45 +1100)
* 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 <ben@adversary.org>
19 files changed:
lang/python/doc/rst/gpgme-python-howto.rst
lang/python/doc/rst/index.rst
lang/python/doc/rst/maintenance-mode.rst [new file with mode: 0644]
lang/python/doc/rst/short-history.rst
lang/python/doc/rst/what-is-new.rst
lang/python/doc/rst/what-was-new.rst
lang/python/doc/src/gpgme-python-howto
lang/python/doc/src/index
lang/python/doc/src/maintenance-mode [new file with mode: 0644]
lang/python/doc/src/short-history
lang/python/doc/src/what-is-new
lang/python/doc/src/what-was-new
lang/python/doc/texinfo/gpgme-python-howto.texi
lang/python/doc/texinfo/index.texi
lang/python/doc/texinfo/maintenance-mode.texi [new file with mode: 0644]
lang/python/doc/texinfo/short-history.texi
lang/python/doc/texinfo/what-is-new.texi
lang/python/doc/texinfo/what-was-new.texi
lang/python/setup.py.in

index dae4c64..d1cb3fd 100644 (file)
@@ -13,8 +13,11 @@ Introduction
 |                                   | e/index.html#sec-1-5>`__          |
 |                                   | <ben@gnupg.org>                   |
 +-----------------------------------+-----------------------------------+
-| Author GPG Key:                   | DB4724E6FA4286C92B4E55C4321E4E237 |
-|                                   | 3590E5D                           |
+| Author GPG Key:                   | `DB4724E6FA4286C92B4E55C4321E4E23 |
+|                                   | 73590E5D <https://hkps.pool.sks-k |
+|                                   | eyservers.net/pks/lookup?search=0 |
+|                                   | xDB4724E6FA4286C92B4E55C4321E4E23 |
+|                                   | 73590E5D&exact=on&op=get>`__      |
 +-----------------------------------+-----------------------------------+
 | Language:                         | Australian English, British       |
 |                                   | English                           |
@@ -3009,34 +3012,37 @@ Draft Editions of this HOWTO
 Draft editions of this HOWTO may be periodically available directly from
 the author at any of the following URLs:
 
--  `GPGME Python Bindings HOWTO draft (XHTML AWS S3
+-  `GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3
    SSL) <https://files.au.adversary.org/crypto/gpgme-python-howto.html>`__
--  `GPGME Python Bindings HOWTO draft (XHTML AWS S3 no
-   SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto.html>`__
--  `GPGME Python Bindings HOWTO draft (Texinfo file AWS S3
-   SSL) <https://files.au.adversary.org/crypto/gpgme-python-howto.texi>`__
--  `GPGME Python Bindings HOWTO draft (Texinfo file AWS S3 no
-   SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto.texi>`__
--  `GPGME Python Bindings HOWTO draft (Info file AWS S3
-   SSL) <https://files.au.adversary.org/crypto/gpgme-python-howto.info>`__
--  `GPGME Python Bindings HOWTO draft (Info file AWS S3 no
-   SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto.info>`__
--  `GPGME Python Bindings HOWTO draft (reST file AWS S3
-   SSL) <https://files.au.adversary.org/crypto/gpgme-python-howto.rst>`__
--  `GPGME Python Bindings HOWTO draft (reST file AWS S3 no
-   SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto.rst>`__
+-  `GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no
+   SS) <http://files.au.adversary.org/crypto/gpgme-python-howto.html>`__
+-  `GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3
+   SSL) <https://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html>`__
+-  `GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 no
+   SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html>`__
 
 All of these draft versions except for one have been generated from this
-document via Emacs `Org mode <https://orgmode.org/>`__ and `GNU
+document via GNU Emacs `Org mode <https://orgmode.org/>`__ and `GNU
 Texinfo <https://www.gnu.org/software/texinfo/>`__. Though it is likely
 that the specific
 `file <https://files.au.adversary.org/crypto/gpgme-python-howto>`__
 `version <http://files.au.adversary.org/crypto/gpgme-python-howto.org>`__
 used will be on the same server with 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
-either of the following two commands:
+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:
+
+.. code:: 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
+
+The reStructuredText format is also generated from the Org-mode source
+file, except it is generated using `Pandoc <https://pandoc.org>`__ with
+either of the following commands:
 
 .. code:: shell
 
index 5f736c7..746391c 100644 (file)
@@ -8,5 +8,8 @@ Contents
 
 -  `A short history of the project <short-history>`__
 -  `What\'s New <what-is-new>`__
+
+   -  `Maintenance Mode <maintenance-mode>`__ (from January, 2019)
+
 -  `What Was New <what-was-new>`__
 -  `GPGME Python Bindings HOWTO <gpgme-python-howto>`__
diff --git a/lang/python/doc/rst/maintenance-mode.rst b/lang/python/doc/rst/maintenance-mode.rst
new file mode 100644 (file)
index 0000000..75cd947
--- /dev/null
@@ -0,0 +1,95 @@
+.. _maintenance-mode:
+
+Maintenance Mode from 2019
+==========================
+
++-----------------------------------+-----------------------------------+
+| Version:                          | 0.0.1-draft                       |
++-----------------------------------+-----------------------------------+
+| GPGME Version:                    | 1.13.0                            |
++-----------------------------------+-----------------------------------+
+| Author:                           | `Ben                              |
+|                                   | McGinnes <https://gnupg.org/peopl |
+|                                   | e/index.html#sec-1-5>`__          |
+|                                   | <ben@gnupg.org>                   |
++-----------------------------------+-----------------------------------+
+| Author GPG Key:                   | `DB4724E6FA4286C92B4E55C4321E4E23 |
+|                                   | 73590E5D <https://hkps.pool.sks-k |
+|                                   | eyservers.net/pks/lookup?search=0 |
+|                                   | xDB4724E6FA4286C92B4E55C4321E4E23 |
+|                                   | 73590E5D&exact=on&op=get>`__      |
++-----------------------------------+-----------------------------------+
+| 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.
+
+.. _maintenance-mode-bm:
+
+Maintainer from 2019 onward
+---------------------------
+
+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.
+
+.. _maintenance-mode-blade-runner:
+
+Using the Python Bindings from 2019 and beyond
+----------------------------------------------
+
+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 `expedite
+it <https://gnupg.org/cgi-bin/procdonate.cgi?mode=preset>`__ (use the
+message field to state what feature is being requested).
index d6f0a5d..70f9b25 100644 (file)
@@ -1,6 +1,28 @@
 Overview
 ========
 
++-----------------------------------+-----------------------------------+
+| Version:                          | 0.0.1-draft                       |
++-----------------------------------+-----------------------------------+
+| GPGME Version:                    | 1.13.0                            |
++-----------------------------------+-----------------------------------+
+| Author:                           | `Ben                              |
+|                                   | McGinnes <https://gnupg.org/peopl |
+|                                   | e/index.html#sec-1-5>`__          |
+|                                   | <ben@gnupg.org>                   |
++-----------------------------------+-----------------------------------+
+| Author GPG Key:                   | `DB4724E6FA4286C92B4E55C4321E4E23 |
+|                                   | 73590E5D <https://hkps.pool.sks-k |
+|                                   | eyservers.net/pks/lookup?search=0 |
+|                                   | xDB4724E6FA4286C92B4E55C4321E4E23 |
+|                                   | 73590E5D&exact=on&op=get>`__      |
++-----------------------------------+-----------------------------------+
+| 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.
index 0fca98f..b3ec06a 100644 (file)
@@ -13,8 +13,11 @@ What\'s New
 |                                   | e/index.html#sec-1-5>`__          |
 |                                   | <ben@gnupg.org>                   |
 +-----------------------------------+-----------------------------------+
-| Author GPG Key:                   | DB4724E6FA4286C92B4E55C4321E4E237 |
-|                                   | 3590E5D                           |
+| Author GPG Key:                   | `DB4724E6FA4286C92B4E55C4321E4E23 |
+|                                   | 73590E5D <https://hkps.pool.sks-k |
+|                                   | eyservers.net/pks/lookup?search=0 |
+|                                   | xDB4724E6FA4286C92B4E55C4321E4E23 |
+|                                   | 73590E5D&exact=on&op=get>`__      |
 +-----------------------------------+-----------------------------------+
 | Language:                         | Australian English, British       |
 |                                   | English                           |
@@ -23,8 +26,7 @@ What\'s New
 +-----------------------------------+-----------------------------------+
 
 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-stuff-1-13-0:
 
@@ -41,3 +43,5 @@ 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 `maintenance mode <maintenance-mode>`__ from January,
+   2019.
index 23f3082..cc11bbf 100644 (file)
@@ -13,8 +13,11 @@ What Was New
 |                                   | e/index.html#sec-1-5>`__          |
 |                                   | <ben@gnupg.org>                   |
 +-----------------------------------+-----------------------------------+
-| Author GPG Key:                   | DB4724E6FA4286C92B4E55C4321E4E237 |
-|                                   | 3590E5D                           |
+| Author GPG Key:                   | `DB4724E6FA4286C92B4E55C4321E4E23 |
+|                                   | 73590E5D <https://hkps.pool.sks-k |
+|                                   | eyservers.net/pks/lookup?search=0 |
+|                                   | xDB4724E6FA4286C92B4E55C4321E4E23 |
+|                                   | 73590E5D&exact=on&op=get>`__      |
 +-----------------------------------+-----------------------------------+
 | Language:                         | Australian English, British       |
 |                                   | English                           |
index 4b02a93..fe1fc2b 100644 (file)
 
 | Version:        | 0.1.4                                    |
 | GPGME Version:  | 1.12.1                                   |
-| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <ben@gnupg.org>             |
-| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
+| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:ben@gnupg.org][ben@gnupg.org]]>             |
+| 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
index ce347ea..ec13c9a 100644 (file)
@@ -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 (file)
index 0000000..ef56e4e
--- /dev/null
@@ -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 <ben@gnupg.org>}
+
+
+* 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:ben@gnupg.org][ben@gnupg.org]]>             |
+| 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).
index 6c5c96e..c91f029 100644 (file)
@@ -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:ben@gnupg.org][ben@gnupg.org]]>             |
+| 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
index 5bcb5ae..ab94e3e 100644 (file)
 
 | Version:        | 0.0.1-draft                              |
 | GPGME Version:  | 1.13.0                                   |
-| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <ben@gnupg.org>             |
-| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
+| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:ben@gnupg.org][ben@gnupg.org]]>             |
+| 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.
index 7c851b1..1d3494c 100644 (file)
@@ -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]] <ben@gnupg.org>             |
-| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
+| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:ben@gnupg.org][ben@gnupg.org]]>             |
+| 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                         |
 
index 558bc87..ad3fbed 100644 (file)
@@ -171,15 +171,15 @@ Copyright and Licensing
 @node Introduction
 @chapter Introduction
 
-@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
+@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
 @item Version:
 @tab 0.1.4
 @item GPGME Version:
 @tab 1.12.1
 @item Author:
-@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <ben@@gnupg.org>
+@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}>
 @item Author GPG Key:
-@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D
+@tab @uref{https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get, DB4724E6FA4286C92B4E55C4321E4E2373590E5D}
 @item Language:
 @tab Australian English, British English
 @item Language codes:
@@ -3200,31 +3200,35 @@ from the author at any of the following URLs:
 
 @itemize
 @item
-@uref{https://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (XHTML AWS S3 SSL)}
+@uref{https://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 SSL)}
 @item
-@uref{http://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (XHTML AWS S3 no SSL)}
+@uref{http://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no SS)}
 @item
-@uref{https://files.au.adversary.org/crypto/gpgme-python-howto.texi, GPGME Python Bindings HOWTO draft (Texinfo file AWS S3 SSL)}
+@uref{https://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html, GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 SSL)}
 @item
-@uref{http://files.au.adversary.org/crypto/gpgme-python-howto.texi, GPGME Python Bindings HOWTO draft (Texinfo file AWS S3 no SSL)}
-@item
-@uref{https://files.au.adversary.org/crypto/gpgme-python-howto.info, GPGME Python Bindings HOWTO draft (Info file AWS S3 SSL)}
-@item
-@uref{http://files.au.adversary.org/crypto/gpgme-python-howto.info, GPGME Python Bindings HOWTO draft (Info file AWS S3 no SSL)}
-@item
-@uref{https://files.au.adversary.org/crypto/gpgme-python-howto.rst, GPGME Python Bindings HOWTO draft (reST file AWS S3 SSL)}
-@item
-@uref{http://files.au.adversary.org/crypto/gpgme-python-howto.rst, GPGME Python Bindings HOWTO draft (reST file AWS S3 no SSL)}
+@uref{http://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html, GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 no SSL)}
 @end itemize
 
 All of these draft versions except for one have been generated from
-this document via Emacs @uref{https://orgmode.org/, Org mode} and @uref{https://www.gnu.org/software/texinfo/, GNU Texinfo}.  Though it is likely
-that the specific @uref{https://files.au.adversary.org/crypto/gpgme-python-howto, file} @uref{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 @uref{https://orgmode.org/, Org mode} and @uref{https://www.gnu.org/software/texinfo/, GNU Texinfo}.  Though it is
+likely that the specific @uref{https://files.au.adversary.org/crypto/gpgme-python-howto, file} @uref{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:
+
+@example
+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 example
 
-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 @uref{https://pandoc.org, Pandoc} with either of the following
+commands:
 
 @example
 pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto.org
index 2ec5e24..2250d1e 100644 (file)
@@ -47,6 +47,10 @@ GPGME Python Bindings
 @uref{short-history, A short history of the project}
 @item
 @uref{what-is-new, What's New}
+@itemize
+@item
+@uref{maintenance-mode, Maintenance Mode} (from January, 2019)
+@end itemize
 @item
 @uref{what-was-new, What Was New}
 @item
diff --git a/lang/python/doc/texinfo/maintenance-mode.texi b/lang/python/doc/texinfo/maintenance-mode.texi
new file mode 100644 (file)
index 0000000..ad52606
--- /dev/null
@@ -0,0 +1,123 @@
+\input texinfo    @c -*- texinfo -*-
+@c %**start of header
+@setfilename maintenance-mode.info
+@settitle Maintenance Mode
+@documentencoding UTF-8
+@documentlanguage en
+@c %**end of header
+
+@finalout
+@titlepage
+@title Maintenance Mode
+@author Ben McGinnes
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top Maintenance Mode
+@end ifnottex
+
+@menu
+* Maintenance Mode from 2019::
+
+@detailmenu
+--- The Detailed Node Listing ---
+
+Maintenance Mode from 2019
+
+* Maintainer from 2019 onward::
+* Using the Python Bindings from 2019 and beyond::
+
+@end detailmenu
+@end menu
+
+@node Maintenance Mode from 2019
+@chapter Maintenance Mode from 2019
+
+@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
+@item Version:
+@tab 0.0.1-draft
+@item GPGME Version:
+@tab 1.13.0
+@item Author:
+@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}>
+@item Author GPG Key:
+@tab @uref{https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get, DB4724E6FA4286C92B4E55C4321E4E2373590E5D}
+@item Language:
+@tab Australian English, British English
+@item xml:lang:
+@tab en-AU, en-GB, en
+@end multitable
+
+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.
+
+@menu
+* Maintainer from 2019 onward::
+* Using the Python Bindings from 2019 and beyond::
+@end menu
+
+@node Maintainer from 2019 onward
+@section Maintainer from 2019 onward
+
+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.
+
+@node Using the Python Bindings from 2019 and beyond
+@section Using the Python Bindings from 2019 and beyond
+
+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 @emph{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 @uref{https://gnupg.org/cgi-bin/procdonate.cgi?mode=preset, expedite it} (use the message field to state what
+feature is being requested).
+
+@bye
\ No newline at end of file
index 395901f..480aebf 100644 (file)
@@ -49,6 +49,21 @@ The Perils of PyPI
 @node Overview
 @chapter Overview
 
+@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
+@item Version:
+@tab 0.0.1-draft
+@item GPGME Version:
+@tab 1.13.0
+@item Author:
+@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}>
+@item Author GPG Key:
+@tab @uref{https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get, DB4724E6FA4286C92B4E55C4321E4E2373590E5D}
+@item Language:
+@tab Australian English, British English
+@item xml:lang:
+@tab en-AU, en-GB, en
+@end multitable
+
 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.
index 0b70d21..25d12c2 100644 (file)
@@ -35,15 +35,15 @@ What's New
 @node What's New
 @chapter What's New
 
-@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
+@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
 @item Version:
 @tab 0.0.1-draft
 @item GPGME Version:
 @tab 1.13.0
 @item Author:
-@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <ben@@gnupg.org>
+@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}>
 @item Author GPG Key:
-@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D
+@tab @uref{https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get, DB4724E6FA4286C92B4E55C4321E4E2373590E5D}
 @item Language:
 @tab Australian English, British English
 @item xml:lang:
@@ -51,9 +51,7 @@ What's New
 @end multitable
 
 Last time the most obviously new thing was adding the @emph{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.
 
 @menu
 * New in GPGME 1·13·0::
@@ -75,6 +73,8 @@ Moving the preceding, archival, segments into @uref{what-was-new.org, another fi
 Added @samp{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).
+@item
+Bindings enter @uref{maintenance-mode, maintenance mode} from January, 2019.
 @end itemize
 
 @bye
\ No newline at end of file
index f81e0c3..63317d8 100644 (file)
@@ -39,15 +39,15 @@ What Was New in GPGME 1·12·0
 @node What Was New
 @chapter What Was New
 
-@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
+@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
 @item Version:
 @tab 0.0.1-draft
 @item GPGME Version:
 @tab 1.13.0
 @item Author:
-@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <ben@@gnupg.org>
+@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}>
 @item Author GPG Key:
-@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D
+@tab @uref{https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get, DB4724E6FA4286C92B4E55C4321E4E2373590E5D}
 @item Language:
 @tab Australian English, British English
 @item xml:lang:
index f23015a..9785a28 100755 (executable)
@@ -30,50 +30,50 @@ import subprocess
 import sys
 
 # Out-of-tree build of the gpg bindings.
-gpg_error_config = ["gpg-error-config"]
-gpgme_config_flags = ["--thread=pthread"]
-gpgme_config = ["gpgme-config"] + gpgme_config_flags
-gpgme_h = ""
+gpg_error_config = ['gpg-error-config']
+gpgme_config_flags = ['--thread=pthread']
+gpgme_config = ['gpgme-config'] + gpgme_config_flags
+gpgme_h = ''
 include_dirs = [os.getcwd()]
 library_dirs = []
 in_tree = False
 extra_swig_opts = []
 extra_macros = dict()
 
-top_builddir = os.environ.get("top_builddir")
+top_builddir = os.environ.get('top_builddir')
 if top_builddir:
     # In-tree build.
     in_tree = True
-    gpgme_config = [os.path.join(top_builddir, "src/gpgme-config")
+    gpgme_config = [os.path.join(top_builddir, 'src/gpgme-config')
                     ] + gpgme_config_flags
-    gpgme_h = os.path.join(top_builddir, "src/gpgme.h")
+    gpgme_h = os.path.join(top_builddir, 'src/gpgme.h')
     library_dirs = [os.path.join(top_builddir,
-                                 "src/.libs")]  # XXX uses libtool internals
+                                 'src/.libs')]  # XXX uses libtool internals
     extra_macros.update(
         HAVE_CONFIG_H=1,
         HAVE_DATA_H=1,
         IN_TREE_BUILD=1,
     )
 
-if hasattr(subprocess, "DEVNULL"):
+if hasattr(subprocess, 'DEVNULL'):
     devnull = subprocess.DEVNULL
 else:
-    devnull = open(os.devnull, "w")
+    devnull = open(os.devnull, 'w')
 
 try:
     subprocess.check_call(gpgme_config + ['--version'], stdout=devnull)
 except:
-    sys.exit("Could not find gpgme-config.  " +
-             "Please install the libgpgme development package.")
+    sys.exit('Could not find gpgme-config.  ' +
+             'Please install the libgpgme development package.')
 
 
 def getconfig(what, config=gpgme_config):
     confdata = subprocess.Popen(
-        config + ["--%s" % what], stdout=subprocess.PIPE).communicate()[0]
+        config + ['--%s' % what], stdout=subprocess.PIPE).communicate()[0]
     return [x for x in confdata.decode('utf-8').split() if x != '']
 
 
-version = version_raw = getconfig("version")[0]
+version = version_raw = getconfig('version')[0]
 if '-' in version:
     version = version.split('-')[0]
 major, minor, patch = map(int, version.split('.'))
@@ -82,31 +82,31 @@ if not (major > 1 or (major == 1 and minor >= 7)):
     sys.exit('Need at least GPGME version 1.7, found {}.'.format(version_raw))
 
 if not gpgme_h:
-    gpgme_h = os.path.join(getconfig("prefix")[0], "include", "gpgme.h")
+    gpgme_h = os.path.join(getconfig('prefix')[0], 'include', 'gpgme.h')
 
 define_macros = []
 libs = getconfig('libs')
 
 # Define extra_macros for both the SWIG and C code
 for k, v in extra_macros.items():
-    extra_swig_opts.append("-D{0}={1}".format(k, v))
+    extra_swig_opts.append('-D{0}={1}'.format(k, v))
     define_macros.append((k, str(v)))
 
 for item in getconfig('cflags'):
-    if item.startswith("-I"):
+    if item.startswith('-I'):
         include_dirs.append(item[2:])
-    elif item.startswith("-D"):
-        defitem = item[2:].split("=", 1)
+    elif item.startswith('-D'):
+        defitem = item[2:].split('=', 1)
         if len(defitem) == 2:
             define_macros.append((defitem[0], defitem[1]))
         else:
             define_macros.append((defitem[0], None))
 
 # Adjust include and library locations in case of win32
-uname_s = os.popen("uname -s").read()
-if uname_s.startswith("MINGW32"):
+uname_s = os.popen('uname -s').read()
+if uname_s.startswith('MINGW32'):
     mnts = [
-        x.split()[0:3:2] for x in os.popen("mount").read().split("\n") if x
+        x.split()[0:3:2] for x in os.popen('mount').read().split('\n') if x
     ]
     tmplist = sorted([(len(x[1]), x[1], x[0]) for x in mnts])
     tmplist.reverse()
@@ -120,7 +120,7 @@ if uname_s.startswith("MINGW32"):
                 extra_dirs.append(os.path.join(tgt, item))
                 break
     include_dirs += extra_dirs
-    for item in [x[2:] for x in libs if x.startswith("-L")]:
+    for item in [x[2:] for x in libs if x.startswith('-L')]:
         for ln, mnt, tgt in tmplist:
             if item.startswith(mnt):
                 item = os.path.normpath(item[ln:])
@@ -131,7 +131,7 @@ if uname_s.startswith("MINGW32"):
 
 
 def in_srcdir(name):
-    return os.path.join(os.environ.get("srcdir", ""), name)
+    return os.path.join(os.environ.get('srcdir', ''), name)
 
 
 def up_to_date(source, target):
@@ -160,9 +160,9 @@ def up_to_date(source, target):
 
 class BuildExtFirstHack(build):
     def _read_header(self, header, cflags):
-        tmp_include = self._in_build_base("include1.h")
+        tmp_include = self._in_build_base('include1.h')
         with open(tmp_include, 'w') as f:
-            f.write("#include <%s>" % header)
+            f.write('#include <%s>' % header)
         return subprocess.check_output(
             os.environ.get('CPP', 'cc -E').split() + cflags +
             [tmp_include]).decode('utf-8')
@@ -173,11 +173,11 @@ class BuildExtFirstHack(build):
                 if f.read() == content:
                     return
 
-        with open(target, "w") as sink:
+        with open(target, 'w') as sink:
             sink.write(content)
 
     def _generate_gpgme_h(self, source_name, sink_name):
-        print("Using gpgme.h from {}".format(source_name))
+        print('Using gpgme.h from {}'.format(source_name))
         shutil.copy2(source_name, sink_name)
 
     def _generate_errors_i(self):
@@ -186,11 +186,11 @@ class BuildExtFirstHack(build):
             subprocess.check_call(
                 gpg_error_config + ['--version'], stdout=devnull)
         except:
-            sys.exit("Could not find gpg-error-config.  " +
-                     "Please install the libgpg-error development package.")
+            sys.exit('Could not find gpg-error-config.  ' +
+                     'Please install the libgpg-error development package.')
 
         gpg_error_content = self._read_header(
-            "gpg-error.h", getconfig("cflags", config=gpg_error_config))
+            'gpg-error.h', getconfig('cflags', config=gpg_error_config))
 
         filter_re = re.compile(r'GPG_ERR_[^ ]* =')
         rewrite_re = re.compile(r' *(.*) = .*')
@@ -203,7 +203,7 @@ class BuildExtFirstHack(build):
                 r'%constant long \1 = \1;' + '\n', line.strip())
 
         self._write_if_unchanged(
-            self._in_build_base("errors.i"), errors_i_content)
+            self._in_build_base('errors.i'), errors_i_content)
 
     def _in_build_base(self, name):
         return os.path.join(self.build_base, name)
@@ -213,7 +213,7 @@ class BuildExtFirstHack(build):
         if not os.path.exists(self.build_base):
             os.makedirs(self.build_base)
 
-        self._generate_gpgme_h(gpgme_h, self._in_build_base("gpgme.h"))
+        self._generate_gpgme_h(gpgme_h, self._in_build_base('gpgme.h'))
         self._generate_errors_i()
 
         # Copy due to https://bugs.python.org/issue2624
@@ -225,9 +225,9 @@ class BuildExtFirstHack(build):
                 shutil.copy2(source, target)
 
         # Append generated files via build_base
-        if not os.path.exists(os.path.join(self.build_lib, "gpg")):
-            os.makedirs(os.path.join(self.build_lib, "gpg"))
-        shutil.copy2("version.py", os.path.join(self.build_lib, "gpg"))
+        if not os.path.exists(os.path.join(self.build_lib, 'gpg')):
+            os.makedirs(os.path.join(self.build_lib, 'gpg'))
+        shutil.copy2('version.py', os.path.join(self.build_lib, 'gpg'))
 
     def run(self):
         self._generate()
@@ -248,7 +248,7 @@ py3 = [] if sys.version_info.major < 3 else ['-py3']
 swig_sources = []
 swig_opts = ['-threads'] + py3 + extra_swig_opts
 swige = Extension(
-    "gpg._gpgme",
+    'gpg._gpgme',
     sources=swig_sources,
     swig_opts=swig_opts,
     include_dirs=include_dirs,
@@ -257,12 +257,34 @@ swige = Extension(
     extra_link_args=libs)
 
 setup(
-    name="gpg",
+    name='gpg',
     cmdclass={'build': BuildExtFirstHack},
-    version="@VERSION@",
-    description='Python bindings for GPGME GnuPG cryptography library',
-    # TODO: add a long description
-    # long_description=long_description,
+    version='@VERSION@',
+    # Note: description appears as Summary in egg-info file.
+    description='Python bindings to the GPGME API of the GnuPG cryptography library.',
+    # Note: long-description appears as Description in egg-info file.
+    long_description='''Dynamically generated bindings to the C API of the GNU Privacy Guard.
+
+The GPG Made Easy (GPGME) library provides a high-level API in C to all the
+component software and libraries in the GnuPG Project, including GPG itself
+(the GnuPG OpenPGP implementation), libgcrypt, libgpg-error, libassuan and
+more.
+
+The official CPython bindings to GPGME are generated during the compiling
+process of GPGME itself and built for the specific C header and include files
+produced when GPGME is compiled using SWIG.  This provides access to over two
+thousand functions, methods and values via both the lower level dynamically
+generated bindings and a more intuitively pythonic higher level layer.
+
+While the lower level, dynamically generated bindings provide access to
+everything which GPGME itself provides; the higher level layer is easier to use
+by Python developers, provides access to the vast majority of functionality
+developers would want from GnuPG and is extensively documented.
+
+GPGME and these bindings is available here:
+
+    https://gnupg.org/software/gpgme/index.html
+''',
     author='The GnuPG hackers',
     author_email='gnupg-devel@gnupg.org',
     url='https://www.gnupg.org',
@@ -271,7 +293,7 @@ setup(
         'gpg', 'gpg.constants', 'gpg.constants.data', 'gpg.constants.keylist',
         'gpg.constants.sig', 'gpg.constants.tofu'
     ],
-    license="LGPL2.1+ (the library), GPL2+ (tests and examples)",
+    license='LGPL2.1+ (the library), GPL2+ (tests and examples)',
     classifiers=[
         'Development Status :: 4 - Beta',
         'Intended Audience :: Developers',