expand your content reuse potential through indirect addressing: using @keys-based referencing in...
DESCRIPTION
DITA 1.2 introduced a set of indirect addressing features, based on the new @keys attribute, that enables resources to be defined at a global level, in a map, rather than having to be defined within each topic that uses the resource. This presentation demonstrates reuse potential that you may not have considered.TRANSCRIPT
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
http://www.infobridge-solutions.com