DITA Configuration

ePublisher's DITA support allows for user-defined mappings between complex DITA element hierarchies and ePublisher styles. This configuration can be controlled at the source DITA map level or at the ePublisher Project and Target level. Finally, through the use of ePublisher Stationery, configurations can be maintained and deployed throughout your organization to all ePublisher Express and ePublisher AutoMap users.

Structured Elements and Styles

Before diving into the ePublisher configuration file, users should first understand how ePublisher processes DITA content.

At this time, ePublisher is a style-centric publishing system. The focus is on the layout and appearance of elements, not on structure.

Consider the following expanded DITA map: 

  <map title="Styles and Structure">
    <topic>
      <title>Title Styles</title>
      <body>
        <section>
          <title>Section Title</title>
          <p>Sections are really great!</p>
        </section>
      </body>

      <topic>
        <title>Task Titles Triumph!</title>
        <body>
          <context>
            <p>Everything should be considered in context.</p>
          </context>
        </body>
      </topic>
    </topic>
  </map>

In this map, there are three <title> elements: 

  <map> <topic> <title>
  <map> <topic> <body> <section> <title>
  <map> <topic> <topic> <title>

and two <p> elements: 

  <map> <topic> <body> <section> <p>
  <map> <topic> <topic> <body> <context> <p>

In style based output formats (such as HTML and RTF), we might choose to treat certain elements with the same style. Here is one possible mapping:

Structure

Style

<map> <topic> <title>

Title

<map> <topic> <body> <section> <title>

Heading 1, Section 1

<map> <topic> <topic> <title>

Heading 1

<map> <topic> <body> <section> <p>

Section Body

<map> <topic> <topic> <body> <context> <p>

Topic Body

This mapping preserves all structure information one-for-one.

Now try "down mapping", converting multiple structures to a single style:

Structure

Style

<map> <topic> <title>

Title

<map> <topic> <body> <section> <title>

Heading 1

<map> <topic> <topic> <title>

Heading 1

<map> <topic> <body> <section> <p>

Body

<map> <topic> <topic> <body> <context> <p>

Body

Written another way:

Structure

Style

<map> <topic> <title>

Title

<title>[count(ancestor::<topic> or ancestor:<section>) > 1]

Heading 1

<p>

Body

Still further rewrites:

Structure

Style

<title>[count(ancestor::<topic>) = 1]

Title

<title>[count(ancestor::<topic> or ancestor:<section>) = 2]

Heading 1

<p>

Body

Mapping with XPath

This style mapping we have created seems nice, but ePublisher can't use it yet. Unless we convert it something ePublisher understands. In this case, we will convert the mapping to XPath expressions.

XPath Expression

Style

title[count(ancestor::topic) = 1]

Title

title[count(ancestor::topic or ancestor:section) = 2]

Heading 1

p

Body

That looks pretty good. Except DITA supports a little thing call "specialization". It means that I can give elements different names, yet process them the same way.

For example, the DITA element <task> is a specialization of the <topic> element. This is represented in DITA through DTDs in a class element. So when you see: 

  <topic>
    ...
  </topic>

  <task>
    ...
  </task>

DITA sees: 

  <topic class="- topic/topic ">
    ...
  </topic>

  <task class="- topic/topic task/task ">
    ...
  </task>

If you want to process a <task> element the same way as a <topic> element, you simply check for " topic/topic " in the @class attribute. And XPath expression to perform this test is: 

  *[contains(@class, ' topic/topic ')]

Different behaviors for <task> elements can be introduced by checking for the " task/task " class substring: 

  *[contains(@class, ' task/task ')]

Now let's rewrite our mapping to support DITA specialization:

XPath Expression

Style

*[contains(@class, ' topic/title ')][count(ancestor::*[contains(@class, ' topic/topic ')]) = 1]

Title

*[contains(@class, ' topic/title ')][count(ancestor::*[contains(@class, ' topic/topic ') or contains(@class, ' topic/section ')]) = 2]

Heading 1

*[contains(@class, ' topic/p ')]

Body

Wow! That's a pretty long-winded way of saying that! But, hey, now we get to use DITA, DITA Specialization, and ePublisher!

