overview of dita 1.3

© 2015 Eberlein Consulting, LLC

Overview of DITA 1.3

Kristen James Eberlein Eberlein Consulting LLC IXIASOFT User Conference 2015

Montreal, Canada


Agenda

1. What is OASIS? The DITA TC?

2. My background

3. Who are you?

4. DITA 1.3 for authors

5. DITA 1.3 for architects

6. Question and answers


What is OASIS?

OASIS = Organization for the Advancement of Structured Information Standards

A nonprofit consortium that drives the development, convergence and adoption of open standards for the global information society


What is the OASIS DITA Technical Committee?

A group of 16 people who meet on a telephone call each week for 60 minutes.

All volunteer, no paid staff

Tools poor: No CCMs, we use SVN …

We rely on the “kindness of vendors”

We (or our corporate employers) pay so that we can participate in developing DITA.


Who am I?

Involved with DITA TC since 2008; currently chair

Co-editor of the DITA 1.2 and 1.3 specifications

Background as a information architect and information developer

Trained as a historian

Available for consulting :)


Who are you?

Role Responsibilities DITA author Develops information in DITA DITA information architect Develops maps, content

models, reuse strategies, and taxonomies

DITA practitioner Develops document-type shells, specializations, and constraints

DITA developer • Develops transformations • Develops processors and

applications


DITA 1.3 for authors 1. Troubleshooting

2. Context-sensitive help

3. Table enhancements

4. New domains – MathML and SVG

– Release management

– XML mention

5. New highlighting elements

6. New deliveryTarget attribute

7. Addressing same-topic elements

8. Learning and training

9. New <sort-as> element

10. Miscellaneous fixes

DITA 1.3 for architects and practitioners

1. Scoped keys

2. Cross-deliverable linking

3. Branch filtering

4. RELAX NG

5. Cascade attribute

6. Grouped filtering attributes

7. <div> element

7


DITA for authors …


Troubleshooting

New type of <note>: Trouble

New element in <step>: <steptroubleshooting>

New section in <task>: <tasktroubleshooting>

New document type: <troubleshooting>

Champion: DITA Technical Communication subcommittee, with special thanks to Bob Thomas, Tagsmiths


Context-sensitive help Better support for requirements of

online help systems

Enables: – Embedding context-hook information in

DITA topic and maps

– Specifying windowing metadata in a DITA map

– Delivering online help without using an additional Help Authoring Tool (HAT)

Champion: DITA Help subcommittee, with special thanks to Tony Self and Stan Doherty


Changes to tables

Control over orientation (tables) and rotation of text (table cells)

New attributes (@scope and @headers) for <entry>

Enables: – Better control over formatting for print-based output formats

– Improves accessibility for very complex tables that cannot be simplified

Champions: Chris Nitchie (Oberon Technologies), Scott Hudson (Comtech)


New domains (1 of 2)

SVG – Enables use of SVG markup within DITA documents, as well

as use-by-reference of SVG markup stored in other files

Equation and MathML – Support for numbered, in-line, and block equations

– Enables use of MathML markup within DITA documents, as well as use-by-reference of MathML markup stored in other files

Champion: Eliot Kimber, Individual member (Contrext)


New domains (2 of 2)

XML mention

– Describe and document XML applications and document types

Used in DITA 1.3 spec

Release management

Enables content authors to log comments and metadata when content is changed

Available in both maps and topics

Makes generated release notes a possibility!

13

Champions: Eliot Kimber, Individual member (Contrext) and the DITA TechComm subcommittee, with special thanks to Tom Cihak, Freescale


<line-through> – Enable authors to indicate a deletion or revision for

rhetorical purpose

<overline> – Indicates content that should be rendered with a line

above it

New highlighting elements

14



@deliveryTarget attribute

A new conditional processing attribute to replace the now-deprecated @print. Available both in topics and maps.

Enables: – More finely controlled filtering for output formats

– Values are controlled by implementation; infinite possibilities.



Link to an ID in the same topic more easily.

