docs: python bindings
authorBen McGinnes <ben@adversary.org>
Tue, 6 Nov 2018 05:22:50 +0000 (16:22 +1100)
committerBen McGinnes <ben@adversary.org>
Tue, 6 Nov 2018 05:22:50 +0000 (16:22 +1100)
* Continued restructuring as part of moving beyond mere;y the HOWTO
  file.
* Generated the alternative source files for reST and Texinfo.
* Fixed some errors and updated links after moving the what's new
  section to two new files (yes, two).

14 files changed:
lang/python/doc/README
lang/python/doc/rst/gpgme-python-howto.rst
lang/python/doc/rst/index.rst
lang/python/doc/rst/short-history.rst
lang/python/doc/rst/what-is-new.rst [new file with mode: 0644]
lang/python/doc/rst/what-was-new.rst [new file with mode: 0644]
lang/python/doc/src/index
lang/python/doc/src/short-history
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/short-history.texi
lang/python/doc/texinfo/what-is-new.texi [new file with mode: 0644]
lang/python/doc/texinfo/what-was-new.texi [new file with mode: 0644]

index a14e1ad..76f1908 100644 (file)
@@ -25,14 +25,14 @@ This docs directory contains four main subdirectories:
  4. texinfo
 
 The Meta directory is for docs that are not intended for distribution
-or are about the docs themselves.  The sole exception being this RDME
-file.
+or are about the docs themselves.  The sole exception being this
+README file.
 
 The Src directory is where the original edited files are, from which
 the following two formats are generated initially.  Most, if not all,
 of these are written in Org Mode.
 
-The ReST directory contains reStructuredText files ehich have been
+The ReST directory contains reStructuredText files which have been
 converted to that format from the Org Mode files via Pandoc.
 
 The Texinfo directory contains Texinfo files which have been exported
index 104b530..3fd8a4d 100644 (file)
@@ -71,87 +71,25 @@ produced in between major releases.
 What\'s New
 -----------
 
-The most obviously new point for those reading this guide is this
-section on other new things, but that\'s hardly important. Not given all
-the other things which spurred the need for adding this section and its
-subsections.
+Full details of what is new are now available in the `What\'s
+New <what-is-new.org>`__ file and archives of the preceding *What\'s
+New* sections are available in the `What Was New <what-was-new>`__ file.
+
+.. _new-stuff-1-13-0:
+
+New in GPGME 1·13·0
+~~~~~~~~~~~~~~~~~~~
+
+See the `What\'s New <what-is-new#new-stuff-1-13-0>`__ document for what
+is new in version 1.13.0.
 
 .. _new-stuff-1-12-0:
 
 New in GPGME 1·12·0
 ~~~~~~~~~~~~~~~~~~~
 
-There have been quite a number of additions to GPGME and the Python
-bindings to it since the last release of GPGME with versions 1.11.0 and
-1.11.1 in April, 2018.
-
-The bullet points of new additiions are:
-
--  an expanded section on `installing <#installation>`__ and
-   `troubleshooting <#snafu>`__ the Python bindings.
--  The release of Python 3.7.0; which appears to be working just fine
-   with our bindings, in spite of intermittent reports of problems for
-   many other Python projects with that new release.
--  Python 3.7 has been moved to the head of the specified python
-   versions list in the build process.
--  In order to fix some other issues, there are certain underlying
-   functions which are more exposed through the
-   `gpg.Context() <#howto-get-context>`__, but ongoing documentation
-   ought to clarify that or otherwise provide the best means of using
-   the bindings. Some additions to ``gpg.core`` and the ``Context()``,
-   however, were intended (see below).
--  Continuing work in identifying and confirming the cause of
-   oft-reported `problems installing the Python bindings on
-   Windows <#snafu-runtime-not-funtime>`__.
--  GSOC: Google\'s Surreptitiously Ordered Conscription ... erm ... oh,
-   right; Google\'s Summer of Code. Though there were two hopeful
-   candidates this year; only one ended up involved with the GnuPG
-   Project directly, the other concentrated on an unrelated third party
-   project with closer ties to one of the GNU/Linux distributions than
-   to the GnuPG Project. Thus the Python bindings benefited from GSOC
-   participant Jacob Adams, who added the key\ :sub:`import` function;
-   building on prior work by Tobias Mueller.
--  Several new methods functions were added to the gpg.Context(),
-   including: `key\ import <#howto-import-key>`__,
-   `key\ export <#howto-export-key>`__,
-   `key\ exportminimal <#howto-export-public-key>`__ and
-   `key\ exportsecret <#howto-export-secret-key>`__.
--  Importing and exporting examples include versions integrated with
-   Marcel Fest\'s recently released `HKP for
-   Python <https://github.com/Selfnet/hkp4py>`__ module. Some
-   `additional notes on this module <#hkp4py>`__ are included at the end
-   of the HOWTO.
--  Instructions for dealing with semi-walled garden implementations like
-   ProtonMail are also included. This is intended to make things a
-   little easier when communicating with users of ProtonMail\'s services
-   and should not be construed as an endorsement of said service. The
-   GnuPG Project neither favours, nor disfavours ProtonMail and the
-   majority of this deals with interacting with the ProtonMail
-   keyserver.
--  Semi-formalised the location where `draft
-   versions <#draft-editions>`__ of this HOWTO may periodically be
-   accessible. This is both for the reference of others and testing the
-   publishing of the document itself. Renamed 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
-   `Pandoc <https://pandoc.org/>`__.
--  Added a new section for `advanced or experimental
-   use <#advanced-use>`__.
--  Began the advanced use cases with `a section <#cython>`__ on using
-   the module with `Cython <https://cython.org/>`__.
--  Added a number of new scripts to the ``example/howto/`` directory;
-   some of which may be in advance of their planned sections of the
-   HOWTO (and some are just there because it seemed like a good idea at
-   the time).
--  Cleaned up a lot of things under the hood.
+See the `What Was New <what-was-new#new-stuff-1-12-0>`__ document for
+what was new in version 1.12.0.
 
 GPGME Concepts
 ==============
