What’s new in DITA 1.3? by Yas Etessam, DITA Consultant and Leigh White, DITA Specialist at IXIASOFT Come and learn about the new proposed DITA 1.3 features. Leigh and Yas will provide an overview of the new architectural features including extensions to the DITA core vocabulary, Online Help vocabularies, scoped keys, branched filtering and enhancements to the Learning and Training, Troubleshooting and Table specializations.

1. What’s New in DITA
1.3
Yas Etessam, DITA Solutions Architect
Leigh White, DITA Specialist, IXIASOFT

2. Introductions
Leigh White
DITA Specialist
• Writer, Information Architect, Speaker
• Implements and supports DITA CMS
• Author of DITA for Print
Yas Etessam
DITA Solutions Architect
• Acknowledged contributor DITA 1.0, 1.1 and 1.2
• Designs and deploys XML solutions
• Bay Area consultant

3. DITA 1.3 Release Themes
• Online help
• Branch filtering
• Troubleshooting
• Scoped keys
• Learning and training
• New vocabularies, elements, attributes

4. Online help support
• Need to create increasing number of online help
targets from same DITA sources, such as mobile,
embedded, standard tri-pane, etc.
• Need to use a topic within help systems for
different products, with a different context-sensitive
id required for each product

5. Online help support
• DITA 1.3 extends metadata to capture this target-specific
information and support multiple callback
and display schemes
• Once the information is captured within DITA, you
can apply standard metadata logic to it.
• All of this reduces dependencies on external Help
Authoring Tools (HATs)
 Purists debate: what about separation of content and presentation? These
new elements and attributes provide a choice…continue using HATs for
formatting of content if you like, or bypass them and use this embedded
metadata along with downstream processing to create formatted help
without the added expense and overhead of additional tools.

6. Online help support
• Three new attributes for <resourceid>:
@appid – identifies a referenced topic to an external
application
@ux-context-string – specifies a context id for the topic
@ux-source-priority – specifies how to resolve conflicts
between callbacks defined in a topic or map
• New element and attribute to record display
information directly in map:
 <uxwindow>
@ux-windowref

7. Online help support – EXAMPLE 1
<map>
<topicref href="topicA.xml">
<topicmeta>
<resourceid
appname="widget"
appid="widget"
ux-context-string="#532"
ux-source-priority="map-takes-priority"/>
<resourceid
appname="gadget"
appid="gadget"
ux-context-string="id4278"
ux-source-priority="map-takes-priority"/>
</topicmeta>
</topicref>
...
</map>

8. Online help support – EXAMPLE 2
<map>
<topicmeta>
<uxwindow
id="w1" name="ux-tablet"
top="5" left="5" height="90%" width="90%"
features="status=yes,toolbar=no,menubar=no,location=no"
relative="false" full-screen="no"/>
ux-source-priority="map-takes-priority"/>
</topicmeta>
<topicref href="topicA.xml">
<resourceid
appname="gadget"
appid="gadget"
ux-context-string="id4278"
ux-source-priority="map-takes-priority"
ux-windowref="ux-tablet"/>
</topicref>
...
</map>

9. Branch filtering
• Pre-DITA 1.3, DITAVAL filters could only be
applied to an entire map. There was no way to
apply a different set of filters to one set of content
within a map (a branch). This is a common use
case.

10. Branch filtering
• New element on <topicref> and <mapref>:
 <ditavalref>

11. Branch filtering – EXAMPLE 1
<map>
<topicref href="topicA.xml">
<topicref href="topicB.xml"/>
<topicref href="topicC.xml"/>
<topicref href="topicD.xml"/>
</topicref>
<topicref href="topicW.xml">
<ditavalref href=“gadget.ditaval"/>
<topicref href="topicX.xml"/>
<topicref href="topicY.xml" product="widget"/>
<topicref href="topicZ.xml"/>
</topicref>
</map>

