2 files changed, 62 insertions, 3 deletions
diff --git a/lang/python/doc/rst/gpgme-python-howto.rst b/lang/python/doc/rst/gpgme-python-howto.rst
index 3750d9a1..1bd069ca 100644
--- a/lang/python/doc/rst/gpgme-python-howto.rst
+++ b/lang/python/doc/rst/gpgme-python-howto.rst
@@ -2048,6 +2048,10 @@ content as a byte object, the recipient key IDs and algorithms in
 ``result`` and the results of verifying any signatures of the data in
 ``verify_result``.
 
+If ``gpg.Context().decrypt(cfile, verify=False)`` is called instead,
+then ``verify_result`` will be returned as ``None`` and the rest remains
+as described here.
+
 .. _howto-basic-signing:
 
 Signing text and files
@@ -3099,11 +3103,11 @@ the author at any of the following URLs:
 -  `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 single file, AWS S3 no
-   SS) <http://files.au.adversary.org/crypto/gpgme-python-howto.html>`__
+   SSL) <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>`__
+   SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto/index.html>`__
 
 All of these draft versions except for one have been generated from this
 document via GNU Emacs `Org mode <https://orgmode.org/>`__ and `GNU
@@ -3135,12 +3139,24 @@ either of the following commands:
 
 In addition to these there is a significantly less frequently updated
 version as a HTML `WebHelp
-site <https://files.au.adversary.org/crypto/gpgme-python-howto/webhelp/index.html>`__
+site <https://files.au.adversary.org/crypto/gpgme-python/dita/webhelp/index.html>`__
 (AWS S3 SSL); generated from DITA XML source files, which can be found
 in `an alternative
 branch <https://dev.gnupg.org/source/gpgme/browse/ben%252Fhowto-dita/>`__
 of the GPGME git repository.
 
+Various generated output formats may occasionally be found in
+subdirectories of the
+`gpgme-python <https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python>`__
+directory. In particular within the
+`DITA <https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/dita>`__,
+`reStructuredText <https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/rst>`__
+and
+`Texinfo <https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/texinfo>`__
+subdirectories. The ``rst`` directory contains output files generated
+with Sphix and may include a considerable number of its possible output
+formats.
+
 These draft editions are not official documents and the version of
 documentation in the master branch or which ships with released versions
 is the only official documentation. Nevertheless, these draft editions
diff --git a/lang/python/doc/rst/maintenance-mode.rst b/lang/python/doc/rst/maintenance-mode.rst
index 770fbe84..6f770bc6 100644
--- a/lang/python/doc/rst/maintenance-mode.rst
+++ b/lang/python/doc/rst/maintenance-mode.rst
@@ -88,3 +88,46 @@ 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).
+
+.. _docs:
+
+Documentation formats
+---------------------
+
+The documentation has been written in Org mode for GNU Emacs, with both
+Texinfo and reStructuredText formats generated from that. The Texinfo
+files are intended for use with the rest of the GnuPG documentation;
+while the reStructuredText files are intended for use with Docutils and
+Sphinx, as with other Python projects.
+
+.. _sphinx-made-epubs-suck:
+
+Cautionary Notes regarding Sphinx and EPUB
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Though Python\'s Docutils in conjunction with Sphinx is capable of
+generating some very useful HTML sites, as proven by `Read the
+Docs <https://readthedocs.org/>`__ and the `Python
+documentation <https://docs.python.org/>`__, there are a number of
+output formats it does not handle well. At the top of the list of things
+it manages to break so atrociously as to be embarassing is the `EPUB
+3 <http://idpf.org/epub>`__ format.
+
+The automatically generated EPUB of the CPython documentation always
+contains hundreds of validation errors and even the modest amount of
+documentation here `produced a
+file <https://files.au.adversary.org.s3.amazonaws.com/crypto/gpgme-python/rst/epub/GPGMEPythonBindings.epub>`__
+with approximately thirty validation errors. As the volume of
+documentation content increases, so does the induced errors. Whereas
+Texinfo doesn\'t produce EPUB output at all, nor does Org-mode.
+
+Should there ever be genuine demand for this format, lodge a `feature
+request <https://dev.gnupg.org/maniphest/task/edit/form/4/>`__ case
+marked for `my <https://dev.gnupg.org/p/BenM/>`__ attention. The means
+of generating such files flawlessly is already available, but is not yet
+part of the GnuPG build system. Nor is it integrated with a means of
+converting Org mode input files to the relevant base format
+automatically, as can already be done when converting Org to
+reStructuredText or Org to Texinfo. As a certain amount of work would be
+required to get it done, there would need to be clear demand for that
+work to be done.