does dita need xml? lightweight dita and html5

© IBM Corporation 2012, 2014 1

Michael PriestleyEnterprise Content Technology StrategistSenior Technical Staff Member

Does DITA need XML?XDITA and HDITA: A Lightweight DITA Preview

May 14, 2013

2 ©IBM Corporation 2012, 2014

Important Disclaimer

THE INFORMATION CONTAINED IN THIS PRESENTATION IS PROVIDED FOR INFORMATIONAL PURPOSES ONLY.

WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION CONTAINED IN THIS PRESENTATION, IT IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED.

IN ADDITION, THIS INFORMATION IS BASED ON IBM’S CURRENT PRODUCT PLANS AND STRATEGY, WHICH ARE SUBJECT TO CHANGE BY IBM WITHOUT NOTICE.

IBM SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS PRESENTATION OR ANY OTHER DOCUMENTATION.

NOTHING CONTAINED IN THIS PRESENTATION IS INTENDED TO, OR SHALL HAVE THE EFFECT OF:

• CREATING ANY WARRANTY OR REPRESENTATION FROM IBM (OR ITS AFFILIATES OR ITS OR THEIR SUPPLIERS AND/OR LICENSORS); OR

• ALTERING THE TERMS AND CONDITIONS OF THE APPLICABLE LICENSE AGREEMENT GOVERNING THE USE OF IBM SOFTWARE.

©IBM Corporation 2012, 2014

What’s ahead

• Why are we doing this?

• Why XML/HTML5 sucks/is awesome

• Why can’t we all just get along?

• What would that look like?


Why are we doing this?

“Here’s something

simple!”

“We need more

features!”

“It’s too complex!”


simple!”

“We need more

features!”


“Here’s something simple!”

“We need more

features!”


SGMLXML

DITA


Evolution or revolution?

Full DITA

LightweightDITA

“We need something

simple”

“We need more

features!”

“We need something

simple”

“We need more

features!”


simple!”

“We need more

features!”


But we are not alone

vi

Emacs

“It’s too complex!!”

XHTML

“Here’s something simple!”

WikiVariant

A-Z

Word

“We need more

features!”


markdown

LightweightDITA

HTML5+

extensions

“We need more

features!”


Full DITA

HTML5

DocBook

“Grrrr”


Why XML sucks

• Tags and attributes are a pain in the #$%#

• Specialized editors cost money, take a long time to load, take a long time to learn

• Long, complex processing chain can break in lots of different places, be really hard to debug

<topic id=“abc”><title>The point of it all</title><shortdesc>I can sum it up here</shortdesc><body>

<p>I can say some more stuff</p><section><title>Stuff</title><p>And so on</p><ul>

<li><p>This</p></li><li><p>Is</p></li><li><p>A List</p></li>

</ul></section><section><title>And more stuff</title><p>With its own explanation</p><dl><dlentry>

<dt><p>This</p></dt><dd><p>Is explained</p></dd>

</dlentry><dlentry>

<dt><p>This</p></dt><dd><p>Is also explained</p></dd>

</dlentry></dl></section>

</body></topic>


Why XML is awesome

• Tags and attributes separate content from presentation, allowing flexibility and control

• Specialized editors support different authoring roles – not one size fits all

• Specialized content types and structures enforce consistency and enable automation

• Multistage processing chain maximizes reuse and provides ready-to-view output

Publish

HTML5

EPUB

Kindle

iBook

PDF

Embedded help

Word

OpenOffice

Slides

Various help formats

Etc.

Filter, Substitute, Link, Assemble, Layout for Device or Format, Etc.

Design Author


Why HTML5 sucks

• Tags and attributes are a pain in the #$%#

• Anything goes

• Single processing step can bloat and affect performance

• No standardized capabilities for conditional processing, reuse, etc.

<html><article>

<h1>The point of it all</h1><p>I can sum it up here</p><p>I can say some more stuff</p><section>

<h2>Stuff</h2> <p>And so on</p>

<ul> <li><p>This</p></li> <li><p>Is</p></li> <li><p>A List</p></li> </ul> <section> <h2>And more stuff</h2> <p>With its own explanation</p> <dl> <dt><p>This</p></dt> <dd><p>Is explained</p></dd> <dt><p>This</p></dt> <dd><p>Is also explained</p></dd> </dl> </section></article></html>


Why HTML5 is awesome

• Tags and attributes separate content from presentation, allowing flexibility and control, including responsive design

• Editor support widely available, even right in the browser

• Author and present in same interface – the browser.

• No complex processing chain, fewer breakage points

(Filter for user)Author View


Why can’t we all just get along?

HTML5 supports adaptive

XML supports omnichannel

EPUB

Kindle

iBook

PDF

Embedded help

Word

OpenOffice

Slides

Various help formats

.

.

.

Aaaand HTML5


Why can’t we ALL just get along?

Tutorials

API docs

Trouble-shooting

