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:param name="cssResourceName" select="'xhtml.css'"/>
    
      <xsl:template match="*[contains(@class,' sample-d/kbd ')]">
        <tt>
          <xsl:call-template name="commonAttributes"/>
          <xsl:apply-templates/>
        </tt>
      </xsl:template>
    
      <xsl:template match="*[contains(@class,' sample-d/time ')]">
        <span>
          <xsl:call-template name="commonAttributes"/>
          <xsl:apply-templates/>
        </span>
      </xsl:template>
    
    </xsl:stylesheet>
    Note that the XSLT template called commonAttributes adds a class="kbd" attribute to the generated <tt> element. Similarly, it adds a class="time" attribute to the <span> element generated for the <time> element. So how to style the generated <tt class="kbd"> and <span class="time">?
    1. Copy ditac_install_dir/xsl/xhtml/resources/ and ditac_install_dir/xsl/xhtml/resources.list to your_plugin_dir/xsl/xhtml/.
    2. Copy the following xhtml.css CSS stylesheet to your_plugin_dir/xsl/xhtml/resources/.
      @import url(base.css);
      
      .kbd {
          font-family: monospace;
          font-size: 90%;
          border: 1px solid #C0C0C0;
          border-radius: 3px;
          -moz-border-radius: 3px;
          -webkit-border-radius: 3px;
          padding: 2px;
          background-color: #F0F0F0;
      }
      
      .time {
          background-color: #FFFFCC;
          padding: 2px;
      }
    3. Append the following line to your_plugin_dir/xsl/xhtml/resources.list.
      resources/xhtml.css
    4. Declare that the default CSS stylesheet is xhtml.css and not stock base.css. This is done by using XSLT stylesheet parameter cssResourceName.
      <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:param name="cssResourceName" select="'xhtml.css'"/>
        ...
  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