What’s New in DITA 1.3

Yas Etessam, DITA Solutions Architect

Leigh White, DITA Specialist, IXIASOFT

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

DITA 1.3 Release Themes

• Online help• Branch filtering• Troubleshooting• Scoped keys• Learning and training • New vocabularies, elements, attributes

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

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.

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

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>

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>

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.

Branch filtering

• New element on <topicref> and <mapref>: <ditavalref>

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>

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.

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.

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.”

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.

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>

Troubleshooting information type

• Designed to help users resolve specific problems.• Provides one or more solutions to a problem.

Troubleshooting

Concept

Reference Task

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.

Troubleshooting

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>

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>

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>

Troubleshooting extensions

• DITA 1.3 also supports embedded troubleshooting information inside the default data model.

• <note type=“trouble”>• <steptroubleshooting> • <tasktroubleshooting>

<note> example

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

<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 thedefault limit specified in the Web Client. See <xref>Increase the

memory limit for the system resource pool</xref>.</steptroubleshooting>

</step>

<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>

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"/>.

Use Case for Scoped Keys

ICM Course

Module 1

Module 2

Module 3

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.

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>

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"/>

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.

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>

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)

Table extensions

• Table @orient

• Entry @rotate @scope @headers

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

Some other cool small things

• New @cascade to provide more control over metadata cascade within maps

OASIS Darwin Information Typing Architecture Releases

OASIS DITA Technical

Committee formed April 2004

DITA 1.1 August 2007

DITA 1.3 target December 2014

OASIS DITA Release Process

DITA TC Develop features

Phase 1, 2 ,3 Proposals

Update DTDs, XSDs

Public ReviewPublically available

specifications

Consider feedback

Update specOASIS Vote

Official releaseDITA Open

ToolkitUpdate

transformsImplement new

processing

DITA OT Releases to support 1.3

featuresVendorsImplement new

features

Software Releases to support

1.3 features

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?

Questions?