@@ -472,7 +410,7 @@ place.
 Multiple installations
 ~~~~~~~~~~~~~~~~~~~~~~
 
-For a veriety of reasons it may be either necessary or just preferable
+For a variety of reasons it may be either necessary or just preferable
 to install the bindings to alternative installed Python versions which
 meet the requirements of these bindings.
 
@@ -489,6 +427,16 @@ by major version numbers and probably minor numbers too).
 On most POSIX systems, including OS X, this will very likely be the case
 in most, if not all, cases.
 
+Note that from GPGME
+`1.12.1 <https://dev.gnupg.org/rMff6ff616aea6f59b7f2ce1176492850ecdf3851e>`__
+the default installation installs to each version of Python it can find
+first. That is that it will currently install for the first copies of
+Python versions 2.7, 3.4, 3.5, 3.6, 3.7 and 3.8 (dev branch) that it
+finds. Usually this will be in the same prefix as GPGME itself, but is
+dictated by the ``$PATH`` when the installation is performed. The above
+instructions can still be performed on other python installations which
+the installer does not find, including alternative prefixes.
+
 .. _snafu-runtime-not-funtime:
 
 Won\'t Work With Windows
@@ -602,10 +550,10 @@ to or which are found by GPGME\'s configuration stage immediately prior
 to running the make commands. Which is exactly what the compiling and
 installing process of GPGME does by default.
 
-Once that is done, however, it appears that a copy the compiled module
-may be installed into a virtualenv of the same major and minor version
-matching the build. Alternatively it is possible to utilise a
-``sites.pth`` file in the ``site-packages/`` directory of a viertualenv
+Once that is done, however, it appears that a copy of the compiled
+module may be installed into a virtualenv of the same major and minor
+version matching the build. Alternatively it is possible to utilise a
+``sites.pth`` file in the ``site-packages/`` directory of a virtualenv
 installation, which links back to the system installations corresponding
 directory in order to import anything installed system wide. This may or
 may not be appropriate on a case by case basis.
@@ -2565,8 +2513,8 @@ Unsurprisingly the result of this is:
 
 .. _keygen-uids-revoke:
 
-Revokinging User IDs
-~~~~~~~~~~~~~~~~~~~~
+Revoking User IDs
+~~~~~~~~~~~~~~~~~
 
 Revoking a user ID is a fairly similar process, except that it uses the
 ``key_revoke_uid`` method.
@@ -2815,7 +2763,7 @@ is the key IDs of the group as a string.
 The ``group_lists`` result is very similar in that it is a list of
 lists. The first part, ``group_lists[i][0]`` matches
 ``group_lines[i][0]`` as the name of the group, but
-``group_lists[i][1]`` is the key IDs of the group as a string.
+``group_lists[i][1]`` is the key IDs of the group as a list.
 
 A demonstration of using the ``groups.py`` module is also available in
 the form of the executable ``mutt-groups.py`` script. This second script
@@ -2920,17 +2868,18 @@ All of these draft versions except for one have been generated from this
 document via 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.org>`__
+`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
-the following command:
+either of the following two commands:
 
 .. code:: 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
