[git] GPGME - branch, master, updated. gpgme-1.12.0-102-g7c63bfe
by Ben McGinnes
cvs at cvs.gnupg.org
Mon Dec 10 06:11:14 CET 2018
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GnuPG Made Easy".
The branch, master has been updated
via 7c63bfe4ab434b61a871aec4bc1d0a05b4c068e6 (commit)
from 78f6291a3bf56769f53af66fe39718ddd2d74bf2 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 7c63bfe4ab434b61a871aec4bc1d0a05b4c068e6
Author: Ben McGinnes <ben at adversary.org>
Date: Mon Dec 10 16:05:14 2018 +1100
python: docs updates
* Multiple updates, expanding on the Windows installation issues.
* Also adding to the new maintenance mode reference document.
* Includes content relating to the resolution of T4271 and T4191.
Tested-by: Ben McGinnes <ben at adversary.org>
Signed-off-by: Ben McGinnes <ben at adversary.org>
diff --git a/lang/python/doc/rst/gpgme-python-howto.rst b/lang/python/doc/rst/gpgme-python-howto.rst
index 3750d9a..1bd069c 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 770fbe8..6f770bc 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.
diff --git a/lang/python/doc/src/gpgme-python-howto b/lang/python/doc/src/gpgme-python-howto
index c6b0002..9820d86 100644
--- a/lang/python/doc/src/gpgme-python-howto
+++ b/lang/python/doc/src/gpgme-python-howto
@@ -2095,6 +2095,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.
+
** Signing text and files
:PROPERTIES:
@@ -3163,9 +3167,9 @@ 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 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)]]
+- [[http://files.au.adversary.org/crypto/gpgme-python-howto.html][GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no SSL)]]
- [[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)]]
+- [[http://files.au.adversary.org/crypto/gpgme-python-howto/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 GNU Emacs [[https://orgmode.org/][Org mode]] and [[https://www.gnu.org/software/texinfo/][GNU Texinfo]]. Though it is
@@ -3194,10 +3198,16 @@ commands:
#+END_SRC
In addition to these there is a significantly less frequently updated
-version as a HTML [[https://files.au.adversary.org/crypto/gpgme-python-howto/webhelp/index.html][WebHelp site]] (AWS S3 SSL); generated from DITA XML
+version as a HTML [[https://files.au.adversary.org/crypto/gpgme-python/dita/webhelp/index.html][WebHelp site]] (AWS S3 SSL); generated from DITA XML
source files, which can be found in [[https://dev.gnupg.org/source/gpgme/browse/ben%252Fhowto-dita/][an alternative branch]] of the GPGME
git repository.
+Various generated output formats may occasionally be found in
+subdirectories of the [[https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python][gpgme-python]] directory. In particular within
+the [[https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/dita][DITA]], [[https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/rst][reStructuredText]] and [[https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/texinfo][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
diff --git a/lang/python/doc/src/maintenance-mode b/lang/python/doc/src/maintenance-mode
index 48c3d40..4b4e0fc 100644
--- a/lang/python/doc/src/maintenance-mode
+++ b/lang/python/doc/src/maintenance-mode
@@ -93,3 +93,43 @@ 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).
+
+
+** Documentation formats
+ :PROPERTIES:
+ :CUSTOM_ID: docs
+ :END:
+
+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.
+
+
+*** Cautionary Notes regarding Sphinx and EPUB
+ :PROPERTIES:
+ :CUSTOM_ID: sphinx-made-epubs-suck
+ :END:
+
+Though Python's Docutils in conjunction with Sphinx is capable of
+generating some very useful HTML sites, as proven by [[https://readthedocs.org/][Read the Docs]] and
+the [[https://docs.python.org/][Python documentation]], 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 [[http://idpf.org/epub][EPUB 3]] format.
+
+The automatically generated EPUB of the CPython documentation always
+contains hundreds of validation errors and even the modest amount of
+documentation here [[https://files.au.adversary.org.s3.amazonaws.com/crypto/gpgme-python/rst/epub/GPGMEPythonBindings.epub][produced a file]] 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 [[https://dev.gnupg.org/maniphest/task/edit/form/4/][feature
+request]] case marked for [[https://dev.gnupg.org/p/BenM/][my]] 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.
diff --git a/lang/python/doc/texinfo/gpgme-python-howto.texi b/lang/python/doc/texinfo/gpgme-python-howto.texi
index bfc42f3..420ea7d 100644
--- a/lang/python/doc/texinfo/gpgme-python-howto.texi
+++ b/lang/python/doc/texinfo/gpgme-python-howto.texi
@@ -2255,6 +2255,10 @@ content as a byte object, the recipient key IDs and algorithms in
@samp{result} and the results of verifying any signatures of the data in
@samp{verify_result}.
+If @samp{gpg.Context().decrypt(cfile, verify=False)} is called instead,
+then @samp{verify_result} will be returned as @samp{None} and the rest remains
+as described here.
+
@node Signing text and files
@section Signing text and files
@@ -3301,11 +3305,11 @@ from the author at any of the following URLs:
@item
@uref{https://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 SSL)}
@item
- at uref{http://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no SS)}
+ at uref{http://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no SSL)}
@item
@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
- at 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)}
+ at uref{http://files.au.adversary.org/crypto/gpgme-python-howto/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
@@ -3335,10 +3339,16 @@ pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto
@end example
In addition to these there is a significantly less frequently updated
-version as a HTML @uref{https://files.au.adversary.org/crypto/gpgme-python-howto/webhelp/index.html, WebHelp site} (AWS S3 SSL); generated from DITA XML
+version as a HTML @uref{https://files.au.adversary.org/crypto/gpgme-python/dita/webhelp/index.html, WebHelp site} (AWS S3 SSL); generated from DITA XML
source files, which can be found in @uref{https://dev.gnupg.org/source/gpgme/browse/ben%252Fhowto-dita/, an alternative branch} of the GPGME
git repository.
+Various generated output formats may occasionally be found in
+subdirectories of the @uref{https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python, gpgme-python} directory. In particular within
+the @uref{https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/dita, DITA}, @uref{https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/rst, reStructuredText} and @uref{https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/texinfo, Texinfo} subdirectories. The @samp{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
diff --git a/lang/python/doc/texinfo/maintenance-mode.texi b/lang/python/doc/texinfo/maintenance-mode.texi
index cf47f6f..9377bbb 100644
--- a/lang/python/doc/texinfo/maintenance-mode.texi
+++ b/lang/python/doc/texinfo/maintenance-mode.texi
@@ -29,6 +29,11 @@ Maintenance Mode from 2019
* Maintainer from 2019 onward::
* Using the Python Bindings from 2019 and beyond::
+* Documentation formats::
+
+Documentation formats
+
+* Cautionary Notes regarding Sphinx and EPUB::
@end detailmenu
@end menu
@@ -66,6 +71,7 @@ the bindings.
@menu
* Maintainer from 2019 onward::
* Using the Python Bindings from 2019 and beyond::
+* Documentation formats::
@end menu
@node Maintainer from 2019 onward
@@ -122,4 +128,42 @@ 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).
+ at node Documentation formats
+ at section 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.
+
+ at menu
+* Cautionary Notes regarding Sphinx and EPUB::
+ at end menu
+
+ at node Cautionary Notes regarding Sphinx and EPUB
+ at subsection 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 @uref{https://readthedocs.org/, Read the Docs} and
+the @uref{https://docs.python.org/, Python documentation}, 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 @uref{http://idpf.org/epub, EPUB 3} format.
+
+The automatically generated EPUB of the CPython documentation always
+contains hundreds of validation errors and even the modest amount of
+documentation here @uref{https://files.au.adversary.org.s3.amazonaws.com/crypto/gpgme-python/rst/epub/GPGMEPythonBindings.epub, produced a file} 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 @uref{https://dev.gnupg.org/maniphest/task/edit/form/4/, feature
+request} case marked for @uref{https://dev.gnupg.org/p/BenM/, my} 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.
+
@bye
\ No newline at end of file
-----------------------------------------------------------------------
Summary of changes:
lang/python/doc/rst/gpgme-python-howto.rst | 22 +++++++++++--
lang/python/doc/rst/maintenance-mode.rst | 43 ++++++++++++++++++++++++
lang/python/doc/src/gpgme-python-howto | 16 +++++++--
lang/python/doc/src/maintenance-mode | 40 ++++++++++++++++++++++
lang/python/doc/texinfo/gpgme-python-howto.texi | 16 +++++++--
lang/python/doc/texinfo/maintenance-mode.texi | 44 +++++++++++++++++++++++++
6 files changed, 172 insertions(+), 9 deletions(-)
hooks/post-receive
--
GnuPG Made Easy
http://git.gnupg.org
More information about the Gnupg-commits
mailing list