12. Branch filtering
• The conditions specified in gadget.ditaval apply to
the branch, as well as content in topicW.xml and
all three of its children (topicX, topicY, and topicZ).
• If gadget.ditaval specifies that content for the
Widget product should be excluded, then any
content marked @product=”widget” will be
excluded from all topics W, X, and Z. TopicY.xml
will be excluded from the output altogether.

13. Branch filtering – EXAMPLE 2
<map>
<mapref href="mapA"/>
<mapref href="mapB">
<ditavalref href=“gadget.ditaval"/>
</mapref>
<mapref href="mapC">
<ditavalref href=“widget.ditaval"/>
</mapref>
</map>
</map>
• Main map with three nested maps. Maps A, B, and
C all contain content for both Widget and Gadget.
Map A remains unfiltered. MapB filtered to include
only Gadget content. MapC filtered to include only
Widget content.

14. Branch filtering
• Global filters still take priority for exclude. If content
is excluded at a higher level by a global ditaval, it
will not be re-included by a branch ditaval.
• OTOH, if content is included at a higher level by a
global ditaval, it can be excluded by a branch
ditaval.
• This is logical but a departure from the pre-1.3
ditaval principle that “include always wins.”

15. Branch filtering
• You can also publish a single branch of content
multiple times with a different branch filter applied
each time.
• Each <ditavalref> is a signal to the processor to
publish that branch using the conditions specified,
so a processor would automatically publish the
following branch twice.

16. Branch filtering – EXAMPLE 3
<topicref href="topicA.xml">
<ditavalref href="us.ditaval"/>
<ditavalref href="canada.ditaval"/>
<topicref href="topicB.xml"/>
<topicref href="topicC.xml"/>
<topicref href="topicD.xml"/>
</topicref>

17. Troubleshooting information type
• Designed to help users resolve specific problems.
• Provides one or more solutions to a problem.
Reference Task
Troubleshooting
Concept

18. Troubleshooting topic type
• Offers problems or conditions:
 title
 shortdesc
 condition
• Offers one or more solutions:
 troubleSolution
 cause
 remedy
 steps
• If one solution doesn’t work, the user moves to the
next troubleSolution.

19. Troubleshooting

20. Troubleshooting
<troubleshooting>
<title>Path Thrashing Causes Slow LUN Access</title>
<shortdesc>If your ESXi host is unable to access a LUN, or access is very slow, you
might have a problem with path thrashing, also called LUN thrashing.
</shortdesc>
<troublebody>
<condition><title>Condition</title>
<p>Your host is unable to access a LUN, or access is very slow.
The host's log files might indicate frequent path state changes.</p>
</condition>
<troubleSolution>…
</troubleSolution>
</troublebody>
</troubleshooting>

21. Troubleshooting
<troubleSolution>
<cause><title>Cause</title>
<p>The problem might be caused by path thrashing.
Path thrashing might occur when two hosts access the same LUN
through different storage processors (SPs) and, as a result, the LUN is
never available.</p>
<p>Path thrashing typically occurs on active-passive arrays. Path thrashing can
also occur on a directly connected array with HBA failover on one or more nodes.
Active-active arrays or arrays that provide transparent failover do not cause path
thrashing.</p>
</cause>
…
</troubleSolution>

22. Troubleshooting
<remedy><title>Solution</title>
<steps>
<step><cmd>Ensure that all hosts that share the same set of LUNs on the active-passive
arrays use the same storage processor.</cmd></step>
…
</steps>
</remedy>
</troubleSolution>
</troublebody>
</troubleshooting>

23. Troubleshooting extensions
• DITA 1.3 also supports embedded troubleshooting
information inside the default data model.
• <note type=“trouble”>
• <steptroubleshooting>
• <tasktroubleshooting>

24. <note> example
<note type="trouble“>
If the green LED light is not blinking, verify that the microcontroller
has been plugged in.</note>

25. <steptroubleshooting> example
<step> …
<stepresult>The message “Host added to the Active Directory"
displays.</stepresult>
<steptroubleshooting>If a “Peak memory reservation exceeded, host not
added” error message is displayed, the memory reservation exceeds the
default limit specified in the Web Client. See <xref>Increase the
memory limit for the system resource pool</xref>.</steptroubleshooting>
</step>

