Part II, Chapter 11. Extensive customization

Chapter 11. Extensive customization

In order to extensively customize the output of ditac, you need to learn how it works.

Basically, this means that you'll have to understand the contents of the ditac_lists.ditac_list file and the .ditac files, which are generated by the ditac preprocessor.

An extensive customization works exactly like a simple one:

Create a custom XSLT 2.0 stylesheet which imports the stock one.
Redefine one or more attribute sets and/or one or more templates in the custom XSLT 2.0 stylesheet.

The only difference is that this time, you need to know exactly what is the format of the files you are going to transform. The bad news first: the ditac XSLT 2.0 stylesheets do not transform plain DITA files. They transform .ditac files, which are fully preprocessed DITA files. Now, the good news: .ditac files mainly contains DITA elements and because the ditac preprocessor performs all the grunt work beforehand, .ditac files are really straightforward to transform.

In fact, transforming .ditac files rather than plain DITA files allows to concentrate on creating great-looking output.

§ How it works

The ditac preprocessor generates a single ditac_lists.ditac_list file and one or more .ditac files⁽¹⁾ out of the source DITA files.

Figure 11-1. The intermediate files generated by the ditac preprocessor

Then, each .ditac file, which mainly contains fully preprocessed DITA topics, is transformed in turn by the ditac XSLT 2.0 stylesheets.

The ditac_lists.ditac_list file, which contains useful information about the overall DITA document being converted, is not directly transformed by the ditac XSLT 2.0 stylesheets. Instead, when needed to, the ditac XSLT 2.0 stylesheets query the ditac_lists.ditac_list file in order to generate optional items. Example: number topics, tables, figures, etc, when parameter number='XXX' has been specified.

It is possible to examine the contents of the ditac_lists.ditac_list file and those of the .ditac files by specifying the -preprocess command-line option. Example:

$ ditac -preprocess \
    -v -chunk single \
    -images img -p xsl-resources-directory res \
    out/manual.html manual.ditamap

§ Contents of a `.ditac` file

The root element of a .ditac file is <ditac:chunk>. A <ditac:chunk> element may have the following child elements (in any order and in any number):

<ditac:titlePage>

This empty placeholder element means: generate a ``title page'' section here.

<ditac:toc>

This empty placeholder element means: generate a Table of Contents section here.

<ditac:figureList>

This empty placeholder element means: generate a List of Figures section here.

<ditac:tableList>

This empty placeholder element means: generate a List of Tables section here.

<ditac:exampleList>

This empty placeholder element means: generate a List of Examples section here.

<ditac:equationList>

This empty placeholder element means: generate a List of Equations section here.

<ditac:indexList>

This empty placeholder element means: generate an Index section here.

A DITA topic of any kind

A fully preprocessed topic. This topic is guaranteed not to contain nested topics.

<ditac:flags-block>

<ditac:flags-inline>

Wrapper elements used to implement flagging in ditac. Flagging is specified by the means of a conditional processing profile (a .ditaval file). See also the -filter command-line option.

A DITA block element which supports all flagging features⁽²⁾ is wrapped in a <ditac:flags-block> element having flagging attributes such as @color, @text-decoration, @change-bar-placement, etc.
A DITA inline element which supports all flagging features⁽³⁾ is wrapped in a <ditac:flags-inline> element having flagging attributes such as @color, @text-decoration, @startImage, etc.
Any other DITA element is considered not to support all flagging features and as such, is given flagging attributes like @ditac:flags-color, @ditac:flags-background-color, @ditac:flags-font-weight, etc, rather than being wrapped in a <ditac:flags-block> or <ditac:flags-inline> element.

More formally, the content model of <ditac:chunk> is specified by the schema/ditac.rnc

RELAX NG grammar.

Example:

<ditac:chunk xmlns:ditac="http://www.xmlmind.com/ditac/schema/ditac"
             xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/">
  <ditac:titlePage/>
  <ditac:toc/>
  <topic class="- topic/topic "
         domains="(topic ui-d) (topic hi-d) (topic pr-d) (topic sw-d)
                 (topic ut-d) (topic indexing-d)"
         id="introduction" ditaarch:DITAArchVersion="1.1">
    <title class="- topic/title ">Introduction</title>
    .
    .
    .  
  </topic>
  <topic class="- topic/topic " id="I_2yl4p_">
    <title class="- topic/title ">Using XMLmind DITA Converter</title>
  </topic>
  <task class="- topic/topic task/task "
        domains="(topic ui-d) (topic hi-d) (topic pr-d) (topic sw-d)
                 (topic ut-d) (topic indexing-d)"
        id="install" ditaarch:DITAArchVersion="1.1">
    <title class="- topic/title ">Installing XMLmind DITA Converter</title>
    .
    .
    .
  </task>
  .
  .
  .
  <ditac:indexList/>
