Chapter 10. Using ditac to convert documents conforming to a DITA specialization

We'll explain by example how to use ditac to convert documents conforming to a DITA specialization. Let's suppose we have a DITA specialization which adds <time> and <kbd> elements (similar to <time> Opens in new window and <kbd> Opens in new window HTML5 elements) topic contents. These elements are modeled as follows (see sample_plugin/dtd/sampleDomain.mod Opens in new window)
<!ENTITY % time "time">

<!ELEMENT time (#PCDATA | %text;)*>

<!ATTLIST time %univ-atts;                                  
               outputclass CDATA #IMPLIED>

<!ATTLIST time %global-atts;
               class CDATA "+ topic/ph sample-d/time ">

<!ATTLIST time %univ-atts;                                  
               datetime CDATA #IMPLIED>

<!ENTITY % kbd "kbd">

<!ELEMENT kbd (#PCDATA | %text;)*>

<!ATTLIST kbd %univ-atts;                                  
               outputclass CDATA #IMPLIED>

<!ATTLIST kbd %global-atts;
               class CDATA "+ topic/ph sample-d/kbd ">
All the example files of this tutorial have been packaged as a plug-in called "sample_plugin". They are found in directory sample_plugin/ Opens in new window. In order to give this plug-in a try, you'll have to copy directory sample_plugin/ to ditac_install_dir/plugin/.

About this task

Using ditac to convert documents conforming to a DITA specialization basically requires customizing the output of the tool using the same techniques as those explained in Chapter 9, Section 1 and Chapter 9, Section 2.

Procedure

  1. Create an XML catalog pointing to a local copy of your custom DTD. This file must be named catalog.xml and must be found in your plug-in directory.
    File sample_plugin/catalog.xml Opens in new window:
    <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"
             prefer="public">
    
      <public publicId="-//OASIS//DTD DITA Concept//EN"
              uri="dtd/concept.dtd"/>
    
      <public publicId="-//OASIS//DTD DITA Composite//EN"
              uri="dtd/ditabase.dtd"/>
    
      <public publicId="-//OASIS//DTD DITA General Task//EN"
              uri="dtd/generalTask.dtd"/>
    
      ...
    
    </catalog>
  2. Create a customization of ditac_install_dir/xsl/xhtml/xhtml.xsl as explained in Chapter 9, Section 2. This file must be found in your_plugin_dir/xsl/xhtml/xhtml.xsl in order to be used by ditac.
    File sample_plugin/xsl/xhtml/xhtml.xsl Opens in new window:
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                    xmlns="http://www.w3.org/1999/xhtml"
                    version="2.0">
    
      <xsl:import href="ditac-xsl:xhtml/xhtml.xsl"/>
    
      <xsl:template match="*[contains(@class,' sample-d/kbd ')]">
        <tt>
          <xsl:call-template name="commonAttributes"/>
          <xsl:apply-templates/>
        </tt>
      </xsl:template>
    
      ...
    
    </xsl:stylesheet>
    Note that the XSLT template called commonAttributes adds a class="kbd" attribute to the generated <tt> element. This makes it easy styling the generated <tt> element using the technique explained in Chapter 9, Section 1.
  3. Create a customization of ditac_install_dir/xsl/fo/fo.xsl as explained in Chapter 9, Section 2. This file must be found in your_plugin_dir/xsl/fo/fo.xsl in order to be used by ditac.
    File sample_plugin/xsl/fo/fo.xsl Opens in new window:
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                    xmlns:fo="http://www.w3.org/1999/XSL/Format"
                    version="2.0">
    
      <xsl:import href="ditac-xsl:fo/fo.xsl"/>
    
      <xsl:attribute-set name="kbd" use-attribute-sets="monospace-style">
        <xsl:attribute name="border">1px solid #C0C0C0</xsl:attribute>
        <xsl:attribute name="background-color">#F0F0F0</xsl:attribute>
        <xsl:attribute name="padding">0.25em</xsl:attribute>
      </xsl:attribute-set>
    
      <xsl:template match="*[contains(@class,' sample-d/kbd ')]">
        <fo:inline xsl:use-attribute-sets="kbd">
          <xsl:call-template name="commonAttributes"/>
          <xsl:apply-templates/>
        </fo:inline>
      </xsl:template>
    
      ...
    
    </xsl:stylesheet>
  4. Pass command-line option -plugin plugin_name to ditac in order to use the DTDs (or schemas) and the XSLT stylesheets found in your plug-in subdirectory, preferably to those found in ditac_install_dir/schema/ and in ditac_install_dir/xsl/.
    You'll find a sample DITA document making use of the custom <time> and <kbd> elements in sample_plugin/sample/sample.ditamap Opens in new window. You can convert this sample document to single-page XHTML and to PDF by running sample_plugin/sample/run.sh (sample_plugin\sample\run.bat on Windows):
    ../../../bin/ditac -plugin sample_plugin \
        out/sample.pdf sample.ditamap