Configuring ePublisher

Great, now we know how to translate structures to styles. And we even know a technology, XPath, that can help us do that. What else does ePublisher need?

It needs the ePublisher DITA configuration file default.wwconfig of course! 

<?xml version="1.0" encoding="UTF-8"?>
<DitaConfiguration version="1.0" xmlns="urn:WebWorks-Dita-Configuration-Schema"
                                 xmlns:wwditaconfig="urn:WebWorks-Dita-Configuration-Schema"
                                 xmlns:wwdoc="urn:WebWorks-Document-Schema"
                                 xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 <Types>
  <Type match="//*[(contains(@class, ' map/topicref ')) and (string-length(@navtitle) &gt; 0)]" value="Paragraph" />
 </Types>

 <Styles>
  <Style match="//*[contains(@class, ' map/topicref ')]">
   <wwditaconfig:Head name="Topic Reference" />
  </Style>
 </Styles>
</DitaConfiguration>

ePublisher DITA Configuration File Structure

The ePublisher DITA configuration file allows ePublisher to answer the following questions:

  1. What style based objects does this structure represent? A paragraph? A character? A container? A table?
  2. What style name should be used for this structure?

Types

First, the <Types> section identifies what the structure represents. From our example, we would define the following types:

XPath Expression

Type

*[contains(@class, ' topic/title ')][count(ancestor::*[contains(@class, ' topic/topic ')]) = 1]

Paragraph

*[contains(@class, ' topic/title ')][count(ancestor::*[contains(@class, ' topic/topic ') or contains(@class, ' topic/section ')]) = 2]

Paragraph

*[contains(@class, ' topic/p ')]

Paragraph

*

Structure

Since all of the <title> elements are really just paragraphs, we can simplify this to:

XPath Expression

Type

*[contains(@class, ' topic/title ')]

Paragraph

*[contains(@class, ' topic/p ')]

Paragraph

*

Structure

Okay, so everything that is either a <title> element or a <p> element becomes a "Paragraph" and the rest become "Structure".

What if we had listed the "Structure" one first?

XPath Expression

Type

*

Structure

*[contains(@class, ' topic/title ')]

Paragraph

*[contains(@class, ' topic/p ')]

Paragraph

That would be bad, because everything in the document would be treated as "Structure"!

So why allow people to do this kind of thing? Well, perhaps we'd like to get crazy and convert DITA titles <section> elements to character styles:

XPath Expression

Type

*[contains(@class, ' topic/title ')][count(contains(@class, ' topic/section ')]) &gt; 0]

Character

*[contains(@class, ' topic/title ')]

Paragraph

*[contains(@class, ' topic/p ')]

Paragraph

*

Structure

We can be as specific as required and ePublisher will pick the first, best match.

Now, we'll return to our earlier (read simplier) example and translate it into ePublisher's required configuration file language:

XPath Expression

Type

*

Structure

*[contains(@class, ' topic/title ')]

Paragraph

*[contains(@class, ' topic/p ')]

Paragraph 

 <Types>
  <Type match="//*[contains(@class, ' topic/title ')]" value="Paragraph" />
  <Type match="//*[contains(@class, ' topic/p ')]" value="Paragraph" />
 </Types>

Styles

We've already covered how to map structure to styles, so now we just need to show how this information is represented in the ePublisher configuration file:

XPath Expression

Style

*[contains(@class, ' topic/title ')][count(ancestor::*[contains(@class, ' topic/topic ')]) = 1]

Title

*[contains(@class, ' topic/title ')][count(ancestor::*[contains(@class, ' topic/topic ') or contains(@class, ' topic/section ')]) = 2]

Heading 1

*[contains(@class, ' topic/p ')]

Body 

 <Styles>
  <Style match="//*[contains(@class, ' topic/title ')][count(ancestor::*[contains(@class, ' topic/topic ')]) = 1]">
   <wwditaconfig:Head name="Title" />
  </Style>

  <Style match="//*[contains(@class, ' topic/title ')][count(ancestor::*[contains(@class, ' topic/topic ') or contains(@class, ' topic/section ')]) = 2]">
   <wwditaconfig:Head name="Heading 1" />
  </Style>

  <Style match="//*[contains(@class, ' topic/p ')]">
   <wwditaconfig:Head name="Body" />
  </Style>
 </Styles>

