python: docs

* Found a bug in org-mode's export to texinfo function which will
  require either manual modification of each file or a customs sed run
  over the generated files for all updates.
* Manually updated the current files for now, but will need to add
  some post-install processing scripts for future use (I already have
  some of these for my specific setup, they just need to be made a
  little more generic and platform independent for here).

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

1 files changed, 36 insertions, 0 deletions

diff --git a/lang/python/doc/src/gpgme-python-howto b/lang/python/doc/src/gpgme-python-howto
index bee661b5..6569806b 100644
--- a/lang/python/doc/src/gpgme-python-howto
+++ b/lang/python/doc/src/gpgme-python-howto
@@ -3254,6 +3254,37 @@ line at the top of each file and have had their =.org= file extensions
 dropped in order to make scripted generation of output formats easier
 and not require renaming files post-conversion.
 
+Due to a bug in Org mode's texinfo conversion method, the recommended
+steps for generating the Texinfo files for all the files in the
+=lang/python/doc/src/= directory are as follows:
+
+#+BEGIN_SRC shell
+  for x in * ; do
+      emacs $x --batch -f org-texinfo-export-to-texinfo --kill
+      cat $x.texi | sed -e 's/@documentencoding UTF-8/@documentencoding utf-8/g' > ../texinfo/$x.texi
+      pandoc -f org -t rst+smart -o ../rst/$x.rst $x
+  done ;
+  rm -fv *.texi
+  cd ../texinfo
+  mkdir info
+  mkdir html
+  for x in *.texi ; do
+      makeinfo -v $x
+      makeinfo --html --no-split $x
+  done ;
+  mv *.info info/
+  mv *.html html/
+#+END_SRC
+
+This code snippet includes the generation of the reStructuredText
+files and would be expected to be run from the =doc/src/= directory
+containing the Org mode source files.  It also assumes that the
+commands are being run on POSIX compliant systems with basic tools
+like sed, the Bourne shell and GNU Emacs[fn:6] available.  The code
+snippet also includes the steps for generating the Emacs Info files
+and HTML files from the Texinfo files.  Using reStructuredText files
+with Sphinx is best left for the documentation of that project.
+
 In addition to these there is a significantly less frequently updated
 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
@@ -3319,3 +3350,8 @@ restricted servers which only advertise either HTTP or HTTPS end
 points and not HKP or HKPS end points must still be identified as as
 HKP or HKPS within the Python Code.  The =hkp4py= module will rewrite
 these appropriately when the connection is made to the server.
+
+[fn:6] Okay, Emacs might not necessarily qualify as a basic tool, but
+it is common enough that having it installed on a system isn't too
+great an expectation, nor is it difficult to add to most POSIX
+systems, even if the users of those systems do not personally use it.