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:

  1. A bug in either Org-Mode or Babel prevented the more complex examples included in the HOWTO from displaying correctly while also retaining syntax highlighting.
  2. To demonstrate some of the advantages of DITA XML over existing documentation production software used in the project (particularly Texinfo and LaTeX).

The XML format definitely supports displaying all the more complex Python code correctly with syntax highlighting, 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.