docs: python docs restructure

* Moved the what's new section out of the HOWTO (mostly), in
  anticipation of expanding the docs to be more than merely a HOWTO.

1 files changed, 106 insertions, 0 deletions

diff --git a/lang/python/doc/src/what-was-new b/lang/python/doc/src/what-was-new
new file mode 100644
index 00000000..666e5ccf
--- /dev/null
+++ b/lang/python/doc/src/what-was-new
@@ -0,0 +1,106 @@
+# -*- mode: org -*-
+#+TITLE: What Was New in the GPGME Python Bindings and Documentation
+#+AUTHOR: Ben McGinnes
+#+LATEX_COMPILER: xelatex
+#+LATEX_CLASS: article
+#+LATEX_CLASS_OPTIONS: [12pt]
+#+LATEX_HEADER: \usepackage{xltxtra}
+#+LATEX_HEADER: \usepackage[margin=1in]{geometry}
+#+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Times New Roman}
+#+LATEX_HEADER: \author{Ben McGinnes <[email protected]>}
+
+
+* What Was New
+  :PROPERTIES:
+  :CUSTOM_ID: new-stuff
+  :END:
+
+| Version:        | 0.0.1-draft                              |
+| GPGME Version:  | 1.13.0                                   |
+| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[email protected]>             |
+| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
+| 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.
+
+
+** What Was New in GPGME 1·12·0
+   :PROPERTIES:
+   :CUSTOM_ID: gpgme-1-12-0
+   :END:
+
+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 in GPGME 1·12·0
+    :PROPERTIES:
+    :CUSTOM_ID: new-stuff-1-12-0
+    :END:
+
+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 [[#installation][installing]] and [[#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
+  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 [[#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]].
+- 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_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]].
+- 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.
+- 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-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.
+- The Texinfo documentation build configuration has been replicated
+  from the parent project in order to make to maintain consistency
+  with that project (and actually ship with each release).
+- a reStructuredText (=.rst=) version is also generated for Python
+  developers more used to and comfortable with that format as it is
+  the standard Python documentation format and Python developers may
+  wish to use it with Sphinx.  Please note that there has been no
+  testing of the reStructuredText version with Sphinx at all.  The
+  reST file was generated by the simple expedient of using [[https://pandoc.org/][Pandoc]].
+- Added a new section for [[#advanced-use][advanced or experimental use]].
+- Began the advanced use cases with [[#cython][a section]] on using the module with
+  [[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
+  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.