blob: 7c90b59c9907dec6ae8023167f261fbca053626d (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<dita xml:lang="en-GB">
<topic id="topic_nb3_hrx_5db">
<title>Documentation Source Files</title>
<body>
<p>Unlike all other documentation in the <xref href="https://gnupg.org" format="html"
scope="external">GnuPG Project</xref>, 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 <xref href="https://dev.gnupg.org/T3977" format="html" scope="external">bug</xref>
in either Org-Mode or Babel prevented the more complex examples included in the HOWTO
from displaying correctly while also retaining syntax highlighting.</li>
<li>To demonstrate some of the advantages of DITA XML over existing documentation
production software 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
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.</p>
<p> </p>
</body>
</topic>
</dita>
|