26. <tasktroubleshooting> example
…
<result>The <uicontrol>User Type</uicontrol> menu updates to display the
new types you added.</result>
<tasktroubleshooting>If the User Type menu does not display the additions,
manually refresh the page.</tasktroubleshooting>
</taskbody>
</task>

27. DITA 1.2 keys
• To define a key, add a keydef into your map
<keydef keys=" changing-printer-cartridge-task "
href=“changing-printer-cartridge.dita" type="concept"
format="dita"/>
• To create a cross-reference to that topic
See <xref keyref="changing-printer-cartridge-task"/>.

28. Use Case for Scoped Keys
ICM Course
Module 1
Module 2
Module 3

29. Scoped keys
• DITA 1.3 will support key definitions at different
locations within a map structure.
 Good for deliverables that are comprised of lots of
submaps
 Each submap defines its keys.
 If a topic is re-used in a deliverable, you can specify
different key values depending in which submap the
topic appears.

30. New attribute: @keyscope
• @keyscope for <topicref> and <mapref>
• Used to define a key space
<map xml:lang="en">
<title>Training Courses</title>
<mapref href="course-1.ditamap" keyscope="course-1"/>
<mapref href="course-2.ditamap" keyscope="course-2"/>
</map>

31. DITA 1.3 keys
• To use a key, DITA 1.2 syntax still works
<xref keyref="changing-printer-cartridge-task"/>
• If you have more than one definition, include the
keyscope :
<xref keyref=“course-1.changing-printer-cartridge-task"/>

32. Cross-deliverable linking
• You get a unique keyscope, if you reference a
different map using the mapref element
 @scope set to “peer”
@keyscope tells processor which key definitions to us
• Cross-deliverable links
 Links to wholly independent deliverables that are created
with different maps.
 Links to a topic within another deliverable.
 Links to figures and tables within another deliverable.

33. Cross-deliverable linking
• The cross-reference references the @keyscope of
the other DITA map and the specific key.
• In this example, the keyscope is map-b, the
specific key is topic-b-1.
<p>See <xref keyref="map-b.topic-b-1">B 1</xref>
...</p>

34. Expanded base
• XML mention and equations
• MathML
• SVG
• Relax NG
• Grouped values on @audience, @platform,
@product, and @otherprops
<p product=“database(db2 oracle)
appserver(WAS)”>…</p>
• @deliveryTarget (replaces @print)

35. Table extensions
• Table
 @orient
• Entry
 @rotate
@scope
 @headers

36. Some other cool small things
• Use <draft-comment>, <text> in more places
• Extended content model for @style on DITAVAL
<prop> and <revprop>
• Use @rev on <title>
• Use @keyref on <object>, <param>
• New <line-through> and <overline> elements in
highlight domain
• New <sort-as> element for use on logically
sortable elements such as title, searchtitle, navtitle,
glossterm, dt, entry, stentry

37. Some other cool small things
• New @cascade to provide more control over
metadata cascade within maps

38. OASIS Darwin Information Typing
Architecture Releases
OASIS DITA
Technical
Committee
formed April
2004
DITA 1.0
June 2005
approved as
an OASIS
standard
DITA 1.1
August
2007
DITA 1.2
December
2010
DITA 1.3
target
December
2014

39. OASIS DITA Release Process
DITA TC
Develop features
Phase 1, 2 ,3 Proposals
Update DTDs, XSDs
Public Review
Publically available
specifications
Consider feedback
Update spec
OASIS Vote
Official release
DITA Open Toolkit
Update transforms
Implement new
processing
DITA OT
Releases to
support 1.3
features
Vendors
Implement new
features
Software
Releases to
support 1.3
features

40. Be a cheerleader and a gate keeper
• Do we need it?
• What is the business value?
• Is it supported by our vendors?
• Is it supported in the DITA OT and our specific
transforms?
• How much will it cost to move to DITA 1.3?
• What is the impact on our tools/infrastructure
team?

41. Questions?