gpgme/lang/python/docs/dita/howto/part01/docs-source.dita

<?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>
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 <ben@adversary.org> 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">`
docs: python bindings howto * Added metadata, author info, version number and xml:lang data. 2018-05-15 03:50:14 +00:00			`<dita xml:lang="en-GB">`
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 <ben@adversary.org> 2018-05-15 03:13:16 +00:00			`<topic id="topic_nb3_hrx_5db">`
			`<title>Documentation Source Files</title>`
			`<body>`
docs: python bindings howto DITA * Fixed a typo, added a couple of links. 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>`
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 <ben@adversary.org> 2018-05-15 03:13:16 +00:00			`<p>This was done for two main reasons:</p>`
			`<p>`
			`<ol id="ol_k3b_wrx_5db">`
docs: python bindings howto DITA * Fixed a typo, added a couple of links. 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`
python bindings howto: dita version * Drafts of instructions for exporting public and secret keys ready, along in addition to the code. 2018-06-28 08:02:43 +00:00			`from displaying correctly while also retaining syntax highlighting.</li>`
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 <ben@adversary.org> 2018-05-15 03:13:16 +00:00			`<li>To demonstrate some of the advantages of DITA XML over existing documentation`
docs: python bindings howto DITA * Fixed a typo, added a couple of links. 2018-05-15 11:26:30 +00:00			`production software used in the project (particularly Texinfo and LaTeX).</li>`
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 <ben@adversary.org> 2018-05-15 03:13:16 +00:00			`</ol>`
			`</p>`
python bindings howto: dita version * Drafts of instructions for exporting public and secret keys ready, along in addition to the code. 2018-06-28 08:02:43 +00:00			`<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>`
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 <ben@adversary.org> 2018-05-15 03:13:16 +00:00			`<p> </p>`
			`</body>`
			`</topic>`
			`</dita>`