Documentation Source Files

From f0063afa71bc7e71f19d174acc2fde26f0c11850 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Tue, 15 May 2018 13:13:16 +1000 Subject: docs: python bindings HOWTO - DITA XML version * Due to the org-babel bug which breaks Python source code examples beyond the most simple snippets, ported the HOWTO to a source format which I *know* for sure won't break it. * Details of the org-mode bug is in https://dev.gnupg.org/T3977 * DITA project uses DITA-OT 2.x (2.4 or 2.5, IIRC) with support for DITA 1.3. * source files were written with oXygenXML Editor 20.0, hence the oXygenXML project file in the directory; however only the .ditamap and .dita files are required to generate any output with the DITA-OT. Signed-off-by: Ben McGinnes --- .../python/docs/dita/howto/part01/docs-source.dita | 27 ++++++++++++++++++++++ lang/python/docs/dita/howto/part01/examples.dita | 11 +++++++++ .../docs/dita/howto/part01/introduction.dita | 11 +++++++++ .../docs/dita/howto/part01/python2-vs-python3.dita | 22 ++++++++++++++++++ 4 files changed, 71 insertions(+) create mode 100644 lang/python/docs/dita/howto/part01/docs-source.dita create mode 100644 lang/python/docs/dita/howto/part01/examples.dita create mode 100644 lang/python/docs/dita/howto/part01/introduction.dita create mode 100644 lang/python/docs/dita/howto/part01/python2-vs-python3.dita (limited to 'lang/python/docs/dita/howto/part01') diff --git a/lang/python/docs/dita/howto/part01/docs-source.dita b/lang/python/docs/dita/howto/part01/docs-source.dita new file mode 100644 index 00000000..f0a8affa --- /dev/null +++ b/lang/python/docs/dita/howto/part01/docs-source.dita @@ -0,0 +1,27 @@ + + + + + Documentation Source Files + +

Unlike all other documentation in the GnuPG Project, including the initial version of + this HOWTO, this version was not written in Emacs Org-Mode. Nor was it written in + LaTeX, Texinfo or even directly in HTML. Instead it was written using the Darwin Information + Typing Architecture (DITA) XML.

This was done for two main reasons:

A bug in either Org-Mode or Babel prevented the more complex examples included in the + HOWTO from displaying correctly.
To demonstrate some of the advantages of DITA XML over existing documentation + productionsoftware used in the project (particularly Texinfo and LaTeX).

The XML format definitely supports displaying all the more complex Python code correctly, + as well as being designed to produce standards compliant print and HTML output. Whereas + currently the existing tools utilised by the GnuPG Project can't display the example code in + a way which would actually pass the project's own git commit ruleset.

+ + + diff --git a/lang/python/docs/dita/howto/part01/examples.dita b/lang/python/docs/dita/howto/part01/examples.dita new file mode 100644 index 00000000..afa66197 --- /dev/null +++ b/lang/python/docs/dita/howto/part01/examples.dita @@ -0,0 +1,11 @@ + + + + + Examples + +

All of the examples found in this document can be found as Python 3 scripts in the + lang/python/examples/howto directory.

+ + + diff --git a/lang/python/docs/dita/howto/part01/introduction.dita b/lang/python/docs/dita/howto/part01/introduction.dita new file mode 100644 index 00000000..7b18eb89 --- /dev/null +++ b/lang/python/docs/dita/howto/part01/introduction.dita @@ -0,0 +1,11 @@ + + + + + Introduction + +

This document provides basic instruction in how to use the GPGME Python bindings to + programmatically leverage the GPGME library.

+ + + diff --git a/lang/python/docs/dita/howto/part01/python2-vs-python3.dita b/lang/python/docs/dita/howto/part01/python2-vs-python3.dita new file mode 100644 index 00000000..97662764 --- /dev/null +++ b/lang/python/docs/dita/howto/part01/python2-vs-python3.dita @@ -0,0 +1,22 @@ + + + + + Python 2 vs. Python 3 + +

Though the GPGME Python bindings themselves provide support for both Python 2 and 3, + the focus is unequivocally on Python 3 and specifically from Python 3.4 and above. As a + consequence all the examples and instructions in this guide use Python 3 code.

Much of it will work with Python 2, but much of it also deals with Python 3 byte literals, + particularly when reading and writing data. Developers concentrating on Python 2.7, and + possibly even 2.6, will need to make the appropriate modifications to support the older + string and unicode types as opposed to bytes.

There are multiple reasons for concentrating on Python 3; some of which relate to the + immediate integration of these bindings, some of which relate to longer term plans for both + GPGME and the python bindings and some of which relate to the impending EOL period for + Python 2.7. Essentially, though, there is little value in tying the bindings to a version of + the language which is a dead end and the advantages offered by Python 3 over Python 2 make + handling the data types with which GPGME deals considerably easier.

+ + + -- cgit v1.2.3