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

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>

and <kbd>

HTML5 elements) topic contents. These elements are modeled as follows (see sample_plugin/dtd/sampleDomain.mod

)

<!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/

. 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

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

<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>

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

<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">?

Copy ditac_install_dir/xsl/xhtml/resources/ and ditac_install_dir/xsl/xhtml/resources.list to your_plugin_dir/xsl/xhtml/.

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;
}

Append the following line to your_plugin_dir/xsl/xhtml/resources.list.
```
resources/xhtml.css
```

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'"/>
  ...

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

<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>

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 . 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
```

‣ Parent topic: Part II. Customizing the output of XMLmind DITA Converter