Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

What's New in DITA 1.3


Published on

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.

Published in: Software
  • Be the first to comment

What's New in DITA 1.3

  1. 1. What’s New in DITA 1.3 Yas Etessam, DITA Solutions Architect Leigh White, DITA Specialist, IXIASOFT
  2. 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. 3. DITA 1.3 Release Themes • Online help • Branch filtering • Troubleshooting • Scoped keys • Learning and training • New vocabularies, elements, attributes
  4. 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. 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. 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. 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. 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. 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. 10. Branch filtering • New element on <topicref> and <mapref>:  <ditavalref>
  11. 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. 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. 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. 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. 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. 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. 17. Troubleshooting information type • Designed to help users resolve specific problems. • Provides one or more solutions to a problem. Reference Task Troubleshooting Concept
  18. 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. 19. Troubleshooting
  20. 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. 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. 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. 23. Troubleshooting extensions • DITA 1.3 also supports embedded troubleshooting information inside the default data model. • <note type=“trouble”> • <steptroubleshooting> • <tasktroubleshooting>
  24. 24. <note> example <note type="trouble“> If the green LED light is not blinking, verify that the microcontroller has been plugged in.</note>
  25. 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. 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. 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. 28. Use Case for Scoped Keys ICM Course Module 1 Module 2 Module 3
  29. 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. 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. 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. 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. 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. 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. 35. Table extensions • Table  @orient • Entry  @rotate @scope  @headers
  36. 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. 37. Some other cool small things • New @cascade to provide more control over metadata cascade within maps
  38. 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. 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. 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. 41. Questions?