customizing content with dita conditional text and xmetal

© 2010 JustSystems Canada, Inc.

Episode 9Customizing Content with DITA

Conditional Text

Su-Laine Yeo, Solutions Consultant

July 15, 2010

in 37 minutes

© 2010JustSystems Canada, Inc.2

• Conditional text with the DITA (Darwin Information Typing Architecture) XML language

• Practical steps for using conditional text in XMetaL Author Enterprise– Fairly detailed level, but not difficult– Specific examples

• Not using DITA? Keep watching, and also come back for our next 37-minute webinar on July 29

Today’s webinar


Customization and content reuse

• Reuse lets you deliver customized content without duplicating it

• Approaches:– Modular reuse:

• reusing whole topics• content references (conref) to reuse phrases and parts of

topics

– Conditional text


What is conditional text?

“Conditional text” refers to:

• The practice of marking up the content in a single source file, so you can create deliverables with different subsets of the file.

• The content that is marked up so you can filter it out of some deliverables. In DITA, conditional "text" can be words, images, tables, index markers, links, etc.


Conditional text

• Marking up the content in a single source file, so you can create deliverables with different subsets of the file.

• E.g. Windows-only content (Ctrl+S) and Macintosh-only content (Command+S)

Under the covers: XML

• A paragraph that is not conditional:

Press Ctrl+S.

• A paragraph that applies to the Windows platform only:

Press Ctrl+S.

attribute attribute value


Steps for using conditional text

1. Plan– Make a list of your audiences, products, and platforms that

require similar documentation

2. Configure– Configure the system to use the conditions you want– Style conditional content so that you can keep track of it when

writing

3. Write– Mark content as conditional

4. Generate output– Choose a particular product/platform/audience combination


• Make lists: • What product variations are similar enough they

could be documented through one set of source files?• What audiences do you want to customize

documentation for?

• Example for today’s webinar: two platforms– A software application that has different keyboard

shortcuts for Macintosh and Windows platforms

Step 1: Plan

Step 2: Define conditional attribute values

Edit the XMetaL ct_config.xml file. – This file is installed in your C:\Program Files\XMetaL

6.0\Author\Conditional Text\configs folder.

<attribute name="platform" title="Platform"> <value name="windows" title="Windows" /> <value name="macintosh" title="Macintosh" /> </attribute>


Distribute settings files

• You can standardize conditions within a team by distributing the ditabase_ct_config.xml file.

• When you start XMetaL, XMetaL automatically configures its Conditional Text dialogs to use the values in this file.


Style conditional text

• You'll want to be able to keep track of conditions when you are writing, preferably in real-time via color-coding.


Configure styling

• Styling affects what you see in XMetaL, not in output• Click Reuse > Style Conditional Text.


To make content conditional:

1. Click in an element, or select some text

2. Click Reuse > Apply/Remove Conditions

Step 3: Write

Under the covers

Content for Windows only:

Press Ctrl+S.

Content for Windows and Macintosh, but not Unix:

Press Ctrl+S.

Content for all platforms:

Press Ctrl+S.


What content can you make conditional?

Yes:• Text• Images• Cross-references• Index markers• Tables• Rows in tables• Content within content

references• Topic references in DITA

maps

No:• Individual table cells

• Table columns

• Required elements (you can conditionalize text within required elements)

<ph> element

• If you make selected text conditional, XMetaL inserts <ph> tags so it can “hang” attributes on the <ph> element.


Best practices

• To make a whole topic conditional, conditionalize the corresponding topic reference in the DITA map file.

• Do not conditionalize content that is "common to all." – If an element is common to all deliverables, do not put

conditional attributes on it.– If an element is common to all products, do not put any "product"

attributes on it.

• If your content will be translated, it is safest to conditionalize entire sentences, not parts of sentences.


Step 4: Generate conditional output

• In XMetaL: File > Generate Output

• Choose what platforms, products, and audiences you want to include

What about DITAVAL files?

• You don’t need to write one. XMetaL generates the DITAVAL file automatically:

<prop att="platform" val="macintosh" action="exclude"/>


Multiple Condition Types


Multiple condition types

Say you have:

• Three platforms: “Windows” and “Macintosh” and "Unix"

• Two audience types: “Europe” and “North America”


How DITA handles multiple condition types

For an element marked as audience = “Europe” and platform = “windows”

In output for this audience and product:

Does the element appear?

Notes

EuropeMacintosh

No* The element is for the right audience. The element is not for the right platform.

North AmericaWindows

No* The element is not for the right audience. The element is for the right platform.

Europe Windows and Macintosh

Yes The element is for the right audience. The element is for one of the right platforms.

*Would appear if you used native FrameMaker® conditions instead of DITA


Multiple condition types: the rule

• In this example: Content must be for both the right platform and the right audience in order to be included.

• The general rule: An element is included if, for each conditional attribute:- It doesn't have any values for that attribute, i.e. it is

"common to all"- OR it matches at least one value that should be

included.


Of the 4 steps, planning is the most challenging:

1. Plan

2. Configure

3. Write

4. Generate output

Putting it into practice


DITA attributes

DITA attributes for conditional text are:– product– platform– audience– otherprops

• For anything else, including other audience types

– props • Create new attributes by specializing the “props” attribute


Example

You are documenting a product with Macintosh, Windows, and Unix versions

For this example:• the attribute you need is "platform".• you will allow the values of the platform attribute

to be "Macintosh", "Windows", and "Unix".


• List the attributes, and values of each attribute, that you want to use.– These will go into your ct_config.xml file

• Do not overload the “audience” attribute:– E.g. have an “audience_skill_level” attribute and a

“audience_region” attribute. Do not put your lists of skill levels and regions all into the “audience” attribute.

Make lists


Summary: Why DITA for conditional text?

• Scalable:– Handles multiple condition types well– Easily standardized across a team

• Standards-based:– Multiple output formats – Can work with dynamic content delivery systems

• Within reach:– No programming needed– Does not require a sophisticated CMS or publishing

system


Q&A

[email protected]

1-866-793-1542

• Contact Su-Laine at: syeo at justsystems dot com

• Today’s slides are at http://www.slideshare.net/XMetaL

mailto:[email protected]




http://na.justsystems.com/

customizing content with dita conditional text and xmetal

Technology

content conditional

wantstyle conditional

conditional text dialogs

conditional textplanmake

customized content

writingwritemark content

customizing content

content reusereuse