Pandoc auto-markup attempt

gistfile1.txt

<p>Plug-in coding conventions</p>
<p>To ensure custom plug-ins work well with the core toolkit code and
remain compatible with future releases, the DITA Open Toolkit project
recommends that plug-ins use modern development practices and common
coding patterns.</p>
<p>Best practices</p>
<p>Adhering to certain development practices will properly isolate your
code from that of DITA Open Toolkit. This will make it easier to you to
upgrade to new versions of DITA-OT when they are released.</p>
<ul>
<li>Use a properly-constructed DITA-OT plug-in.</li>
<li>Use a version control system to store your code.</li>
<li>Store the source code of your plug-ins outside of the DITA-OT
installation directory, and add the repository location to the list of
plug-in directories defined in the plugindirsentry of the
configuration.properties file.</li>
<li>Never modify any of the core DITA-OT code.</li>
</ul>
<p>Tip: You may want to set the permissions on default plug-in
directories such asorg.dita.pdf2 to “read-only” to ensure that you do
not accidentally modify the files within as you develop your customized
plug-in.</p>
<ul>
<li>Avoid copying entire DITA-OT files into your customization plug-in.
When you only copy the attribute sets and templates that you need to
override, there is less risk of impact from new features or fixes in the
base code, making your code more stable and easier to upgrade between
releases.</li>
<li>If you only need to change a few attribute sets and templates, you
may prefer to store your overrides in custom.xsl files, or a simple
folder hierarchy within your custom plug-in.</li>
<li>In cases that require substantial customizations, you may prefer to
organize the files in a folder structure that mimics the hierarchy of
the default plug-in you are customizing. This facilitates comparisons
with the default settings in the base plug-in and makes it easier to
migrate your changes to new toolkit versions. See PDF plug-in structure
for information on the files in the base PDF plug-in.</li>
<li>Upgrade your customization plug-in to new versions of DITA-OT
regularly. Do not wait through several major releases before
upgrading.</li>
</ul>
<p>Use a custom namespace</p>
<p>For XSLT customizations, use a custom namespace for any modified
template modes, template names, attribute sets, functions, and
variables. This helps to clarify which portions of the code are specific
to your customizations, and serves to isolate your changes in the event
that items with the same name are added to the base plug-ins in the
future. For example, instead of creating a template named searchbar, use
something likecorp:searchbar instead. This ensures that if future
versions of DITA-OT add a searchbartemplate, your custom version will be
unaffected.</p>
<p>Instead of:</p>
<p><xsl:template name="searchbar"/></p>
<p>use:</p>
<p><xsl:template name="corp:searchbar"/></p>
<p>Upgrade stylesheets to XSLT 2.0</p>
<p>The Saxon project has announced plans to remove XSLT 1.0 support from
the Saxon-HE library that ships with DITA-OT: …we’re dropping XSLT 1.0
backwards compatibility mode from Saxon-HE, and hope to eliminate it
entirely in due course.</p>
<p>https://www.xml.com/news/release-saxon-98/</p>
<p>DITA-OT 3.0 and 3.0.1 included Saxon-HE 9.8.0.5, which rejects XSLT
stylesheets that specifyversion=“1.0”. Plug-ins with XSLT templates
specifying version 1.0 will fail with the message “XSLT 1.0
compatibility mode is not available in this configuration.”</p>
<p>To resolve this issue, change any occurrences of
<xsl:stylesheet version="1.0"> in custom plug-in stylesheets to at least
<xsl:stylesheet version="2.0">.</p>
<p>Tip: DITA-OT 3.0.2 includes Saxon-HE 9.8.0.7, which restores XSLT 1.0
backwards-compatibility mode, but the DITA Open Toolkit project
recommends upgrading all stylesheets to XSLT 2.0 to ensure plug-ins
remain compatible with future versions of DITA-OT and Saxon-HE.</p>
<p>Use custom <pipeline> elements</p>
In Ant scripts, use the XSLT module from DITA-OT instead of Ant’s
built-in <xslt> or
<style>
<p>tasks.</p>
<p>The XSLT module allows access to DITA-OT features like using the job
configuration to select files in the temporary folder based on file
metadata and custom XSLT extension functions.</p>
<p>Important: Future versions of DITA-OT may switch to a new XML
resolver or in-memory storage features that are not supported by Ant’s
XSLT task. To ensure compatibility with future releases, plug-ins should
replace these constructs with custom <pipeline>elements.</p>
<p>Instead of:</p>
<p><xslt style="${dita.plugin.example.dir}/custom.xsl"
      basedir="${dita.temp.dir}"
      destdir="${dita.output.dir}"
      includesfile="${dita.temp.dir}/${fullditatopicfile}"/> use:
