## page was renamed from HelpCenter/Tips/DITA/Release Specific/ePublisher 9.3/DITA_Configuration
## page was renamed from HelpCenter/Tips/DITA/ePublisher_9_3/DITA_Configuration
## page was renamed from HelpCenter/Tips/DITA/ePublisher 9 3/Element Mapping Configuration
= 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:
{{{
}}}
In this map, there are three {{{}}} 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) > 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?
1. 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 ')]) > 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.
1. Per project.
1. Per format.
1. 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
}}}
||<#ee9999>NOTE: ||<#ee9999>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
----
<<PageComment2(markup=1, newerfirst=1, rows=4, cols=80, articleview=1, tablewidth=500, notify=1)>>