</ditac:chunk>

Important

The DITA topics contained in a .ditac file are fully preprocessed. What does this mean? Basically that they are ready to be transformed without further efforts:

Conref inclusions have been processed.
Unspecified attributes having default values have been added to the elements. Example: a <p> element becomes <p class="- topic/p ">.
Elements now have a ``flat'', globally unique, ID. Example: the @id attribute of this <title> element <topic id="introduction"><title id="start"> becomes id="introduction__start".
The @href attribute of <xref>, <link>, <image>, <svgref>, <mathmlref> elements now point to the (future) output files. Example: the @href attribute of this <xref> element <xref href="intro.dita#introduction/start"> becomes href="userguide-1.html#introduction__start".
Some text may have been added to empty <xref> and <link> elements.
The <reltable> elements of the DITA map have been converted to <related-links> sections or to extra <link> elements.
Filtered elements have been removed. Flagged elements have been wrapped in a <ditac:flags> element.

§ Contents of the `ditac_lists.ditac_list` file

The root element of the ditac_lists.ditac_list file is <ditac:lists>. A <ditac:lists> element may have the following child elements (in this exact order and in this exact number):

<ditac:chunkList>

A <ditac:chunkList> contains a <ditac:chunk> element for each .ditac file. A <ditac:chunk> element may be seen as the manifest of a .ditac file.

Example:

<ditac:chunkList>
  <ditac:chunk file="manual.html">
    <ditac:titlePage/>
    <ditac:toc/>
    <ditac:topic id="introduction" number="bookabstract.1"
                 role="bookabstract" title="Introduction"/>
    .
    .
    .
    <ditac:topic id="limitations" number="appendix.1" role="appendix"
                 title="Limitations and implementation specificities"/>
    <ditac:indexList/>
  </ditac:chunk>
</ditac:chunkList>

<ditac:titlePage>

Contains all the DITA elements needed to generate the ``title page'' section of a document. This element exists but is empty if the DITA document being converted has no title and no metadata (e.g. <topicmeta>/<autor>, <bookmeta>/<publisherinformation>, etc).

Example:

<ditac:titlePage>
  <title class="- topic/title ">XMLmind DITA Converter Manual</title>
  <bookmeta class="- map/topicmeta bookmap/bookmeta ">
    <authorinformation class="+ topic/author xnal-d/authorinformation ">
    .
    .
    .
    <critdates class="- topic/critdates ">
      <created class="- topic/created " date="September 17, 2009"/>
    </critdates>
  </bookmeta>
</ditac:titlePage>

<ditac:frontmatterTOC>

<ditac:toc>

<ditac:backmatterTOC>

Contains all the information needed to generate Table of Contents section of a document.

Example:

<ditac:toc>
  <ditac:tocEntry file="manual.html" id="I_2yl4p_" number="part.1"
                  role="part" title="Using XMLmind DITA Converter">
    <ditac:tocEntry file="manual.html" id="install"
                    number="part.1 chapter.1" role="chapter"
                    title="Installing XMLmind DITA Converter">
    .
    .
    .  
    </ditac:tocEntry>
  </ditac:tocEntry>
  <ditac:tocEntry file="manual.html" id="limitations" number="appendix.1"
                  role="appendix"
                  title="Limitations and implementation specificities"/>
</ditac:toc>

<ditac:figureList>

Contains all the information needed to generate the List of Figures section of a document. This element exists but is empty if the DITA document being converted contains no <fig> elements having a <title> child element.

Example:

<ditac:figureList>
  <ditac:figure file="manual.html" id="xsltParams__page_areas"
                number="part.1 chapter.4 figure.1" title="Page areas"/>
  <ditac:figure file="manual.html" id="howItWorks__I_6gb2s_"
                number="part.2 chapter.3 figure.1" 
                title="The intermediate files generated by
                       the ditac preprocessor"/>