Types and Styles Together

Perhaps now our little configuration file example will make a bit more sense: 

<?xml version="1.0" encoding="UTF-8"?>
<DitaConfiguration version="1.0" xmlns="urn:WebWorks-Dita-Configuration-Schema"
                                 xmlns:wwditaconfig="urn:WebWorks-Dita-Configuration-Schema"
                                 xmlns:wwdoc="urn:WebWorks-Document-Schema"
                                 xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 <Types>
  <Type match="//*[contains(@class, ' topic/title ')]" value="Paragraph" />
  <Type match="//*[contains(@class, ' topic/p ')]" value="Paragraph" />
 </Types>

 <Styles>
  <Style match="//*[contains(@class, ' topic/title ')][count(ancestor::*[contains(@class, ' topic/topic ')]) = 1]">
   <wwditaconfig:Head name="Title" />
  </Style>

  <Style match="//*[contains(@class, ' topic/title ')][count(ancestor::*[contains(@class, ' topic/topic ') or contains(@class, ' topic/section ')]) = 2]">
   <wwditaconfig:Head name="Heading 1" />
  </Style>

  <Style match="//*[contains(@class, ' topic/p ')]">
   <wwditaconfig:Head name="Body" />
  </Style>
 </Styles>
</DitaConfiguration>

Overriding DITA Configurations

DITA configuration files can be overriding in four locations:

  1. Per source DITA map.
  2. Per project.
  3. Per format.
  4. Per target.

Per source DITA Map

If you have a DITA map file named mymap.ditamap, you can create a ePublisher configuration file with the base name of the original and use the .wwconfig extension.

You directory goes from: 

  mymap.ditamap

to: 

  mymap.ditamap
  mymap.wwconfig

NOTE:

This particular configuration file need only contain overrides or changes from the base default.wwconfig file.

Per project

Users can change the configuration of all DITA files in a project, across formats and targets, by creating a new default.wwconfig file in this location: 

  <project directory>
    Formats
      Adapters
        xml
          scripts
            dita
              default.wwconfig

Per format

Users can change the configuration of all DITA files in a project for a particular format by creating a new default.wwconfig file in this location: 

  <project directory>
    Formats
      <Format Name>
        Adapters
          xml
            scripts
              dita
                default.wwconfig

Per target

Users can change the configuration of all DITA files in a project for a single target by creating a new default.wwconfig file in this location: 

  <project directory>
    Targets
      <Target Name>
        Adapters
          xml
            scripts
              dita
                default.wwconfig

Crazy Configurations

<Not yet complete.>

Some tips from experience

By Zoë Lawson

Occasionally, a <Style> may contain some wwdoc elements inside of the wwditaconfig:Head elements. These wwdoc elements provide formatting elements that override the Style Designer. For example, from the Style element which matches codeblock: 

<wwditaconfig:Head name="{$
}">
     <wwdoc:Style>
          <wwdoc:Attribute name="font-family" value="Courier" />
          <wwdoc:Attribute name="white-space" value="pre" />
     </wwdoc:Style>
</wwditaconfig:Head>

The wwdoc:Attribute element defines that no matter what settings you have in the Style designer, always use Courier font and something that defines using ‘pre’-formatted white space. You may want to comment out the wwdoc:Style attributes to return control to the Style Designer.

The <wwdoc:Style> elements should not override Style Designer settings. Rather, they just set the default values to be used for that paragraph/character style. So, you should still be able to disable them, change them, etc., through the Style Designer.

Zoë, can you attach a test case showing this behavior?

-- BenAllums


:) :)) :( ;) :\ |) X-( B) Markup
Using all 4 scenarios I always end up with an empty CHM (f.e.) file that reads "please map toc styles". Did anyone test this with a fresh, clean project that has only DITA source files in it? TIA, Franz-Josef
Posted by p5B13BECD at 2007-11-12 16:25:31 X

Permalinks/DITA_Configuration (last edited 2013-11-12 21:42:19 by LaurenLever)