key scopes in dita 1.3
TRANSCRIPT
Scoped Keys inDITA 1.3
(Finally!)
Leigh WhiteDITA Specialist
Presented at CIDM/DITA NAApril 2015
Me
• Writer, Information Architect• DITA user since 2007• Implements and supports the DITA CMS• Author of DITA for Print• Contributor to Language of Content Strategy• Member of
DITA Adoption TC
DITA 1.2: Once upon a time
“The DITA 1.2 key reference facility provides an indirect addressing mechanism that allows authors to create references to things without having to know exactly where or what those things are or will be in the future.” (from an OASIS DITA Adoption TC white paper)
WHAT?
Unscoped key (simple) example<map> <keydef keys="ot-version"> <topicmeta> <keywords> <keyword>1.8</keyword> </keywords> </topicmeta> </keydef> <topicref href="introduction.xml"/></map>
From introduction.xml:
<p>This book was … formatted using the DITA Open Toolkit <ph keyref="ot-version"/> using some of the same techniques you’ll learn about here.</p>
GREAT, huh?
But…there was trouble in the key-ngdom
<map> <title>Using the Widget</title> <keydef keys="module-name"> <keyword>Widget</keyword> </keydef> <topicref href="get_started.xml"/></map>
get_started.xml
<p>Now that you have integrated the <ph keyref="module-name">, many new options are available to you.</p>
<map> <mapref href="widget.ditamap"/> <mapref href="gadget.ditamap"/></map>
<map> <title>Using the Gadget</title> <keydef keys="module-name"> <keyword>Gadget</keyword> </keydef> <topicref href="get_started.xml"/></map>
There can be only one…
• In DITA 1.2, there can be only one definition/resolution of a key for an entire processing scope
• The definition used is the “first” one that the DITA-OT encounters when processing the map.
• What does “first” mean? Long story. Read about it here:
http://dita.xml.org/resource/dita-tc-faq-about-keys.
• The bottom line is you can’t use a topic multiple times in a deliverable and have a different value for a given key each time.
The people were angry
And the full promise of keys lay tantalizingly out of reach
The years passed…
…and DITA 1.3 keyscope appeared
Scoped keys!
• DITA 1.3 supports key definitions at different locations within a map structure Good for deliverables that are comprised of lots of sub-
maps; each map can have its own set of key definitions If a topic is re-used in a deliverable, you can specify
different key values depending in which sub-map the topic appears
Fully backwards-compatible with DITA 1.2. Existing maps function exactly as before; they don’t contain any keyscope attributes
How do they work?
• New attribute “keyscope”• Used to define a key space• Can be used on <mapref>, <topicgroup>,
<topichead>, <topicref>
Let’s look at some examples
Example 1: Parallel key spaces
Nested standalone maps:
<map> <title>Training Courses</title> <mapref href="widget.ditamap" keyscope="widget"/> *<keydef keys="module-name"> = Widget <topicref href="get-started.xml"/> <mapref href="gadget.ditamap" keyscope="gadget"/> *<keydef keys="module-name"> = Gadget <topicref href="get-started.xml"/></map>
get_started.xml:
<p>Now that you have integrated the <ph keyref="module-name">, many new options are available to you.</p>
Multiple instances?
• “If a topic that contains key references is reused in multiple key scopes within a given root map such that its references resolve differently in each use context, processors MUST produce multiple copies of the source topic in resolved output for each distinct set of effective key definitions that are referenced by the topic. In such cases, authors can use the [copy-to] attribute to specify different source URIs for each reference to a topic.” (From DITA 1.3 spec as of 4/4/2015)
• force-unique build parameter generates copy-to attributes to duplicate topicref elements. The allowed values are true and false; the default value is false.
Example 2: Parallel key spaces
Single map, scope definition via topicgroup or topichead:
<map> <title>Training Courses</title> <topicgroup keyscope="widget"> *<keydef keys="module-name"> = Widget <topicref href="get-started.xml"/> </topicgroup> <topichead keyscope="gadget" navtitle="Using the Gadget"> *<keydef keys="module-name"> = Gadget <topicref href="get-started.xml"/> </topichead></map>
*Not the actual syntax; abbreviated to save space
Example 3: Parallel key spaces
Single map, scope definition via topicref:
<map> <title>Equipment Oil Change Procedures</title> <topicref href="get-started.xml" keyscope="widget"> *<keydef keys="module-name"> = Widget </topicref> <topicref href="get-started.xml" keyscope="gadget"> *<keydef keys="module-name"> = Gadget </topicref></map>
Example 4: Nested key spaces<map keyscope="scope1"> <map keyscope="scope2"> <topicgroup keyscope="scope3"> <topicref href="topicA.xml"/> </topicgroup> </map></map>
scope1: module-name="Widget"
scope2: module-name="Gadget"
scope3: module-name="Thingy"
In topicA.xml, key "module-name" resolves to...?
Widget
Which key space wins?
• If a key is defined in both parent and child scopes, parent definition takes precedence
• Always an implicit root key scope on root map• Based on existing DITA 1.2 practice where a key
definition in a parent map takes precedence over same key definition in child maps Good arguments for having key definitions in child
scopes override those from parent scopes for references within that scope
Could put control of this in the author’s hands via “precedence”-type attribute but maybe confusing
Example 5: Keys outside of scopes<map> <title>Training Courses</title> <mapref href="widget.ditamap" keyscope="widget"/> *<keydef keys=“X"/> *<keydef keys=“Y"/> <mapref href="gadget.ditamap" keyscope="gadget"/> *<keydef keys=“X"/> *<keydef keys=“Z"/> <topicref href=“topic1.xml”/> <!--uses keys X & Y--> </map>
•X is redefined per gadget keyscope definition•Y is considered undefined because it has no definition within gadget keyscope•Key definitions don’t carry over from parallel key spaces; they only “trickle down” from parent key spaces*
*Let me clarify
Y
Example 6: Using keys from other scopes
<map> <title>Training Courses</title> <mapref href="widget.ditamap" keyscope="widget"/> *<keydef keys=“module-name"/> <topicref href=“get-started.xml"/>
<p>If you also integrate the <ph keyref=“gadget.module-name">, many new options will be available to you.</p>
<mapref href="gadget.ditamap" keyscope="gadget"/> *<keydef keys="module-name"/> <topicref href=“get-started.xml"/>
<p>If you also integrate the <ph keyref=“widget.module-name">, many new options will be available to you.</p>
</map>
•To reference a key in another scope, include that scope name in the keyref•If the key is many scopes deep, specify all of the scope names, from the top down to the key, relative to the current scope
Scope names and reuse
• Scope names can limit reuse Either the context you are reusing in has to have a key
space with the specified name, or You have to add a key space with that name to the
context for the sake of resolving the key
• Otherwise, you have an undefined key
Example 7: Cross-deliverable linking
• Basic idea: define a root map as a key space and allow a topic within another root map to link to a key within that key space
• One use case: root map A creates a help system; root map B creates a separate help system. You want to create links between topics in the two help systems.
• Whether or not a cross-deliverable reference becomes an active link depends on processor DITA 1.3 spec doesn't define how cross-deliverable links
should be handled by processors
Example 7: Cross-deliverable linkingwidget.ditamap:
<map> <title>Widget Online Help</title> <mapref href="gadget.ditamap" scope="peer" keyscope="gadget"/> <topicref href="getting_started_widget.dita"/></map>
gadget.ditamap:
<map> <title>Gadget Online Help</title> <keydef keys="integ-gadget" href="integrating_gadget.dita"/></map>
getting_started_widget.dita:
<topic id="getstartwidget"> <title>Getting started with the Widget</title> <body> <p>If you choose to <xref keyref="gadget.integ-gadget">integrate the Gadget module</xref>, many more options will be available to you.</p> </body></topic>