<pipeline> <xslt style="${dita.plugin.example.dir}/custom.xsl"
        destdir="${dita.output.dir}"> <ditafileset format="dita" />
</xslt> </pipeline></p>
<p>Use the plug-in directory property</p>
<p>In Ant scripts, always refer to files in other plug-ins using the
dita.plugin.plugin-id.dirproperty.</p>
<p>Instead of:</p>
<p><property name="base" location="../example/custom.xsl"/></p>
<p>use:</p>
<p><property name="base" location="${dita.plugin.example.dir}/custom.xsl"/></p>
<p>This fixes cases where plug-ins are installed to custom plug-in
directories or the plug-in folder name doesn’t match the plug-in ID.</p>
<p>Tip: For details, see Referencing files from other plug-ins.</p>
<p>Use the plugin URI scheme</p>
<p>In XSLT, use the plugin URI scheme in <xsl:import> and <xsl:include>
to reference files in other plug-ins.</p>
<p>Instead of:</p>
<p><xsl:import href="../../org.dita.base/xsl/common/output-message.xsl"/></p>
<p>use:</p>
<p><xsl:import href="plugin:org.dita.base:xsl/common/output-message.xsl"/></p>
<p>As with the plug-in directory property in Ant, this allows plug-ins
to resolve to the correct directory even when a plug-in moves to a new
location. The plug-in is referenced using the syntax
plugin:plugin-id:path/within/plugin/file.xsl.</p>
<p>Tip: For details, see Referencing files from other plug-ins.</p>
<p>Use <ditafileset> to select files</p>
<p>In Ant scripts, use <ditafileset> to select resources in the
temporary directory.</p>
<p>For example, to select all images referenced by input DITA files,
instead of:</p>
<p><copy todir="${copy-image.todir}"> <fileset dir="${user.input.dir}">
<includes name="*.jpg"/> <includes name="*.jpeg"/>
<includes name="*.png"/> <includes name="*.gif"/>
<includes name="*.svg"/> </fileset> </copy></p>
<p>use:</p>
<p><copy todir="${copy-image.todir}"> <ditafileset format="image" />
</copy></p>
<p>The <ditafileset> resource collection can be used to select different
types of files.</p>
<p>Example Description</p>
<p><ditafileset format="dita"/> Selects all DITA topics in the temporary
directory. <ditafileset format="ditamap"/> Selects all DITA maps in the
temporary directory. <ditafileset format="image"/> Selects images of all
known types in the temporary directory.</p>
<p>Match elements with their <span class="citation"
data-cites="class">@class</span> attribute</p>
<p>Use <span class="citation" data-cites="class">@class</span>
attributes to match elements in XPATH expressions instead of element
names.</p>
<p>For example, instead of: <xsl:template match="p"/> use:
<xsl:template match="*[contains(@class,' topic/p ')]"/>
Specialization-aware processing uses these classes to distinguish the
general class of elements to which the current element belongs.</p>
<p>Tip: Matching classes instead of elements ensures that the expression
also applies to any specialized elements as well as to their more
general ancestors. This means you can define new markup without
necessarily requiring new processing rules.</p>
<p>Validating plug-ins</p>
<p>DITA-OT includes a RELAX NG schema file that can be used to validate
the plugin.xml files that define the capabilities of each plug-in.</p>
<p>To ensure the syntax of your custom plug-in is correct, include an
<?xml-model?> processing instruction at the beginning of the plugin.xml
file, immediately after the XML prolog:</p>
<?xml-model href="https://www.dita-ot.org/rng/plugin.rnc" type="application/relax-ng-compact-syntax"?>
<p>If your authoring environment does not apply this schema
automatically, point your editor to dita-ot-dir/resources/plugin.rnc to
associate the schema with your plug-in file.</p>