Prodoverviews

Tech comm

Trainer

Developer

Support

Marketing

LCMS

WCM

CCM

KB

Usage

Learningsite

Marketingsite

Supportsite

Developersite

Coderepo


Let’s try that again…

From any source, to any channel

Content reused across applications, applications reused across content

LCMS

WCM

CCMKB

Coderepo

Learningsite

Marketingsite

Supportsite

Developersite

Tech comm

Trainer

Developer

Support

Marketing


So what does it look like?

Lightweight DITA

XDITA and HDITA mapping

Next steps, open questions


Lightweight DITA vs full DITA

15

Full DITA Lightweight DITA

Topics 94 elements ~30 elements

Maps 10 elements(+30 shared with topic)

~3 elements(+1 shared with topic)

<p>What elements are allowed in a paragraph?</p>

dl parml fig syntaxdiagram imagemap image lines lq note hazardstatement object ol pre codeblock msgblock screen simpletable sl table ul boolean cite keyword apiname option parmname cmdname msgnum varname wintitle ph b i sup sub tt u codeph synph filepath msgph systemoutput userinput menucascade uicontrol q term abbreviated-form tm xref state data data-about foreign unknown draft-comment fn indextermref indexterm required-cleanup

dl parml fig syntaxdiagram imagemap image lines lq note hazardstatement object ol pre codeblock msgblock screen simpletable sl table ul boolean cite keyword apiname option parmname cmdname msgnum varname wintitle ph b i sup sub tt u codeph synph filepath msgph systemoutput userinput menucascade uicontrol q term abbreviated-form tm xref state data data-about foreign unknown draft-comment fn indextermref indexterm required-cleanup

image ph (phrase)b (bold)i (italic)u (underline)sup (superscript)sub (subscript)xref (link)data

image ph (phrase)b (bold)i (italic)u (underline)sup (superscript)sub (subscript)xref (link)data


Simplified topic

Eliminate advanced features No prolog metadata or related links

Eliminate redundant markup Only one table model (simplified CALS)

Simplify content models No mixed content: the only place to author

text is in a <p>, and <p> doesn't contain lists or other block-level content

<topic id="mini" domains="(lwdita-c)(no-nested-topics-c) (no-nested-blocks-c)"> <title>Mini topic</title> <body> <p>This topic has constraints that disallow nesting topics and lists.</p> <p>Additional constraints could be applied to get rid of attribute sets based on function, for example eliminating conref.</p> <ul> <li><p>Everything you write goes inside a paragraph.</p></li> <li><p>You can add paragraphs, tables, lists, and media.</p></li> </ul> </body> </topic>


Simplified topic

Easily modified to: Get rid of sections or get rid of content

outside of sections Limit lists to one level

Easy to add or remove capabilities with attributes organized into functional groups: “reuse” adds @id and @conref to <p>, <ul>,

<li> etc. “variable-content” adds @keyref to <ph>

<topic id="mini" domains="(lwdita-c)(no-nested-topics-c) (no-nested-blocks-c)"> <title>Mini topic</title> <body> <p>This topic has constraints that disallow nesting topics and lists.</p> <p>Additional constraints could be applied to get rid of attribute sets based on function, for example eliminating conref.</p> <ul> <li><p>Everything you write goes inside a paragraph.</p></li> <li><p>You can add paragraphs, tables, lists, and media.</p></li> </ul> </body> </topic>


Simplified map

Eliminate advanced features No metadata or reltable

Simplify content models Only one way to specify title: as <navtitle> in

<topicmeta>

<map id="simpleTOCmap" domains="(lwdita-c) (tocref-c)"> <topicmeta> <navtitle>TOC map</navtitle> </topicmeta> <topicref href=”mini.dita”> <topicmeta> <navtitle>Mini topic</navtitle> </topicmeta></map>


Simplified map

Easy to add or remove capabilities with attributes organized into functional groups: “TOC referencing” adds @href “Classification/variables” adds @keys “Link indirection” adds @keyref

Out of the box maps for: Simple TOC Variable/taxonomy management and link

redirection

<map id="simplevarmap" domains="(lwdita-c) (taxo-c)"> <topicmeta> <navtitle>Variable map</navtitle> </topicmeta> <topicref keys=”prodname”> <topicmeta> <navtitle>My Product</navtitle> </topicmeta> </topicref></map>


Simplified specialization

Pull together a new specialization out of building blocks Assemble section types Add phrases and attributes

So simple it can be authored instead of coded Use a specialized authoring topic Fill in the fields and generate the

specialization

<specdef id=”meeting”> <title>Meeting specialization</title> <specdefbody> <sectiondef> <dl> <dlentry> <dt>Goals</dt> <dd> <p><xref href=”goals.dita”/></p> <p>Fill the goals of the meeting</p> </dd> </dlentry> ......


Simplified specialization

Generate more than just DTDs Schemas, RNG... with lightweight schemas

