what's new in dita 1.3
DESCRIPTION
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.TRANSCRIPT
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?