A demonstration of DITA specialization
Download
Report
Transcript A demonstration of DITA specialization
Conditional processing and reuse
Managing differences and commonalities in topics and
maps
June 21, 2004
© 2004 IBM Corporation
Overview
Conditional processing
– Metadata attributes
– Filtering
– Flagging
Content reuse
– conref attribute
– Current and proposed rules
Substitution
– Substituting common files
– Manage volatility
Summary
2
DITA conditional processing and reuse
© 2004 IBM Corporation
Conditional processing: input
Metadata attributes set in source:
<p audience="administrator">Set the configuration options:
<ul>
<li product="extendedprod">Set foo to bar</li>
<li product="basicprod extendedprod">Set your blink rate</li>
<li>Do some other stuff</li>
<li platform="unix">Do a special thing on Unix systems</li>
</ul>
</p>
3
DITA conditional processing and reuse
© 2004 IBM Corporation
Conditional processing: output
Behavior set at build time (filter, flag):
<prop att="platform"
val="unix"
action="flag"
img="ngunix.gif" alt="Unix"/>
<prop att="product" val="extendedprod"
action="exclude"/>
Not supported in public package
4
DITA conditional processing and reuse
© 2004 IBM Corporation
Filtering
You can filter based on:
product
platform
audience
otherprops
Filtering rules:
If any one attribute has all values set to exclude, exclude the element
An element may have several metadata attributes, each with several
values. All the values in at least one of the attributes must be set to
exclude, or the content still applies to a valid context.
5
DITA conditional processing and reuse
© 2004 IBM Corporation
A note on filtering for media
No media attribute in topics, since they are supposed to be medianeutral
Outputclass attribute provides semantic distinctions for processes to
use, when specialization not yet available
Maps do have media attributes, since they often encode mediaspecific structures
6
DITA conditional processing and reuse
© 2004 IBM Corporation
Flagging
You can flag based on:
product
platform
audience
otherprops
rev
Flagging rules:
If any value of the specified attribute evaluates to flag, flag the element
An element may have several metadata attributes, with several values in
each. For each value set to flag, a flag is generated - unless the whole
element is being excluded, thanks to one of its attributes evaluating to
exclude.
7
DITA conditional processing and reuse
© 2004 IBM Corporation
Content reuse
conref attribute on most elements in topic and map
Point from one element to another to copy the target's content:
<p conref="abc.dita#mytopic/mypara"/>
...
<p id="mypara">Here's the data to copy</p>
Target element has to be the same type (not just element name but
class) and in a topic with the same domains (not just same content
but same content rules)
Reuse from topic to topic (across types is ok as long as it's an
element common to both) and from map to map
8
DITA conditional processing and reuse
© 2004 IBM Corporation
Example: source
content.dita:
<topic id="content">
<title>Conref test: content</title>
<body>
<p id="oho">Putting an ID on an element makes it reusable.</p>
</body>
</topic>
reference.dita:
<topic id="reference">
<title>Conref test: reference</title>
<body>
<p conref="content.dita#content/oho"/>
</body>
</topic>
9
DITA conditional processing and reuse
© 2004 IBM Corporation
Example: output
10
DITA conditional processing and reuse
© 2004 IBM Corporation
Future enhancement possibilities
Better judging of domain matching
Currently just compares domain attributes on content topic and referencing topic.
Should be more intelligent: see if the content topic allows the same or fewer
domains, compared to the referencing topic.
Metadata reuse across topics and maps
Even though the same metadata elements exist in both map and topic, cannot conref
from maps to topics or vice versa to share metadata.
(You can get a lot of reuse out of map processing in general without conref reuse,
however)
Generalization on the fly
should be able to reuse a specialized element from one of its ancestors, and
generalize the target at build time, eg
<li conref="#mytask/mystep"/>
<step id="mystep><cmd>Here's a step</cmd></step>
11
DITA conditional processing and reuse
© 2004 IBM Corporation
A note about processing pipelines
Current public package does conref and output in one pass
Works most of the time, except when there's an element in the
conref'd content that requires information about the topic it's in
Examples: generated anchors, numbering of figures
When the content in the conref'd element gets processed, the
template retrieves element from its real context, not its reusing
context - can create problems
Doing it in two passes is more cumbersome but more reliable
12
DITA conditional processing and reuse
© 2004 IBM Corporation
Content substitution
Use a common file for volatile elements like product name, user
interface labels
If your content ships with multiple products with minor variations in
UI, maintain multiple copies of the common file: one per product
At build time, substitute the common file with the values you want
13
DITA conditional processing and reuse
© 2004 IBM Corporation
Example
Source directory
Maintain different directories for different products, single directory for shared content
productA\common.dita
productB\common.dita
componentX\abc.dita, xyz.dita
Build directory:
At build time, copy source files from component plus common file from a product
directory:
productA\common.dita, abc.dita, xyz.dita
Output directory:
infocenter\abc.html, xyz.html
14
DITA conditional processing and reuse
© 2004 IBM Corporation
Some reuse strategies
If conditional processing in a topic gets too complicated, create
multiple topics with shared content
Let the map choose the right topic
If conditional processing in a map gets too complicated, create
multiple maps with shared content
Let the build process select the right map
Use common files for volatile phrase-level content
Let each reusing context manage its own common file
Use predictable reuse patterns wherever possible
Easier for people to pick up maintenance of your content
Avoid spaghetti conref and christmas-tree conditions
Just because you can do something doesn't mean you should
Think of those who will come after you
15
DITA conditional processing and reuse
© 2004 IBM Corporation
Example: more differences than commonalities
<topic id="abc">
<body>
<p product="A">Here's what to do for A</p>
<p product="B">Here's what to do for B</p>
<p product="C">Here's what to do for C</p>
<p>And here's what applies to all of them</p>
</body>
</topic>
16
DITA conditional processing and reuse
© 2004 IBM Corporation
Example: from filtering to sharing
------------------------------------------------------------------------<topic id="a">
<body>
<p>Here's what to do for A</p>
<p conref="shared.dita#shared/all"/>
</body>
</topic>
------------------------------------------------------------------------<topic id="b">
<body>
<p>Here's what to do for B</p>
<p conref="shared.dita#shared/all"/>
</body>
</topic>
------------------------------------------------------------------------<topic id="c">
<body>
<p>Here's what to do for C</p>
<p conref="shared.dita#shared/all"/>
</body>
</topic>
------------------------------------------------------------------------<topic id="shared">
<body>
<p id="all">And here's what applies to all of them</p>
</body>
</topic>
17
DITA conditional processing and reuse
© 2004 IBM Corporation
Example: with conditions moved into the map
<map id="abcmap">
<topicref product="A" href="a.dita"/>
<topicref product="B" href="b.dita"/>
<topicref product="C" href="c.dita"/>
</map>
If map was mostly conditional content, next step would be to create
separate maps for each product, and reuse by conref common
branches.
18
DITA conditional processing and reuse
© 2004 IBM Corporation
On the value of replacing conditions with conref
The strategy of replacing complex conditions with simple conref works
well for cases where you are doing lots of filtering, and different
teams are working on the same source. It separates concerns into
separate files, so that each team can update their content without
conflict with others.
The strategy would not work well for flagging cases, and would be less
necessary in a single-author environment.
19
DITA conditional processing and reuse
© 2004 IBM Corporation
Fundamental principles
Keep content ignorant of how it is reused
Keep control of reuse in the hands of the reuser
Manage context separately from content whenever possible
Conditional processing breaks that rule, so use it carefully
If maintenance of reuse costs more than it saves, just copy the
content and maintain it twice
20
DITA conditional processing and reuse
© 2004 IBM Corporation
Summary
Manage differences with metadata attributes
Manage commonalities with conref
Manage volatility with substitution
Don't overmanage
21
DITA conditional processing and reuse
© 2004 IBM Corporation
Further reading
Conditional processing note from the DITA forum, replicated to the
DITA TC list:
http://lists.oasis-open.org/archives/dita/200406/msg00032.html
SIGDOC paper on reuse by reference in DITA:
http://xml.coverpages.org/dita.html#Priestley-sigdoc2001
22
DITA conditional processing and reuse
© 2004 IBM Corporation