+   pandoc -f org -t rst -o gpgme-python-howto.rst gpgme-python-howto
 
 In addition to these there is a significantly less frequently updated
 version as a HTML `WebHelp
@@ -2965,7 +2914,7 @@ Footnotes
 =========
 
 .. [1]
-   ``short-history.org`` and/or ``short-history.html``.
+   ``short-history`` and/or ``short-history.html``.
 
 .. [2]
    With no issues reported specific to Python 3.7, the release of Python
index 31dc146..5f736c7 100644 (file)
@@ -1,12 +1,12 @@
-.. _index:
+.. _top:
 
 GPGME Python Bindings
 =====================
 
-.. _index-contents:
-
 Contents
 --------
 
--  `A short history of the project <short-history.org>`__
--  `GPGME Python Bindings HOWTO <gpgme-python-howto.org>`__
+-  `A short history of the project <short-history>`__
+-  `What\'s New <what-is-new>`__
+-  `What Was New <what-was-new>`__
+-  `GPGME Python Bindings HOWTO <gpgme-python-howto>`__
index 8cf604f..d6f0a5d 100644 (file)
@@ -19,10 +19,10 @@ 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.
+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
 -----------------
@@ -135,7 +135,7 @@ 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."
+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.
@@ -144,7 +144,7 @@ Footnotes
 =========
 
 .. [1]
-   In all likelihood thos would have been Python 2.2 or possibly Python
+   In all likelihood this would have been Python 2.2 or possibly Python
    2.3.
 
 .. [2]
diff --git a/lang/python/doc/rst/what-is-new.rst b/lang/python/doc/rst/what-is-new.rst
new file mode 100644 (file)
index 0000000..9332fb6
--- /dev/null
@@ -0,0 +1,42 @@
+.. _new-stuff:
+
+What\'s New
+===========
+
++-----------------------------------+-----------------------------------+
+| 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:                   | DB4724E6FA4286C92B4E55C4321E4E237 |
+|                                   | 3590E5D                           |
++-----------------------------------+-----------------------------------+
+| 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.
+
+.. _new-stuff-1-13-0:
+
+New in GPGME 1·13·0
+-------------------
+
+Additions since GPGME 1.12.0 include:
+
+-  An advanced HOWTO on using the bindings with web interfaces,
+   specifically Flask.
+-  Moving the *What\'s New* section out of the basic
+   `HOWTO <gpgme-python-howto.org>`__ document and into its own file so
+   as to more readily include other documents beyond that HOWTO.
+-  Moving the preceding, archival, segments into `another
+   file <what-was-new.org>`__.
diff --git a/lang/python/doc/rst/what-was-new.rst b/lang/python/doc/rst/what-was-new.rst
new file mode 100644 (file)
index 0000000..23f3082
--- /dev/null
@@ -0,0 +1,116 @@
+.. _new-stuff:
+
+What Was New
+============
+
++-----------------------------------+-----------------------------------+
+| 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:                   | DB4724E6FA4286C92B4E55C4321E4E237 |
+|                                   | 3590E5D                           |
++-----------------------------------+-----------------------------------+
+| Language:                         | Australian English, British       |
+|                                   | English                           |
++-----------------------------------+-----------------------------------+
+| xml:lang:                         | en-AU, en-GB, en                  |
++-----------------------------------+-----------------------------------+
+
+The following are all the past *What\'s New* sections for the Python
+Bindings HOWTO and other documentation.
+
+.. _gpgme-1-12-0:
+
+What Was New in GPGME 1·12·0
+----------------------------
+
+The most obviously new point for those reading this guide is this
+section on other new things, but that's hardly important. Not given all
+the other things which spurred the need for adding this section and its
+subsections.
+
+.. _new-stuff-1-12-0:
+
+New in GPGME 1·12·0
+~~~~~~~~~~~~~~~~~~~
+
+There have been quite a number of additions to GPGME and the Python
+bindings to it since the last release of GPGME with versions 1.11.0 and
+1.11.1 in April, 2018.
+
+The bullet points of new additiions are:
+
+-  an expanded section on
+   `installing <gpgme-python-howto#installation>`__ and
+   `troubleshooting <gpgme-python-howto#snafu>`__ the Python bindings.
+-  The release of Python 3.7.0; which appears to be working just fine
+   with our bindings, in spite of intermittent reports of problems for
+   many other Python projects with that new release.
+-  Python 3.7 has been moved to the head of the specified python
+   versions list in the build process.
+-  In order to fix some other issues, there are certain underlying
+   functions which are more exposed through the
+   `gpg.Context() <gpgme-python-howto#howto-get-context>`__, but ongoing
+   documentation ought to clarify that or otherwise provide the best
+   means of using the bindings. Some additions to ``gpg.core`` and the
+   ``Context()``, however, were intended (see below).
+-  Continuing work in identifying and confirming the cause of
+   oft-reported `problems installing the Python bindings on
+   Windows <gpgme-python-howto#snafu-runtime-not-funtime>`__.
+-  GSOC: Google\'s Surreptitiously Ordered Conscription ... erm ... oh,
+   right; Google\'s Summer of Code. Though there were two hopeful
+   candidates this year; only one ended up involved with the GnuPG
+   Project directly, the other concentrated on an unrelated third party
+   project with closer ties to one of the GNU/Linux distributions than
+   to the GnuPG Project. Thus the Python bindings benefited from GSOC
+   participant Jacob Adams, who added the key\ :sub:`import` function;
+   building on prior work by Tobias Mueller.
+-  Several new methods functions were added to the gpg.Context(),
+   including: `key\ import <gpgme-python-howto#howto-import-key>`__,
+   `key\ export <gpgme-python-howto#howto-export-key>`__,
+   `key\ exportminimal <gpgme-python-howto#howto-export-public-key>`__
+   and
+   `key\ exportsecret <gpgme-python-howto#howto-export-secret-key>`__.
+-  Importing and exporting examples include versions integrated with
+   Marcel Fest\'s recently released `HKP for
+   Python <https://github.com/Selfnet/hkp4py>`__ module. Some
+   `additional notes on this module <gpgme-python-howto#hkp4py>`__ are
+   included at the end of the HOWTO.
+-  Instructions for dealing with semi-walled garden implementations like
+   ProtonMail are also included. This is intended to make things a
+   little easier when communicating with users of ProtonMail\'s services
+   and should not be construed as an endorsement of said service. The
+   GnuPG Project neither favours, nor disfavours ProtonMail and the
+   majority of this deals with interacting with the ProtonMail
+   keyserver.
+-  Semi-formalised the location where `draft
+   versions <gpgme-python-howto#draft-editions>`__ of this HOWTO may
+   periodically be accessible. This is both for the reference of others
+   and testing the publishing of the document itself. Renamed 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
+   `Pandoc <https://pandoc.org/>`__.
+-  Added a new section for `advanced or experimental
+   use <gpgme-python-howto#advanced-use>`__.
+-  Began the advanced use cases with `a
+   section <gpgme-python-howto#cython>`__ on using the module with
+   `Cython <https://cython.org/>`__.
+-  Added a number of new scripts to the ``example/howto/`` directory;
+   some of which may be in advance of their planned sections of the
+   HOWTO (and some are just there because it seemed like a good idea at
+   the time).
+-  Cleaned up a lot of things under the hood.
index 18c9386..ce347ea 100644 (file)
 
 * GPGME Python Bindings
   :PROPERTIES:
