2018-05-15 03:13:16 +00:00
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
|
|
<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
|
2018-05-15 03:50:14 +00:00
|
|
|
<dita xml:lang="en-GB">
|
2018-05-15 03:13:16 +00:00
|
|
|
<topic id="topic_nb3_hrx_5db">
|
|
|
|
|
<title>Documentation Source Files</title>
|
|
|
|
|
<body>
|
2018-05-15 11:26:30 +00:00
|
|
|
<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>
|
2018-05-15 03:13:16 +00:00
|
|
|
<p>This was done for two main reasons:</p>
|
|
|
|
|
<p>
|
|
|
|
|
<ol id="ol_k3b_wrx_5db">
|
2018-05-15 11:26:30 +00:00
|
|
|
<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.</li>
|
2018-05-15 03:13:16 +00:00
|
|
|
<li>To demonstrate some of the advantages of DITA XML over existing documentation
|
2018-05-15 11:26:30 +00:00
|
|
|
production software used in the project (particularly Texinfo and LaTeX).</li>
|
2018-05-15 03:13:16 +00:00
|
|
|
</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>
|
