f0063afa71
* 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 <ben@adversary.org>
28 lines
1.4 KiB
XML
28 lines
1.4 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
|
|
<dita>
|
|
<topic id="topic_nb3_hrx_5db">
|
|
<title>Documentation Source Files</title>
|
|
<body>
|
|
<p>Unlike all other documentation in the GnuPG Project, including the initial version of
|
|
this HOWTO, this version was <i>not</i> 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.</p>
|
|
<p>This was done for two main reasons:</p>
|
|
<p>
|
|
<ol id="ol_k3b_wrx_5db">
|
|
<li>A bug in either Org-Mode or Babel prevented the more complex examples included in the
|
|
HOWTO from displaying correctly.</li>
|
|
<li>To demonstrate some of the advantages of DITA XML over existing documentation
|
|
productionsoftware used in the project (particularly Texinfo and LaTeX).</li>
|
|
</ol>
|
|
</p>
|
|
<p>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.</p>
|
|
<p> </p>
|
|
</body>
|
|
</topic>
|
|
</dita>
|