-  :CUSTOM_ID: index
+  :CUSTOM_ID: top
   :END:
 
 
 ** Contents
    :PROPERTIES:
-   :CUSTOM_ID: index-contents
+   :CUSTOM_ID: contents
    :END:
 
 
 - [[file:short-history][A short history of the project]]
+- [[file:what-is-new][What's New]]
+- [[file:what-was-new][What Was New]]
 - [[file:gpgme-python-howto][GPGME Python Bindings HOWTO]]
index ac5804d..6c5c96e 100644 (file)
@@ -166,7 +166,7 @@ SWIG itself, which are worth noting here.
 
 * Footnotes
 
-[fn:1] In all likelihood thos would have been Python 2.2 or possibly
+[fn:1] In all likelihood this would have been Python 2.2 or possibly
 Python 2.3.
 
 [fn:2] The entire PyME git log and other preceding VCS logs are
index 666e5cc..7c851b1 100644 (file)
@@ -48,7 +48,7 @@ and 1.11.1 in April, 2018.
 
 The bullet points of new additiions are:
 
-- an expanded section on [[#installation][installing]] and [[#snafu][troubleshooting]] the Python
+- an expanded section on [[file:gpgme-python-howto#installation][installing]] and [[file:gpgme-python-howto#snafu][troubleshooting]] the Python
   bindings.
 - The release of Python 3.7.0; which appears to be working just fine
   with our bindings, in spite of intermittent reports of problems for
@@ -56,12 +56,12 @@ The bullet points of new additiions are:
 - Python 3.7 has been moved to the head of the specified python
   versions list in the build process.
 - In order to fix some other issues, there are certain underlying
-  functions which are more exposed through the [[#howto-get-context][gpg.Context()]], but
+  functions which are more exposed through the [[file:gpgme-python-howto#howto-get-context][gpg.Context()]], but
   ongoing documentation ought to clarify that or otherwise provide the
   best means of using the bindings.  Some additions to =gpg.core= and
   the =Context()=, however, were intended (see below).
 - Continuing work in identifying and confirming the cause of
-  oft-reported [[#snafu-runtime-not-funtime][problems installing the Python bindings on Windows]].
+  oft-reported [[file:gpgme-python-howto#snafu-runtime-not-funtime][problems installing the Python bindings on Windows]].
 - GSOC: Google's Surreptitiously Ordered Conscription ... erm ... oh,
   right; Google's Summer of Code.  Though there were two hopeful
   candidates this year; only one ended up involved with the GnuPG
@@ -71,11 +71,11 @@ The bullet points of new additiions are:
   participant Jacob Adams, who added the key_import function; building
   on prior work by Tobias Mueller.
 - Several new methods functions were added to the gpg.Context(),
-  including: [[#howto-import-key][key_import]], [[#howto-export-key][key_export]], [[#howto-export-public-key][key_export_minimal]] and
-  [[#howto-export-secret-key][key_export_secret]].
+  including: [[file:gpgme-python-howto#howto-import-key][key_import]], [[file:gpgme-python-howto#howto-export-key][key_export]], [[file:gpgme-python-howto#howto-export-public-key][key_export_minimal]] and
+  [[file:gpgme-python-howto#howto-export-secret-key][key_export_secret]].
 - Importing and exporting examples include versions integrated with
   Marcel Fest's recently released [[https://github.com/Selfnet/hkp4py][HKP for Python]] module.  Some
-  [[#hkp4py][additional notes on this module]] are included at the end of the HOWTO.
+  [[file:gpgme-python-howto#hkp4py][additional notes on this module]] are included at the end of the HOWTO.
 - Instructions for dealing with semi-walled garden implementations
   like ProtonMail are also included.  This is intended to make things
   a little easier when communicating with users of ProtonMail's
@@ -83,7 +83,7 @@ The bullet points of new additiions are:
   service.  The GnuPG Project neither favours, nor disfavours
   ProtonMail and the majority of this deals with interacting with the
   ProtonMail keyserver.
-- Semi-formalised the location where [[#draft-editions][draft versions]] of this HOWTO may
+- Semi-formalised the location where [[file:gpgme-python-howto#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
   this file at around the same time.
@@ -96,8 +96,8 @@ The bullet points of new additiions are:
   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
+- Added a new section for [[file:gpgme-python-howto#advanced-use][advanced or experimental use]].
+- Began the advanced use cases with [[file:gpgme-python-howto#cython][a section]] on using the module with
   [[https://cython.org/][Cython]].
 - Added a number of new scripts to the =example/howto/= directory;
   some of which may be in advance of their planned sections of the
index 695ed15..d776f58 100644 (file)
@@ -43,6 +43,7 @@ Introduction
 
 What's New
 
+* New in GPGME 1·13·0::
 * New in GPGME 1·12·0::
 
 GPGME Concepts
@@ -138,7 +139,7 @@ Creating keys and subkeys
 User IDs
 
 * Adding User IDs::
-* Revokinging User IDs::
+* Revoking User IDs::
 
 Advanced or Experimental Use Cases
 
@@ -230,98 +231,24 @@ major releases.
 @node What's New
 @section What's New
 
-The most obviously new point for those reading this guide is this
-section on other new things, but that's hardly important.  Not given
-all the other things which spurred the need for adding this section
-and its subsections.
+Full details of what is new are now available in the @uref{what-is-new.org, What's New} file
+and archives of the preceding @emph{What's New} sections are available in
+the @uref{what-was-new, What Was New} file.
 
 @menu
+* New in GPGME 1·13·0::
 * New in GPGME 1·12·0::
 @end menu
 
-@node New in GPGME 1·12·0
-@subsection New in GPGME 1·12·0
+@node New in GPGME 1·13·0
+@subsection New in GPGME 1·13·0
 
-There have been quite a number of additions to GPGME and the Python
-bindings to it since the last release of GPGME with versions 1.11.0
-and 1.11.1 in April, 2018.
+See the @uref{what-is-new#new-stuff-1-13-0, What's New} document for what is new in version 1.13.0.
 
-The bullet points of new additiions are:
+@node New in GPGME 1·12·0
+@subsection New in GPGME 1·12·0
 
-@itemize
-@item
-an expanded section on @ref{Installation, , installing} and @ref{Known Issues, , troubleshooting} the Python
-bindings.
-@item
-The release of Python 3.7.0; which appears to be working just fine
-with our bindings, in spite of intermittent reports of problems for
-many other Python projects with that new release.
-@item
-Python 3.7 has been moved to the head of the specified python
-versions list in the build process.
-@item
-In order to fix some other issues, there are certain underlying
-functions which are more exposed through the @ref{Context, , gpg.Context()}, but
-ongoing documentation ought to clarify that or otherwise provide the
-best means of using the bindings.  Some additions to @samp{gpg.core} and
-the @samp{Context()}, however, were intended (see below).
-@item
-Continuing work in identifying and confirming the cause of
-oft-reported @ref{Won't Work With Windows, , problems installing the Python bindings on Windows}.
-@item
-GSOC: Google's Surreptitiously Ordered Conscription @dots{} erm @dots{} oh,
-right; Google's Summer of Code.  Though there were two hopeful
-candidates this year; only one ended up involved with the GnuPG
-Project directly, the other concentrated on an unrelated third party
-project with closer ties to one of the GNU/Linux distributions than
-to the GnuPG Project.  Thus the Python bindings benefited from GSOC
-participant Jacob Adams, who added the key@math{_import} function; building
-on prior work by Tobias Mueller.
-@item
-Several new methods functions were added to the gpg.Context(),
-including: @ref{Importing keys, , key@math{_import}}, @ref{Exporting keys, , key@math{_export}}, @ref{Exporting public keys, , key@math{_export}@math{_minimal}} and
-@ref{Exporting secret keys, , key@math{_export}@math{_secret}}.
-@item
-Importing and exporting examples include versions integrated with
-Marcel Fest's recently released @uref{https://github.com/Selfnet/hkp4py, HKP for Python} module.  Some
-@ref{Keyserver access for Python, , additional notes on this module} are included at the end of the HOWTO.
-@item
-Instructions for dealing with semi-walled garden implementations
-like ProtonMail are also included.  This is intended to make things
-a little easier when communicating with users of ProtonMail's
-services and should not be construed as an endorsement of said
-service.  The GnuPG Project neither favours, nor disfavours
-ProtonMail and the majority of this deals with interacting with the
-ProtonMail keyserver.
-@item
-Semi-formalised the location where @ref{Draft Editions of this HOWTO, , 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
-this file at around the same time.
-@item
-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).
-@item
-a reStructuredText (@samp{.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 @uref{https://pandoc.org/, Pandoc}.
-@item
-Added a new section for @ref{Advanced or Experimental Use Cases, , advanced or experimental use}.
-@item
-Began the advanced use cases with @ref{C plus Python plus SWIG plus Cython, , a section} on using the module with
-@uref{https://cython.org/, Cython}.
-@item
-Added a number of new scripts to the @samp{example/howto/} directory;
-some of which may be in advance of their planned sections of the
-HOWTO (and some are just there because it seemed like a good idea at
-the time).
-@item
-Cleaned up a lot of things under the hood.
-@end itemize
+See the @uref{what-was-new#new-stuff-1-12-0, What Was New} document for what was new in version 1.12.0.
 
 @node GPGME Concepts
 @chapter GPGME Concepts
@@ -418,7 +345,7 @@ version 3.0 (or any later version).
 
 This package is the origin of these bindings, though they are somewhat
 different now.  For details of when and how the PyME package was
-folded back into GPGME itself see the @uref{short-history.org, Short History} document.@footnote{@samp{short-history.org} and/or @samp{short-history.html}.}
+folded back into GPGME itself see the @uref{short-history.org, Short History} document.@footnote{@samp{short-history} and/or @samp{short-history.html}.}
 
 The PyME package was first released in 2002 and was also the first
 attempt to implement a low level binding to GPGME.  In doing so it
@@ -670,7 +597,7 @@ place.
 @node Multiple installations
 @subsection Multiple installations
 
-For a veriety of reasons it may be either necessary or just preferable
+For a variety of reasons it may be either necessary or just preferable
 to install the bindings to alternative installed Python versions which
 meet the requirements of these bindings.
 
@@ -687,6 +614,15 @@ by major version numbers and probably minor numbers too).
 On most POSIX systems, including OS X, this will very likely be the
 case in most, if not all, cases.
 
+Note that from GPGME @uref{https://dev.gnupg.org/rMff6ff616aea6f59b7f2ce1176492850ecdf3851e, 1.12.1} the default installation installs to each
+version of Python it can find first.  That is that it will currently
+install for the first copies of Python versions 2.7, 3.4, 3.5, 3.6,
+3.7 and 3.8 (dev branch) that it finds.  Usually this will be in the
+same prefix as GPGME itself, but is dictated by the @samp{$PATH} when the
+installation is performed.  The above instructions can still be
+performed on other python installations which the installer does not
+find, including alternative prefixes.
+
 @node Won't Work With Windows
 @subsection Won't Work With Windows
 
@@ -800,10 +736,10 @@ to or which are found by GPGME's configuration stage immediately prior
 to running the make commands.  Which is exactly what the compiling and
 installing process of GPGME does by default.
 
-Once that is done, however, it appears that a copy the compiled module
-may be installed into a virtualenv of the same major and minor version
-matching the build.  Alternatively it is possible to utilise a
-@samp{sites.pth} file in the @samp{site-packages/} directory of a viertualenv
+Once that is done, however, it appears that a copy of the compiled
+module may be installed into a virtualenv of the same major and minor
+version matching the build.  Alternatively it is possible to utilise a
+@samp{sites.pth} file in the @samp{site-packages/} directory of a virtualenv
 installation, which links back to the system installations
 corresponding directory in order to import anything installed system
 wide.  This may or may not be appropriate on a case by case basis.
@@ -2724,7 +2660,7 @@ bash-4.4$
 
 @menu
 * Adding User IDs::
-* Revokinging User IDs::
+* Revoking User IDs::
 @end menu
 
 @node Adding User IDs
@@ -2763,8 +2699,8 @@ ssb   rsa3072 2018-03-15 [E] [expires: 2018-09-13]
 bash-4.4$
 @end example
 
-@node Revokinging User IDs
-@subsection Revokinging User IDs
+@node Revoking User IDs
+@subsection Revoking User IDs
 
 Revoking a user ID is a fairly similar process, except that it uses
 the @samp{key_revoke_uid} method.
@@ -3009,7 +2945,7 @@ is the key IDs of the group as a string.
 The @samp{group_lists} result is very similar in that it is a list of
 lists.  The first part, @samp{group_lists[i][0]} matches
 @samp{group_lines[i][0]} as the name of the group, but @samp{group_lists[i][1]}
-is the key IDs of the group as a string.
+is the key IDs of the group as a list.
 
 A demonstration of using the @samp{groups.py} module is also available in
 the form of the executable @samp{mutt-groups.py} script.  This second
@@ -3116,15 +3052,16 @@ from the author at any of the following URLs:
 
 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.org, file} @uref{http://files.au.adversary.org/crypto/gpgme-python-howto.org, version} used will be on the same server with
+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 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:
+either of the following two commands:
 
 @example
-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
+pandoc -f org -t rst -o gpgme-python-howto.rst gpgme-python-howto
 @end example
 
 In addition to these there is a significantly less frequently updated
@@ -3152,4 +3089,4 @@ WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
 implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 PURPOSE.
 
-@bye
+@bye
\ No newline at end of file
index 4f80423..2ec5e24 100644 (file)
@@ -44,9 +44,13 @@ GPGME Python Bindings
 
 @itemize
 @item
-@uref{short-history.org, A short history of the project}
+@uref{short-history, A short history of the project}
 @item
-@uref{gpgme-python-howto.org, GPGME Python Bindings HOWTO}
+@uref{what-is-new, What's New}
+@item
+@uref{what-was-new, What Was New}
+@item
+@uref{gpgme-python-howto, GPGME Python Bindings HOWTO}
 @end itemize
 
 @bye
\ No newline at end of file
index a982f02..395901f 100644 (file)
@@ -65,7 +65,7 @@ return to the source.  This is a short explanation of that journey.
 
 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
+SWIG.@footnote{In all likelihood this 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.
diff --git a/lang/python/doc/texinfo/what-is-new.texi b/lang/python/doc/texinfo/what-is-new.texi
new file mode 100644 (file)
index 0000000..6233cac
--- /dev/null
@@ -0,0 +1,79 @@
+\input texinfo    @c -*- texinfo -*-
+@c %**start of header
+@setfilename what-is-new.info
+@settitle What's New in the GPGME Python Bindings and Documentation
+@documentencoding UTF-8
+@documentlanguage en
+@c %**end of header
+
+@finalout
+@titlepage
+@title What's New in the GPGME Python Bindings and Documentation
+@author Ben McGinnes
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top What's New in the GPGME Python Bindings and Documentation
+@end ifnottex
+
+@menu
+* What's New::
+
+@detailmenu
+--- The Detailed Node Listing ---
+
+What's New
+
+* New in GPGME 1·13·0::
+
+@end detailmenu
+@end menu
+
+@node What's New
+@chapter What's New
+
+@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
+@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>
+@item Author GPG Key:
+@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D
+@item Language:
+@tab Australian English, British English
+@item xml:lang:
+@tab en-AU, en-GB, en
+@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.
+
+@menu
+* New in GPGME 1·13·0::
+@end menu
+
+@node New in GPGME 1·13·0
+@section New in GPGME 1·13·0
+
+Additions since GPGME 1.12.0 include:
+
+@itemize
+@item
+An advanced HOWTO on using the bindings with web interfaces,
+specifically Flask.
+@item
+Moving the @emph{What's New} section out of the basic @uref{gpgme-python-howto.org, HOWTO} document and
+into its own file so as to more readily include other documents
+beyond that HOWTO.
+@item
+Moving the preceding, archival, segments into @uref{what-was-new.org, another file}.
+@end itemize
+
+@bye
\ No newline at end of file
diff --git a/lang/python/doc/texinfo/what-was-new.texi b/lang/python/doc/texinfo/what-was-new.texi
new file mode 100644 (file)
index 0000000..f81e0c3
--- /dev/null
@@ -0,0 +1,160 @@
+\input texinfo    @c -*- texinfo -*-
+@c %**start of header
+@setfilename what-was-new.info
+@settitle What Was New in the GPGME Python Bindings and Documentation
+@documentencoding UTF-8
+@documentlanguage en
+@c %**end of header
+
+@finalout
+@titlepage
+@title What Was New in the GPGME Python Bindings and Documentation
+@author Ben McGinnes
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top What Was New in the GPGME Python Bindings and Documentation
+@end ifnottex
+
+@menu
+* What Was New::
+
+@detailmenu
+--- The Detailed Node Listing ---
+
+What Was New
+
+* What Was New in GPGME 1·12·0::
+
+What Was New in GPGME 1·12·0
+
+* New in GPGME 1·12·0::
+
+@end detailmenu
+@end menu
+
+@node What Was New
+@chapter What Was New
+
+@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
+@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>
+@item Author GPG Key:
+@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D
+@item Language:
+@tab Australian English, British English
+@item xml:lang:
+@tab en-AU, en-GB, en
+@end multitable
+
+The following are all the past @emph{What's New} sections for the Python
+Bindings HOWTO and other documentation.
+
+@menu
+* What Was New in GPGME 1·12·0::
+@end menu
+
+@node What Was New in GPGME 1·12·0
+@section What Was New in GPGME 1·12·0
+
+The most obviously new point for those reading this guide is this
+section on other new things, but that’s hardly important. Not given
+all the other things which spurred the need for adding this section
+and its subsections.
+
+@menu
+* New in GPGME 1·12·0::
+@end menu
+
+@node New in GPGME 1·12·0
+@subsection New in GPGME 1·12·0
+
+There have been quite a number of additions to GPGME and the Python
+bindings to it since the last release of GPGME with versions 1.11.0
+and 1.11.1 in April, 2018.
+
+The bullet points of new additiions are:
+
+@itemize
+@item
+an expanded section on @uref{gpgme-python-howto#installation, installing} and @uref{gpgme-python-howto#snafu, troubleshooting} the Python
+bindings.
+@item
+The release of Python 3.7.0; which appears to be working just fine
+with our bindings, in spite of intermittent reports of problems for
+many other Python projects with that new release.
+@item
+Python 3.7 has been moved to the head of the specified python
+versions list in the build process.
+@item
+In order to fix some other issues, there are certain underlying
+functions which are more exposed through the @uref{gpgme-python-howto#howto-get-context, gpg.Context()}, but
+ongoing documentation ought to clarify that or otherwise provide the
+best means of using the bindings.  Some additions to @samp{gpg.core} and
+the @samp{Context()}, however, were intended (see below).
+@item
+Continuing work in identifying and confirming the cause of
+oft-reported @uref{gpgme-python-howto#snafu-runtime-not-funtime, problems installing the Python bindings on Windows}.
+@item
+GSOC: Google's Surreptitiously Ordered Conscription @dots{} erm @dots{} oh,
+right; Google's Summer of Code.  Though there were two hopeful
+candidates this year; only one ended up involved with the GnuPG
+Project directly, the other concentrated on an unrelated third party
+project with closer ties to one of the GNU/Linux distributions than
+to the GnuPG Project.  Thus the Python bindings benefited from GSOC
+participant Jacob Adams, who added the key@math{_import} function; building
+on prior work by Tobias Mueller.
+@item
+Several new methods functions were added to the gpg.Context(),
+including: @uref{gpgme-python-howto#howto-import-key, key@math{_import}}, @uref{gpgme-python-howto#howto-export-key, key@math{_export}}, @uref{gpgme-python-howto#howto-export-public-key, key@math{_export}@math{_minimal}} and
+@uref{gpgme-python-howto#howto-export-secret-key, key@math{_export}@math{_secret}}.
+@item
+Importing and exporting examples include versions integrated with
+Marcel Fest's recently released @uref{https://github.com/Selfnet/hkp4py, HKP for Python} module.  Some
+@uref{gpgme-python-howto#hkp4py, additional notes on this module} are included at the end of the HOWTO.
+@item
+Instructions for dealing with semi-walled garden implementations
+like ProtonMail are also included.  This is intended to make things
+a little easier when communicating with users of ProtonMail's
+services and should not be construed as an endorsement of said
+service.  The GnuPG Project neither favours, nor disfavours
+ProtonMail and the majority of this deals with interacting with the
+ProtonMail keyserver.
+@item
+Semi-formalised the location where @uref{gpgme-python-howto#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
+this file at around the same time.
+@item
+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).
+@item
+a reStructuredText (@samp{.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 @uref{https://pandoc.org/, Pandoc}.
+@item
+Added a new section for @uref{gpgme-python-howto#advanced-use, advanced or experimental use}.
+@item
+Began the advanced use cases with @uref{gpgme-python-howto#cython, a section} on using the module with
+@uref{https://cython.org/, Cython}.
+@item
+Added a number of new scripts to the @samp{example/howto/} directory;
+some of which may be in advance of their planned sections of the
+HOWTO (and some are just there because it seemed like a good idea at
+the time).
+@item
+Cleaned up a lot of things under the hood.
+@end itemize
+
+@bye
\ No newline at end of file