</ditac:figureList>

<ditac:tableList>

Contains all the information needed to generate the List of Tables section of a document. This element exists but is empty if the DITA document being converted contains no <table> elements having a <title> child element.

Example:

<ditac:tableList>
  <ditac:table file="manual.html"
               id="quickStart__supported_filename_extensions"
               number="part.1 chapter.2 table.1"
               title="Supported filename extensions"/>
  <ditac:table file="manual.html"
               id="quickStart__supported_output_formats"
               number="part.1 chapter.2 table.2"
               title="Supported output formats"/>
</ditac:tableList>

<ditac:exampleList>

Contains all the information needed to generate the List of Examples section of a document. This element exists but is empty if the DITA document being converted contains no <example> elements having a <title> child element.

Example:

<ditac:exampleList>
  <ditac:example file="topicAAA.htm" id="topicAAA__I_6wcr3_"
                 number="part.1 example.1" title="Example AAA.1"/>
  .
  .
  .
  <ditac:example file="topicHHH.htm" id="topicHHH__exampleHHH.2"
                 number="appendix.2 example.2" title="Example HHH.2"/>
</ditac:exampleList>

<ditac:equationList>

Contains all the information needed to generate the List of Examples section of a document. This element exists but is empty if the DITA document being converted contains no <equation-figure> elements having a <title> child element.

Example:

<ditac:equationList>
  <ditac:equation file="part222.html" id="part222__first_equation" 
                  number="part.2 equation.1" title="First equation">
    <ditac:description>This is a short description of the first equation.
    It should be displayed in the <i class="+ topic/ph hi-d/i ">
    <b class="+ topic/ph hi-d/b ">List of
    Equations</b></i>.</ditac:description>
  </ditac:equation>
  .
  .
  .
  <ditac:equation file="trademarks.html" id="trademarks__I_qa9vmk_" 
                  number="equation.4" title="Second equation"/>
</ditac:equationList>

<ditac:indexList>

Contains all the information needed to generate the Index section of a document. This element exists but is empty if the DITA document being converted contains no <indexterm> elements.

Example:

<ditac:indexList>
  <ditac:div title="A">
    <ditac:indexEntry term="appendix-number-format, parameter"
                      xml:id="I_hd1wr_">
      <ditac:indexAnchor file="manual.html" 
                         id="xsltParams__I_8bona_"
                         number="1"/>
    </ditac:indexEntry>
    <ditac:indexEntry sortAs="automap" term="-automap, option"
                      xml:id="I_2gud9_">
      <ditac:indexAnchor file="manual.html"
                         id="commandLine__I_5x8va_"
                         number="1"/>
    </ditac:indexEntry>
  </ditac:div>
  .
  .
  .
  <ditac:div title="X">
    .
    .
    .
    <ditac:indexEntry sortAs="xslt" term="-xslt, option"
                      xml:id="I_atn9k_">
      <ditac:indexAnchor file="manual.html"
                         id="commandLine__I_cu3ew_"
                         number="1"/>
      <ditac:indexAnchor file="manual.html"
        id="customAttributeSet__I_gis5b_" number="2"/>
      <ditac:indexAnchor file="manual.html"
                         id="specialize__I_11514_"
                         number="3"/>
      <ditac:indexSeeAlso ref="I_bhy05_" term="-t, option"/>
      <ditac:indexSeeAlso ref="I_f1jh_" term="-xslt, option"/>
    </ditac:indexEntry>
  </ditac:div>
</ditac:indexList>

More formally, the content model of <ditac:lists> is specified by the schema/ditac_lists.rnc

RELAX NG grammar.

Currently the ditac_lists.ditac_list file is used to generate:

the ``title page'' section of a document;
the Table of Contents section of a document;
the List of Figures, List of Tables, List of Examples, List of Equations sections of a document;
the Index section of a document;
the navigation icons in a multi-page HTML document;
all the files (project.hhp, toc.hhc, etc) required by the HTML Help system;
all the files (jhelpset.hs, jhelpmap.jhm, etc) required by the Java™ Help system.

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

Chapter 11. Extensive customization

§ How it works

Figure 11-1. The intermediate files generated by the ditac preprocessor

§ Contents of a .ditac file

Important

§ Contents of the ditac_lists.ditac_list file

§ Contents of a `.ditac` file

§ Contents of the `ditac_lists.ditac_list` file