Conditional processing and reuse

June 21, 2004 © 2004 IBM Corporation

Conditional processing and reuse

Managing differences and commonalities in topics and maps

DITA conditional processing and reuse © 2004 IBM Corporation2

Overview

Conditional processing– Metadata attributes

– Filtering

– Flagging Content reuse

– conref attribute

– Current and proposed rules Substitution

– Substituting common files

– Manage volatility Summary


Conditional processing: input

Metadata attributes set in source:

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>


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


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.


A note on filtering for media

No media attribute in topics, since they are supposed to be media-neutral

Outputclass attribute provides semantic distinctions for processes to use, when specialization not yet available

Maps do have media attributes, since they often encode media-specific structures


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.


Content reuse

conref attribute on most elements in topic and map

Point from one element to another to copy the target's content:

 ... Here's the data to copy

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


Example: source

content.dita:<topic id="content">

<title>Conref test: content</title><body>

Putting an ID on an element makes it reusable.</body>

</topic>

reference.dita:<topic id="reference">

<title>Conref test: reference</title><body>

</body>

</topic>


Example: output


Future enhancement possibilities

Better judging of domain matchingCurrently 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 mapsEven 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 flyshould 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>


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


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


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


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 contentLet the build process select the right map

Use common files for volatile phrase-level contentLet each reusing context manage its own common file

Use predictable reuse patterns wherever possibleEasier for people to pick up maintenance of your content

Avoid spaghetti conref and christmas-tree conditionsJust because you can do something doesn't mean you should

Think of those who will come after you


Example: more differences than commonalities

<topic id="abc"><body>

Here's what to do for AHere's what to do for BHere's what to do for CAnd here's what applies to all of them

</body></topic>


Example: from filtering to sharing-------------------------------------------------------------------------<topic id="a">

<body>Here's what to do for A

</body></topic>-------------------------------------------------------------------------<topic id="b">

<body>Here's what to do for B

</body></topic>-------------------------------------------------------------------------<topic id="c">

<body>Here's what to do for C

</body></topic>-------------------------------------------------------------------------<topic id="shared">

<body>And here's what applies to all of them

</body></topic>


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.


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.


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


Summary

Manage differences with metadata attributes

Manage commonalities with conref

Manage volatility with substitution

Don't overmanage


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

Date post:	31-Dec-2015
Category:	Documents
Upload:	maxwell-franklin
View:	44 times
Download:	2 times

Conditional processing and reuse

Documents