Expand Your Content Reuse Potential through Indirect Addressing:

Using @keys-based Referencing in DITA 1.2

Nancy Harrison

Infobridge Solutions Intelligent Content 2012

Agenda

Review of pre-1.2 referencing and reuse

Why introduce indirect referencing?

Intro to <keys>, <keyref>, <keydef>

Examples of <keys>, <keyref>, <keydef>

Intro to <conkeyref>

Examples of <conkeyref>

Exercises using indirect addressing

First, a little background: what do we mean by reuse?

Re-purposing: reusing content (topics) in different configurations; different collections share some, but not all content; content may be organized differently.

Single-sourcing: reusing content for different output formats: same content is used, with roughly the same organization, to create online help and print manuals.

Simple reuse: reusing boilerplate information or small chunks of text that appear widely but should be maintained in one place

terminology – glossary terms

book titles

product names

trademark/legal notices ...

Re-purposing of content

Reuse flows from the topic-based paradigm

If content is authored as standalone topics

Topics can be used in different contexts; collects controlled by maps

Topics from multiple components can be integrated in a solution

Re-purposing: using DITA maps

Child1-novice

simple

Child2a Child2

Child3 Child2b

Child1-expert

Online help for novice user

Online help for expert users

Reuse of content – block and phrase level

Use the @conref attribute to reuse sub-topic units of information, at the paragraph, list, table, or even phrase level.

Integrated with use of profiling attributes - @product, @audience, etc., to achieve conditionality.

Review of pre-1.2 referencing and reuse

Linking to specific locations

Context: related-links, reltable, inline links (xref)

Profiling: use profiling attributes to modify link target

<conref> to reuse content from other locations

Could also use profiling to modify source location

For either, profiling requires use of DITAVAL file to generate correct output; for a large set of conditions, this can get a bit messy...

Sample of complex reuse using profiling Complex topic

Complex reuse using profiling (cont.)

The DITAVAL file is also complex

How does indirect addressing work?

Indirect addressing uses the map that contains the current topic to determine the location of the link target or the content to be reused.

In DITA 1.1, the location had to be specified 'directly' in the topic containing the link or conref.

Benefits of indirect addressing

Simplifies authoring; authors don't have to give an exact location when defining a link or conref.

Sometimes, the exact location/name of the link target or conref source isn't known at authoring time; using keys, authors don't have to wait till locations are final in order to complete topics.

Topics are often reused in different contexts, and the contexts may require different links and/or content. Indirect addressing allows the target to be changed without modifying the topic itself.

Benefits (continued)

A term or keyword can be linked to explanatory text, or your publishing stylesheet can turn it into a live link to its glossary definition.

Multiple links, in multiple topics, can be changed with a single change to a map.

Storing topics in a file system can be done with some of the benefits of using a CMS.

A map can optionally remove an explicit link from a topic, by not defining the key that the link references.

How it works

Value System map

Keys:

speakers, receiversl

Family

System map

Keys: speakers, receivers

Welcome topic

Welcome topic

Install_system topic

speaker200 Speaker Topic

receiver300 Receiver Topic

speaker400 Speaker topic

receiver200 Receiver Topic

Note: though the files are different, the key names ('speakers' & 'receiver') are the same.

Usage: defining a key

Key basics: within a map, define a key (@keys) by assigning it a target location.

Keys are defined in either a <topicref> or <keydef>

<topicref keys=”speakers” href=”speakers200.dita”/>

<keydef keys="logo" href="images/salmon-maze.jpg"/>

<keydef keys="system_name">

<topicmeta>

<keywords>

<keyword>SoundOff Family Sound System</keyword>

</keywords>

</topicmeta>

</keydef>

Usage: Referencing a key

A key can be referenced from any element that contains an 'href' attribute (as well as any element via the @conkeyref attribute)

<link keyref=”contact”/>

<xref keyref=”speakers”/>

<image keyref=”logo”/>

<keyword keyref=”system_name”/>

Use a key to determine map content

Define key

Call key in topicref

Create link using key

Change the key to change the target

New href value

Creates link to new target

Use a key to define a keyword and image

Define keys for image and keyword in map

Use keys to point to image and keyword in topic

Result in output

Use a key to link to a web page 1, Define a key that calls a web page 2. Use that key

to create a link.

3. The link shows up in the output.

4. And points to the web page.

Links using keys are easy to remove...

Using the same install_system.dita file, but in a map where the 'receiver_cleaning' key isn't defined, the link doesn't show up in the output.

Keys really do provide a great deal of flexibility...

All the previous examples used the same ;welcome,dita' and 'install_system.dita' files, and one of 3 map files. No DITAVAL files are used at all.

@conkeyref: reusing content with keys

The @conkeyref attribute is used instead of @conref where the target - the location of the content to be included by reference in the topic – will vary according to the map the topic is published from.

Authors can change the target of a @conkeyref target without changing the topic it's in.

Simplified @conkeyref syntax

@conkeyref syntax is simpler than @conref syntax.

– @conref requires URI syntax; if the target element is a descendant of a topic, the path must include the ID of the parent topic.

<keyword conref=”../speakers.dita#topicid/system_name”/>

– @conkeyref requires simply a key value pointing to a defined key, then a forward slash '/', then the target element's ID.

For @conkeyref, first define the key in a map, e.g. <keydef keys=”speakers” href=”../speakers.dita/>

Then, refer to an element within it. <keyword conkeyref=”speakers/system_name”/>

@conkeyref in action

One topic, no profiling, 3 different outputs

Results of key use

Target topic in output

Link target

Exercises

In the folder 'SoundOff_Systems_exercise', create maps and modify the welcome.dita and install_system.dita files for the following configurations. (give them new names:)

1. Receiver Model 300, Speaker Model 700

2. Receiver Model 300, Speaker Model 400, Blu-ray Player Model 450 (sold only in Europe, so 'contact' should be eur version.

3. Receiver Model 650, Speaker Model 200, Blu-ray Player Model 800, Headphones Model 400 (sold only in Asia)

Use the content in the 'SoundOff_Systems_2012' folder as a basis for your work.. Note that you'll need to add material to the welcome & install topics for the new components (I have suggested some basic text for the install.)

Questions?

Presenter background

Working with SGML / XML since 1992

One of original DocBook DTD developers

IBM DITA Architect team 2003 – 2007; charter member of OASIS DITA Technical Committee

Currently, DITA TC Secretary; also member of DocBook TC

Additional background in translation / globalization

Contact information

Nancy Harrison

Infobridge Solutions

Concord, MA, USA

nharrison@infobridge-solutions.com

http://www.infobridge-solutions.com