For example, link to a figure in the SAME topic by placing a period after the hash tag (<xref=“#./figure1”>

Addressing same-topic elements

16

Champion: David Helfinstine, PTC


Changes to learning and training

New document types

New domains for learning interactions

Enables: – Learning groups and learning objects to be stored as

objects in a repository

– Enables block-level content in question-and-answer interactions – a serious pain point in DITA 1.2!

Champions: DITA learning & Training subcommittee and Mark Myers, SAP


Can provide a sorting phrase for the content of an element

Useful for sorting in non-Western languages such as Japanese

<sort-as> element

18



<cite> in titles

@rev on <title>

<draft-comment> in more places

<sub> and <sup> available in <indexterm>

Et cetera

Miscellaneous fixes

19


DITA for information architects and practitioners …


Scoped keys

Provides a mechanism to have a single key resolve to different references in different parts of a map.

Enables: – Material from different companies or teams to be

combined without key collision.

Example: – Acme uses the key “company-products” to point to

an overview of their products.

– But so does Ajax

– With scoped keys, the content from these two companies can be combined in a single deliverable.

Champion: Chris Nitchie, Oberon Technologies


Scoped keys: Use cases

Omnibus publications – Combine multiple standalone maps

– Define a key scope for each standalone map to prevent key collisions

Multi-product publications – Each product has common keys: overview, installing …

– Wrap each product area in a key scope to segregate key definitions

Template topics – Reuse a set of topics with keyrefs for graphics and

variable text


Scoped keys: Example <map>

<title>CIDM DITA Conferences</title>

<topichead navtitle="DITA Europe"

keyscope="dita-europe">

<keydef keys="hotel" href="holidayinn-munich.dita" />

<topicref href="aboutTheConference.dita" />

</topichead>

< topichead navtitle="DITA North America"

keyscope="dita-na">

<keydef keys="hotel" href="westin-seattle.dita" />

<topicref href="aboutTheConference.dita" />

</topichead>

</map>


Cross-deliverable addressing

Mechanism for referencing content in another root map – Key-based; utilizes key scopes

Enables: – Production of large omnibus publications

– Useful for companies with large, cross- linked publications



Ability to reference multiple DITAVAL profiles within maps – On the root map

– On a map branch

Previously, only a single DITAVAL profile could be associated with a master map.

Makes reuse more powerful – Can reuse a topic multiple times in a map, each time with different filtering

conditions

– Common use cases: • Installation instructions that vary by operating system • Medical instructions to vary for adult patient vs. adult caretaker of child

Branch filtering

25

Champion: Robert Anderson, IBM


Support for RELAX NG

RELAX NG becomes the normative XML grammar for DITA

Enables: – Single-sourcing of DTDs and XSDs from the RELAX NG

– Much easier to create document-type shells and specializations

GitHub utility for generating DTD and XSD from RELAX NG source

Champion: Eliot Kimber, Individual member (Contrext) – and special thanks to George Bina, SyncroSoft

Enables architects to change default cascading behavior for filtering attributes in maps

Consider the following DITA 1.2 example:

@cascade attribute (1 of 2)

27

<map product=“Widget" platform="windows mac linux"> <title>All about Widget</title>  <topichead navtitle="Linux install” platform="linux"> <!– Only applies to Linux -->  </topichead> </map>

© 2015 Eberlein Consulting, LLC 28

@cascade attribute (2 of 2)

<map product=“Widget" platform="windows mac linux"> <title>All about Widget</title>  <topichead navtitle="Linux install” platform="linux“ cascade=“nomerge” > <!– Only applies to Linux --> </topichead> </map>

Adding the @cascade attribute controls whether values set higher in the map cascade to the element.


The filtering attributes (audience, platform, product, and otherprops) now accept grouped values.

Makes it possible for users to filter content based on a combination of products, audiences, or platforms.

Expanded syntax for filtering attributes (1 of 2)

29



DITA 1.2 <step product=“db2 oracle was”>

DITA 1.3 <step product="database(db2 oracle) appserver(WAS)">

Can filter on attribute subcategory. For example, allows authors to filter on "database" and "appserver" without the two interfering with each other.

Expanded syntax for filtering attributes (2 of 2.)

30


Useful as a specialization base – Can group multiple block-level elements

– Used in new learning & training domain

Useful for authors – Can group blocks of elements for reuse

<div> element

31



Questions?

Kristen James Eberlein Eberlein Consulting, LLC Durham, NC, USA

[email protected] +1 (919) 682-2290 kriseberlein on Skype

mailto:[email protected]


Resources: DITA 1.3

DITA 1.3 specification The URL links to the most recent official version of the specification. In October 2015, it linked to the Candidate OASIS Standard, published 3 September 2015.

DITA 1.3: Why Three Editions? Working draft 04, 29 October 2015.

Overview of DITA 1.3 PDFs of presentations given by Kristen James Eberlein (Eberlein Consulting LLC) at conferences in 2014

DITA 1.3 Webinar PDF and link to recording of a Webinar jointly sponsored by the DITA TC and DITA Adoption TC in August 2014.

Demo of key scopes Illustration of using key scopes with Titania Delivery. Shows the DITA source and rendering with and without key scopes.

http://docs.oasis-open.org/dita/dita/v1.3/dita-v1.3-part0-overview.html

https://www.oasis-open.org/committees/download.php/56803/dita-why-three-editions.pdf

http://dita.xml.org/resource/overview-of-dita-13

http://dita.xml.org/resource/recording-of-oasis-dita-13-webinar

https://td-demo.titaniasoftware.com/portals/ui/sample/viewer/55310e2ee4b0235e2bca8047/55310e37e4b0235e2bca8054/r/concept


Resources: Adoption TC feature articles

Understanding Scoped Keys in DITA 1.3 Authored by Leigh W. White (IXIASOFT); published September 2015.

About the DITA 1.3 release management domain Authored by Tom Cihak (Freescale) and Keith Schengli-Roberts (IXIASOFT); published June 2015.

Using DITA 1.3 Troubleshooting Authored by Bob Thomas (Tagsmiths); published July 2014

Making the Most of the New Math Domains in DITA 1.3 Authored by Autumn Cuellar (Design Science), published April 2015.

https://www.oasis-open.org/committees/download.php/56472/Understanding%20Scoped%20Keys%20In%20DITA%201.3.pdf

https://www.oasis-open.org/committees/download.php/56339/Release_Management_WP.pdf

https://www.oasis-open.org/committees/download.php/53517/DITA13TroubleshootingArticle_FINAL_03jul14.pdf

https://www.oasis-open.org/apps/org/workgroup/dita-adoption/download.php/55488/MathSpecializationFeatureArticle.pdf

overview of dita 1.3

Software