python: post installer docs fix script

* Moved post_installer.py into the examples/howto/ directory.
* Added instructions for its use to the Python Bindings HOWTO.
* Ran it as intended from the lang/python/ directory in order to both
  prove it works and quickly and easily get the updated howto
  replicated.  Also to fix all those .texi files.

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

10 files changed, 53 insertions, 15 deletions

diff --git a/lang/python/doc/rst/gpgme-python-howto.rst b/lang/python/doc/rst/gpgme-python-howto.rst
index 4146e374..5f8bcd5d 100644
--- a/lang/python/doc/rst/gpgme-python-howto.rst
+++ b/lang/python/doc/rst/gpgme-python-howto.rst
@@ -683,6 +683,21 @@ on the system and version of Python in use. Another option is to run the
 command ``python3 -m virtualenv /path/to/install/virtual/thingy``
 instead.
 
+.. _snafu-docs:
+
+Post installation
+~~~~~~~~~~~~~~~~~
+
+Following installation it is recommended to move the
+``post_installer.py`` script from the ``lang/python/examples/howto/``
+directory to the ``lang/python/`` directory and run it. This will fix or
+restore files needed by Sphinx which may be removed during a
+distribution build for release. It will also generate reST files from
+Org mode files with Pandoc and generate Texinfo files from Org mode
+files with GNU Emacs and Org mode (in batch mode). Additionally it will
+fix the UTF-8 declaration line in the Texinfo files (Emacs expects
+\"UTF-8\" to be \"utf-8\").
+
 .. _howto-fund-a-mental:
 
 Fundamentals
diff --git a/lang/python/doc/rst/index.rst b/lang/python/doc/rst/index.rst
index 9c4f0f7a..3ff34fc4 100644
--- a/lang/python/doc/rst/index.rst
+++ b/lang/python/doc/rst/index.rst
@@ -7,7 +7,7 @@ GPGME Python Bindings
 =====================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :caption: Contents:
 
 Contents
@@ -20,11 +20,3 @@ Contents
 
 -  `What Was New <what-was-new>`__
 -  `GPGME Python Bindings HOWTO <gpgme-python-howto>`__
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/lang/python/doc/src/gpgme-python-howto b/lang/python/doc/src/gpgme-python-howto
index 6569806b..c63191b4 100644
--- a/lang/python/doc/src/gpgme-python-howto
+++ b/lang/python/doc/src/gpgme-python-howto
@@ -705,6 +705,22 @@ the command =python3 -m virtualenv /path/to/install/virtual/thingy=
 instead.
 
 
+*** Post installation
+    :PROPERTIES:
+    :CUSTOM_ID: snafu-docs
+    :END:
+
+Following installation it is recommended to move the
+=post_installer.py= script from the =lang/python/examples/howto/=
+directory to the =lang/python/= directory and run it.  This will fix
+or restore files needed by Sphinx which may be removed during a
+distribution build for release.  It will also generate reST files from
+Org mode files with Pandoc and generate Texinfo files from Org mode
+files with GNU Emacs and Org mode (in batch mode).  Additionally it
+will fix the UTF-8 declaration line in the Texinfo files (Emacs
+expects "UTF-8" to be "utf-8").
+
+
 * Fundamentals
   :PROPERTIES:
   :CUSTOM_ID: howto-fund-a-mental
diff --git a/lang/python/doc/texinfo/gpgme-python-howto.texi b/lang/python/doc/texinfo/gpgme-python-howto.texi
index fac0056f..9f53aa5a 100644
--- a/lang/python/doc/texinfo/gpgme-python-howto.texi
+++ b/lang/python/doc/texinfo/gpgme-python-howto.texi
@@ -81,6 +81,7 @@ Known Issues
 * Won't Work With Windows::
 * CFFI is the Best™ and GPGME should use it instead of SWIG::
 * Virtualised Environments::
+* Post installation::
 
 Fundamentals
 
@@ -511,6 +512,7 @@ they be encountered.
 * Won't Work With Windows::
 * CFFI is the Best™ and GPGME should use it instead of SWIG::
 * Virtualised Environments::
+* Post installation::
 @end menu
 
 @node Breaking Builds
@@ -883,6 +885,19 @@ on the system and version of Python in use.  Another option is to run
 the command @samp{python3 -m virtualenv /path/to/install/virtual/thingy}
 instead.
 
+@node Post installation
+@subsection Post installation
+
+Following installation it is recommended to move the
+@samp{post_installer.py} script from the @samp{lang/python/examples/howto/}
+directory to the @samp{lang/python/} directory and run it.  This will fix
+or restore files needed by Sphinx which may be removed during a
+distribution build for release.  It will also generate reST files from
+Org mode files with Pandoc and generate Texinfo files from Org mode
+files with GNU Emacs and Org mode (in batch mode).  Additionally it
+will fix the UTF-8 declaration line in the Texinfo files (Emacs
+expects "UTF-8" to be "utf-8").
+
 @node Fundamentals
 @chapter Fundamentals
 
@@ -3465,4 +3480,4 @@ WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
 implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 PURPOSE.
 
-@bye
+@bye
\ No newline at end of file
diff --git a/lang/python/doc/texinfo/index.texi b/lang/python/doc/texinfo/index.texi
index 0f4863c7..95c27c22 100644
--- a/lang/python/doc/texinfo/index.texi
+++ b/lang/python/doc/texinfo/index.texi
@@ -57,4 +57,4 @@ GPGME Python Bindings
 @uref{gpgme-python-howto, GPGME Python Bindings HOWTO}
 @end itemize
 
-@bye
+@bye
\ No newline at end of file
diff --git a/lang/python/doc/texinfo/maintenance-mode.texi b/lang/python/doc/texinfo/maintenance-mode.texi
index d38875bd..92457190 100644
--- a/lang/python/doc/texinfo/maintenance-mode.texi
+++ b/lang/python/doc/texinfo/maintenance-mode.texi
@@ -166,4 +166,4 @@ 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
+@bye
\ No newline at end of file
diff --git a/lang/python/doc/texinfo/short-history.texi b/lang/python/doc/texinfo/short-history.texi
index cbb13f31..d27f68d9 100644
--- a/lang/python/doc/texinfo/short-history.texi
+++ b/lang/python/doc/texinfo/short-history.texi
@@ -221,4 +221,4 @@ For those using Python 2, there is essentially no harm in using
 this module, but it may lack a number of more recent features
 added to GPGME.
 
-@bye
+@bye
\ No newline at end of file
diff --git a/lang/python/doc/texinfo/what-is-new.texi b/lang/python/doc/texinfo/what-is-new.texi
index 5abc87a6..406ab2f7 100644
--- a/lang/python/doc/texinfo/what-is-new.texi
+++ b/lang/python/doc/texinfo/what-is-new.texi
@@ -91,4 +91,4 @@ repetition if a key includes a user ID matching the hexadecimal
 value of a key ID.
 @end itemize
 
-@bye
+@bye
\ No newline at end of file
diff --git a/lang/python/doc/texinfo/what-was-new.texi b/lang/python/doc/texinfo/what-was-new.texi
index 29ea847c..3f0ad9d9 100644
--- a/lang/python/doc/texinfo/what-was-new.texi
+++ b/lang/python/doc/texinfo/what-was-new.texi
@@ -157,4 +157,4 @@ the time).
 Cleaned up a lot of things under the hood.
 @end itemize
 
-@bye
+@bye
\ No newline at end of file
diff --git a/lang/python/post_installer.py b/lang/python/examples/howto/post_installer.py
index b9fd36f2..b9fd36f2 100755
--- a/lang/python/post_installer.py
+++ b/lang/python/examples/howto/post_installer.py