or starter sets for full Overrides for publishing transforms and

editor prompts Even a lightweight authoring prototype for

testing

<meeting id="abc123" domains="(lwdita-c)(all-sections-c) (goals-d) (agenda-d) (minutes-d)> <title>Minutes for 2012 July 18<title> <shortdesc>Discussions of editor scenarios and processing expectations.</shortdesc> <meetingbody> <goals>...</goals> <agenda>...</agenda> <minutes>...</minutes> </meetingbody> </meeting>


But it’s still all just XML

With all the attendant vices and virtues you’ve come to love/hate….

But does it have to be?


It comes in flavors!XDITA (DITA in XML) HDITA (DITA in HTML5)

<topic> <title>The point of it all</title>

<shortdesc>I can sum it up here</shortdesc>

<body> <p>I can say some more stuff</p>

<section>

<title>Stuff</title> <p>And so on</p>

<ul>

<li><p>This</p></li> <li><p>Is</p></li>

<li><p>A List</p></li>

</ul> <section>

<title>And more stuff</title>

<p>With its own explanation</p> <dl>

<dlentry>

<dt><p>This</p></dt> <dd><p>Is explained</p></dd>

</dlentry>

<dlentry> <dt><p>This</p></dt>

<dd><p>Is also explained</p></dd>

</dlentry> </dl>

</section>

</body></topic>

<article> <h1>The point of it all</h1>

<p>I can sum it up here</p>

<p>I can say some more stuff</p> <section>

<h2>Stuff</h2>

<p>And so on</p> <ul>

<li><p>This</p></li>

<li><p>Is</p></li> <li><p>A List</p></li>

</ul>

<section> <h2>And more stuff</h2>

<p>With its own explanation</p>

<dl> <dt><p>This</p></dt>

<dd><p>Is explained</p></dd>

<dt><p>This</p></dt> <dd><p>Is also explained</p></dd>

</dl>

</section></article>


Meet in the middle:Specialize in XML, constrain in HTML5

XDITA HDITA

<video><fallback><p>Here's a video of stuff

you can't see.</p></fallback><controls value="y"/><poster value="screengrab.png"/><source value="mymovie.mp4"

type="video/mp4"/><source value="backupformat.xyz"

type="video/xyz"/><track value="captions.vtt"

type="captions"/></video>

<video controls=“controls” poster="screengrab.png">

<source src="mymovie.mp4" type="video/mp4"/>

<source src="backupformat.xyz" type="video/xyz"/>

<track value="captions.vtt" kind="captions"/>

<p>Here's a video of stuff you can't see.</p>

</video>


Mapping maps

XDITA HDITA

<map>

<topicmeta>

<navtitle>Navigation</navtitle> </topicmeta> <topicref href="abc.dita">

<topicmeta> <navtitle>Topic A</navtitle> </topicmeta>

</topicref> <topicref href="bcd.dita"> <topicmeta>

<navtitle>Topic B</navtitle> </topicmeta> <topicref href="b123.dita">

<topicmeta> <navtitle>Topic B1</navtitle> </topicmeta>

</topicref> </topicref></map

<nav>

<h1>Navigation</h1>

<ul> <li><a href="abc.html">Topic A</a></li> <li><a href="bcd.html">Topic B</a>

<ul> <li><a href="b123.html">Topic B1</a> </li>

</ul> </ul><nav>


A few attributes

XDITA HDITA

@props @data-hd-props

@abc123 (any attribute specialized from @props)

@data-hd-abc123

@conref (on section, table, paragraph, and list elements)

@data-hd-conref (on section, table, paragraph, and list elements)

@keys (on topicref) @data-hd-keys (on <li> inside <nav>)

@keyref (on <image>, <a>, and <topicref> for link indirection, on all inline elements for variable text)

@data-hd-keyref (on <img> and <a> for link indirection, on all inline elements for variable text)


Can DITA jump formats?

vi

Emacs


simple!”

Wiki

Word

“Here’s something simple!!”

markdown “We need more

features!”


Full DITA

HTML5

“Grrrr”

XDITA

HDITA

markDITA

WorDITA

WiDITA

“We need more

features!”

“We need more

features!”


If you like this idea…

Talk about it.

Tell people.

Especially, tell the tool developers, and the vendors.

The two main reasons vendors say they don’t support DITA:

“it’s too complicated”

“people aren’t asking for it”

We’re working on the first one – but we need your help for the second.


Join the discussion

Lightweight DITA discussion group at Linkedin:http://www.linkedin.com/groups/Lightweight-DITA-4943862

Blogging about it at the DITA focus area:http://dita.xml.org/blog/michael-priestley

Start an argument with me on twitter: @Ditaguy

http://www.linkedin.com/groups/Lightweight-DITA-4943862

http://dita.xml.org/blog/michael-priestley


Legal

IBM and the IBM logo are trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at “Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml

does dita need xml? lightweight dita and html5

Internet