diff options
Diffstat (limited to 'lang/python/doc/texinfo/maintenance-mode.texi')
| -rw-r--r-- | lang/python/doc/texinfo/maintenance-mode.texi | 44 |
1 files changed, 44 insertions, 0 deletions
diff --git a/lang/python/doc/texinfo/maintenance-mode.texi b/lang/python/doc/texinfo/maintenance-mode.texi index cf47f6f3..9377bbb2 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). +@node Documentation formats +@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. + +@menu +* Cautionary Notes regarding Sphinx and EPUB:: +@end menu + +@node Cautionary Notes regarding Sphinx and EPUB +@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 |