python: docs update

* Expanded the section on issues with Windows installations, with
  greater detail of which versions of Visual Studio are needed
  depending on which version of CPython is to be used.
* Included a recommendation which is a bit harsh without being totally
  prickish.
* Updated all files to not link to author's key or related data in
  order to make them all consistent with the changes in commit
  649b19688132dd315e361c0f5b63ba6d8f45996d.

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

1 files changed, 75 insertions, 4 deletions

diff --git a/lang/python/doc/src/gpgme-python-howto b/lang/python/doc/src/gpgme-python-howto
index 43d0c2b3..5436bfb7 100644
--- a/lang/python/doc/src/gpgme-python-howto
+++ b/lang/python/doc/src/gpgme-python-howto
@@ -17,8 +17,8 @@
 
 | Version:        | 0.1.4                                    |
 | GPGME Version:  | 1.12.1                                   |
-| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:[email protected]][[email protected]]]>             |
-| Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] |
+| Author:         | Ben McGinnes <[email protected]>             |
+| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
 | Language:       | Australian English, British English      |
 | Language codes: | en-AU, en-GB, en                         |
 
@@ -493,12 +493,13 @@ been kept around far longer than it should have been.
 There are two theoretical solutions to this issue:
 
  1. Compile and install the GnuPG stack, including GPGME and the
-    Python bibdings using the same version of Microsoft Visual Studio
+    Python bindings using the same version of Microsoft Visual Studio
     used by the Python Foundation to compile the version of Python
     installed.
 
     If there are multiple versions of Python then this will need to be
-    done with each different version of Visual Studio used.
+    done with each different version of Visual Studio used for those
+    versions of Python.
 
  2. Compile and install Python using the same tools used by choice,
     such as MinGW or Msys2.
@@ -515,6 +516,76 @@ what.
 Investigations into the extent or the limitations of this issue are
 ongoing.
 
+The following table lists the version of Microsoft Visual Studio which
+needs to be used when compiling GPGME and the Python bindings with
+each version of the CPython binary released [[https://www.python.org/downloads/windows/][for Windows]]:
+
+| CPython | Microsoft product name | runtime filename |
+|  2.7.6  |   Visual Studio 2008   |   MSVCR90.DLL    |
+|  3.4.0  |   Visual Studio 2010   |   MSVCR100.DLL   |
+|  3.5.0  |   Visual Studio 2015   |   *see below*    |
+|  3.6.0  |   Visual Studio 2015   |   *see below*    |
+|  3.7.0  |   Visual Studio 2017*  |   *see below*    |
+
+It is important to note that MingW and Msys2 ship with the Visual C
+runtime from Microsoft Visual Studio 2005 and are thus *incompatible*
+with all the versions of CPython which can be used with the GPGME
+Python bindings.
+
+It is also important to note that from CPython 3.5 onwards, the Python
+Foundation has adopted the reworking of the Visual C runtime which was
+performed for Visual Studio 2015 and aimed at resolving many of these
+kinds of issues.  Much greater detail on these issues and the correct
+file(s) to link to are available from Matthew Brett's invaluable page,
+[[https://matthew-brett.github.io/pydagogue/python_msvc.html][Using Microsoft Visual C with Python]].  It is also worth reading the
+Microsoft Developer Network blog post on [[http://blogs.msdn.com/b/vcblog/archive/2015/03/03/introducing-the-universal-crt.aspx][the universal CRT]] and Steve
+Dower's blog posts on Python extensions ([[http://stevedower.id.au/blog/building-for-python-3-5][part 1]] and [[http://stevedower.id.au/blog/building-for-python-3-5-part-two][part 2]]).
+
+The second of those two posts by Steve Dower contains the details of
+specific configuration options required for compiling anything to be
+used with official CPython releases.  In addition to those
+configuration and compiler settings to use, the versions of Visual
+Studio prior to Visual Studio 2015 did not support 64-bit systems by
+default.  So compiling a 64-bit version of these bindings for a 64-bit
+version of CPython 2.7 or 3.4 requires additional work.
+
+In addition to the blog posts, the [[https://wiki.python.org/moin/WindowsCompilers][Windows compilers]] wiki page on the
+CPython wiki is another essential reference on the relevant versions
+of Visual Studio to use and the degree of compatibility with CPython
+releases.
+
+Eventually someone will ask why there isn't an installable binary for
+Windows, which the GPGME of the licenses do not preclude as long as
+the source code is available in conjunction with such a release.
+
+The sheer number of versions of Visual Studio in conjunction with
+differing configuration options depending on the target Windows
+version and whether the architecture is 64-bit or 32-bit makes it
+difficult to provide a correct binary installer for Windows users.  At
+the bare minimum doing so would require the GnuPG project compile ten
+different versions of the bindings with each release; both 32-bit and
+64-bit versions for CPython 2.7 and 3.4, with 64-bit versions for both
+x86-64 (i.e. Intel and AMD) and ARM architectures for CPython 3.5,
+3.6, 3.7 and later releases.  That's the bare *minimum*, it'd probably
+be higher.
+
+Considering all of that, what do we recommend?
+
+ 1. Use a recent version of CPython; at least 3.5, but ideally 3.6 or
+    later.
+
+ 2. Use Visual Studio 2015 or the standalone build tools for Visual
+    Studio 2017 (or later).
+
+ 3. Compile both CPython and GPGME with these bindings using the tools
+    selected in step 2.
+
+ 4. Ignore MingW, Msys2 and the official CPython binary installers.
+
+ 5. Be thankful the answer to this question wasn't simply to say
+    something like, “install Linux” or “install FreeBSD” (or even
+    Apple's OS X).
+
 
 *** CFFI is the Best™ and GPGME should use it instead of SWIG
     :PROPERTIES: