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 <ben@adversary.org>
Signed-off-by: Ben McGinnes <ben@adversary.org>
This commit is contained in:
Ben McGinnes 2018-12-22 09:39:13 +11:00
parent dc5f416351
commit 06bca0eaa8
8 changed files with 193 additions and 51 deletions

View File

@ -2962,12 +2962,12 @@ information in Python.
group_lines = []
group_lists = []
for i in range(len(groups)):
group_lines.append(groups[i].split("="))
group_lists.append(groups[i].split("="))
for group in groups:
group_lines.append(group.split("="))
group_lists.append(group.split("="))
for i in range(len(group_lists)):
group_lists[i][1] = group_lists[i][1].split()
for glist in group_lists:
glist[1] = glist[1].split()
The result of that code is that ``group_lines`` is a list of lists where
``group_lines[i][0]`` is the name of the group and ``group_lines[i][1]``
@ -3135,8 +3135,6 @@ Copyright
Copyright © The GnuPG Project, 2018.
Copyright (C) The GnuPG Project, 2018.
.. _draft-editions:
Draft Editions of this HOWTO
@ -3145,25 +3143,39 @@ Draft Editions of this HOWTO
Draft editions of this HOWTO may be periodically available directly from
the author at any of the following URLs:
- `GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3
- `GPGME Python Bindings HOWTO draft (HTML 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
- `GPGME Python Bindings HOWTO draft (HTML single file, AWS S3 no
SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto.html>`__
- `GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3
- `GPGME Python Bindings HOWTO draft (HTML 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
- `GPGME Python Bindings HOWTO draft (HTML multiple files, AWS S3 no
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
Texinfo <https://www.gnu.org/software/texinfo/>`__. Though it is likely
that the specific
These draft versions have been generated from this document via GNU
Emacs `Org mode <https://orgmode.org/>`__ to ``.texi`` and `GNU
Texinfo <https://www.gnu.org/software/texinfo/>`__ to HTML. Though it is
likely that the specific
`file <https://files.au.adversary.org/crypto/gpgme-python-howto>`__
`version <http://files.au.adversary.org/crypto/gpgme-python-howto.org>`__
used will be on the same server with the generated output formats.
Occasionally I may include the Org mode generated XHTML versions:
- `GPGME Python Bindings HOWTO draft (HTML single file, AWS S3
SSL) <https://files.au.adversary.org/crypto/gpgme-python-howto.xhtml>`__
- `GPGME Python Bindings HOWTO draft (HTML single file, AWS S3 no
SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto.xhtml>`__
That XHTML version, however, is exported in a way which inherits a
colour scheme from `the author\'s Emacs
theme <https://github.com/holomorph/emacs-zenburn>`__ (which is a higher
contrast version of `Zenburn <http://kippura.org/zenburnpage/>`__ ported
by `Holomorph <https://github.com/holomorph>`__). So it\'s fine for
people who prefer dark themed web pages, but not so great for everyone
else.
The GNU Texinfo and reStructured Text versions ship with the software,
while the GNU Emacs Info verseion is generated from the Texinfo version
while the GNU Emacs Info version is generated from the Texinfo version
using GNU Texinfo or GNU Makeinfo. The Texinfo format is generated from
the original Org mode source file in Org mode itself either within GNU
Emacs or via the command line by invoking Emacs in batch mode:
@ -3173,15 +3185,51 @@ Emacs or via the command line by invoking Emacs in batch mode:
emacs gpgme-python-howto.org --batch -f org-texinfo-export-to-texinfo --kill
emacs gpgme-python-howto --batch -f org-texinfo-export-to-texinfo --kill
The reStructuredText format is also generated from the Org-mode source
The reStructuredText format is also generated from the Org mode source
file, except it is generated using `Pandoc <https://pandoc.org>`__ with
either of the following commands:
either of the following commands (depending on the filename):
.. code:: shell
pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto.org
pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto
Note that the Org mode source files are identified as such via a mode
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:
.. code:: 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/
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 [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 `WebHelp
site <https://files.au.adversary.org/crypto/gpgme-python/dita/webhelp/index.html>`__
@ -3199,8 +3247,9 @@ directory. In particular within the
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.
with Sphinx and may include a considerable number of its possible output
formats, but there are no guarantees as to how recent these are or even
if they are present.
These draft editions are not official documents and the version of
documentation in the master branch or which ships with released versions
@ -3258,3 +3307,9 @@ Footnotes
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.
.. [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.

View File

@ -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.

View File

@ -2,7 +2,7 @@
@c %**start of header
@setfilename gpgme-python-howto.info
@settitle GNU Privacy Guard (GnuPG) Made Easy Python Bindings HOWTO (English)
@documentencoding UTF-8
@documentencoding utf-8
@documentlanguage en
@c %**end of header
@ -3162,12 +3162,12 @@ groups = line.split(":")[-1].replace('"', '').split(',')
group_lines = []
group_lists = []
for i in range(len(groups)):
group_lines.append(groups[i].split("="))
group_lists.append(groups[i].split("="))
for group in groups:
group_lines.append(group.split("="))
group_lists.append(group.split("="))
for i in range(len(group_lists)):
group_lists[i][1] = group_lists[i][1].split()
for glist in group_lists:
glist[1] = glist[1].split()
@end example
The result of that code is that @samp{group_lines} is a list of lists where
@ -3338,8 +3338,6 @@ occur in versions which do not have the @samp{gpgme.version.is_beta} and
Copyright © The GnuPG Project, 2018.
Copyright (C) The GnuPG Project, 2018.
@node Draft Editions of this HOWTO
@section Draft Editions of this HOWTO
@ -3348,22 +3346,35 @@ from the author at any of the following URLs:
@itemize
@item
@uref{https://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 SSL)}
@uref{https://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (HTML single file, AWS S3 SSL)}
@item
@uref{http://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no SSL)}
@uref{http://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (HTML 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)}
@uref{https://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html, GPGME Python Bindings HOWTO draft (HTML multiple files, AWS S3 SSL)}
@item
@uref{http://files.au.adversary.org/crypto/gpgme-python-howto/index.html, GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 no SSL)}
@uref{http://files.au.adversary.org/crypto/gpgme-python-howto/index.html, GPGME Python Bindings HOWTO draft (HTML multiple files, AWS S3 no SSL)}
@end itemize
All of these draft versions except for one have been generated from
this document via GNU Emacs @uref{https://orgmode.org/, Org mode} and @uref{https://www.gnu.org/software/texinfo/, GNU Texinfo}. Though it is
These draft versions have been generated from this document via GNU
Emacs @uref{https://orgmode.org/, Org mode} to @samp{.texi} and @uref{https://www.gnu.org/software/texinfo/, GNU Texinfo} to HTML. Though it is
likely that the specific @uref{https://files.au.adversary.org/crypto/gpgme-python-howto, file} @uref{http://files.au.adversary.org/crypto/gpgme-python-howto.org, version} used will be on the same server
with the generated output formats.
with the generated output formats. Occasionally I may include the Org
mode generated XHTML versions:
@itemize
@item
@uref{https://files.au.adversary.org/crypto/gpgme-python-howto.xhtml, GPGME Python Bindings HOWTO draft (HTML single file, AWS S3 SSL)}
@item
@uref{http://files.au.adversary.org/crypto/gpgme-python-howto.xhtml, GPGME Python Bindings HOWTO draft (HTML single file, AWS S3 no SSL)}
@end itemize
That XHTML version, however, is exported in a way which inherits a
colour scheme from @uref{https://github.com/holomorph/emacs-zenburn, the author's Emacs theme} (which is a higher contrast
version of @uref{http://kippura.org/zenburnpage/, Zenburn} ported by @uref{https://github.com/holomorph, Holomorph}). So it's fine for people who
prefer dark themed web pages, but not so great for everyone else.
The GNU Texinfo and reStructured Text versions ship with the software,
while the GNU Emacs Info verseion is generated from the Texinfo
while the GNU Emacs Info version is generated from the Texinfo
version using GNU Texinfo or GNU Makeinfo. The Texinfo format is
generated from the original Org mode source file in Org mode itself
either within GNU Emacs or via the command line by invoking Emacs in
@ -3374,15 +3385,54 @@ emacs gpgme-python-howto.org --batch -f org-texinfo-export-to-texinfo --kill
emacs gpgme-python-howto --batch -f org-texinfo-export-to-texinfo --kill
@end example
The reStructuredText format is also generated from the Org-mode source
The reStructuredText format is also generated from the Org mode source
file, except it is generated using @uref{https://pandoc.org, Pandoc} with either of the following
commands:
commands (depending on the filename):
@example
pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto.org
pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto
@end example
Note that the Org mode source files are identified as such via a mode
line at the top of each file and have had their @samp{.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
@samp{lang/python/doc/src/} directory are as follows:
@example
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 example
This code snippet includes the generation of the reStructuredText
files and would be expected to be run from the @samp{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@footnote{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.} 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 @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
@ -3391,8 +3441,9 @@ 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.
directory contains output files generated with Sphinx and may include a
considerable number of its possible output formats, but there are no
guarantees as to how recent these are or even if they are present.
These draft editions are not official documents and the version of
documentation in the master branch or which ships with released
@ -3414,4 +3465,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

View File

@ -2,7 +2,7 @@
@c %**start of header
@setfilename index.info
@settitle GNU Privacy Guard (GnuPG) Made Easy Python Bindings
@documentencoding UTF-8
@documentencoding utf-8
@documentlanguage en
@c %**end of header
@ -57,4 +57,4 @@ GPGME Python Bindings
@uref{gpgme-python-howto, GPGME Python Bindings HOWTO}
@end itemize
@bye
@bye

View File

@ -2,7 +2,7 @@
@c %**start of header
@setfilename maintenance-mode.info
@settitle Maintenance Mode
@documentencoding UTF-8
@documentencoding utf-8
@documentlanguage en
@c %**end of header
@ -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

View File

@ -2,7 +2,7 @@
@c %**start of header
@setfilename short-history.info
@settitle A Short History of the GPGME bindings for Python
@documentencoding UTF-8
@documentencoding utf-8
@documentlanguage en
@c %**end of header
@ -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

View File

@ -2,7 +2,7 @@
@c %**start of header
@setfilename what-is-new.info
@settitle What's New in the GPGME Python Bindings and Documentation
@documentencoding UTF-8
@documentencoding utf-8
@documentlanguage en
@c %**end of header
@ -91,4 +91,4 @@ repetition if a key includes a user ID matching the hexadecimal
value of a key ID.
@end itemize
@bye
@bye

View File

@ -2,7 +2,7 @@
@c %**start of header
@setfilename what-was-new.info
@settitle What Was New in the GPGME Python Bindings and Documentation
@documentencoding UTF-8
@documentencoding utf-8
@documentlanguage en
@c %**end of header
@ -157,4 +157,4 @@ the time).
Cleaned up a lot of things under the hood.
@end itemize
@bye
@bye