diff options
Diffstat (limited to 'lang/python/doc/src')
| -rw-r--r-- | lang/python/doc/src/gpgme-python-howto | 16 | ||||
| -rw-r--r-- | lang/python/doc/src/maintenance-mode | 40 |
2 files changed, 53 insertions, 3 deletions
diff --git a/lang/python/doc/src/gpgme-python-howto b/lang/python/doc/src/gpgme-python-howto index c6b00027..9820d86b 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 48c3d409..4b4e0fca 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. |