1. A Document Standards Interoperability Framework for DocBook, DITA, ODF and More! www.oasis-open.org Scott Hudson

2. Fraternal Twins?  Optimized for book-oriented deliverables  Widely supported  Well- documented  Large user community  Designed for multiple outputs  Designed for topic-based authoring and re- use  Designed for interoperability  Highly flexible specialization  Designed for multiple outputs Both designed for technical documentation!

3. In Search of the Holy Grail n Content Sharing, Reuse and Re-Purposing has always been the “Holy Grail” of Publishing

4. Interoperability is Needed!  Sharing information between trading partners or OEMs who use different standards  Sharing information between areas in the same organization that have implemented different standards  Sharing content between “non-XML” users and XML Content developers (Knowledge Transfer)  Transitional strategy as an organization moves between content standards, but has existing applications that share data  Compatibility with tools that are optimized for a different standard  Syndication!  Leverage, Repurpose content from many sources

5. Today’s Reality n Old and New Forms of Collaboration l OEMs and Partners l Intra-Organizational l Mergers/Acquisitions l Syndication n Multiple XML Document Standards l DocBook l DITA l TEI l ODF l Microsoft Office Open XML n How do I reconcile/leverage/reuse content from disparate standards?

6. n Because DocBook, DITA and other standards will co-exist, these standards need to be interoperable, but they’re not… Yet. n A common set of element definitions and models as a base for each standard will require much more collaboration between standards. n Both standards contain methods to extend their respective standard: l Specializations in DITA l Customization layers in DocBook Interoperability: Current State

7. Chapter DITA BookMap Text… Chapter Topic (Sub-Topic) Topic (Sub-Sub-Topic) Topic Topic (Front Matter) Topic (Back Matter) Section (Topic) Section (Sub-Topic) Section (Sub-Sub-Topic) Section (Topic) Front Matter Back Matter DocBook Master Document Insight: Parallel View of DITA and DocBook DITA Topic DocBook Section

8. A Closer Look At DITA Structures Book (bookmap) Meta (bookmeta) Title conref conref (href) TopicRef (topicref) 1 Chapter (chapter, appendix) ChapterRef (chapter) Topic (topic) Title Meta (topicmeta) TopicBody MediaRef Topic Nested Topics Media (image, object) Book (bookmap) Meta (bookinfo) ChapterRef (chapter) Chapter (chapter, appendix) Title TopicRef (topicref) Topic (section) Title Meta (sectioninfo) TopicBody Media MediaRef, Nested Topics section XInclude Topics Publications Book (book) Meta (bookinfo) ChapterRef Title Topic (section) Title Meta (topicmeta) TopicBody Media MediaRef, Nested Topics XInclude Chapter (chapter, appendix) Book (bookmap) Meta (bookmeta) Title (booktitle) topicref (href) Topic Reference (topicref) Chapter (chapter, appendix, etc.) Chapters Topic (topic) Title (title) Meta (topicmeta) Body (topicbody) Media (image, object) Topic (topic) Nested Topics Media Object (jpg, gif, mpeg, wav, etc.) Front Matter (frontmatter) Topic Reference (topicref) Publication-Level Assembly Chapter-Level Assembly Topic Chunk Media Object href Topic Chunk conref

9. A Closer Look At DocBook Structures Book (bookmap) Meta (bookmeta) Title conref conref (href) TopicRef (topicref) 1 Chapter (chapter, appendix) ChapterRef (chapter) Topic (topic) Title Meta (topicmeta) TopicBody MediaRef Topic Nested Topics Media (image, object) Book (bookmap) Meta (bookinfo) ChapterRef (chapter) Chapter (chapter, appendix) Title TopicRef (topicref) Topic (section) Title Meta (sectioninfo) TopicBody Media MediaRef, Nested Topics section XInclude Topics Publications Book (book) Meta (bookinfo) ChapterRef Title Topic (section) Title Meta (topicmeta) TopicBody Media MediaRef, Nested Topics XInclude Chapter (chapter, appendix) Book (book) Meta (info | bookinfo) Title (title) Entity Reference | XInclude Topic Reference (Entity Reference) Chapter (chapter, appendix, etc.) Chapters Topic (section) Title (title) Meta (info | sectioninfo) Body (IMPLIED) Media (mediaobject) Topic (section) Nested Topics Media Object (jpg, gif, mpeg, wav, etc.) Front Matter Topic Reference (Entity Reference) Publication-Level Assembly Chapter-Level Assembly Topic Chunk Media Object href Topic Chunk Entity Reference | XInclude

10. l Content Interoperability n “Shoehorning” l Processing Interoperability n “Uni-directional” l Roundtrip Interoperability n “Bi-Directional” Strategies for Interoperability

11. n DITA elements can be specialized with DocBook element names so authors can create content as valid simplified DocBook sections and refsections, while also being valid DITA specialized topics! n Likewise, DITA elements can be added to a DocBook customization layer to allow DITA topics as siblings of DocBook sections. n Drawback: No official specialization or customization layer exists. If you customize DocBook, it’s not DocBook anymore! Is there a better way? Content Interoperability

12. n DocBook books should be able to include DITA topics by reference. Using a transform, this content could be preprocessed into DocBook and finally output with the DocBook stylesheets. n Similarly, DITA maps or topics should be able to reference DocBook articles or sections. Using a transform, this content could be preprocessed to produce DITA and then processed using the DITA Open Toolkit. n Drawback: How do you handle validation? how do you address different versions of the standards? Is there a better way? Processing Interoperability

13. n Roundtrip interoperability uses transforms to convert content directly from DocBook to DITA and vice versa n Drawback: Requires multiple stylesheets to address different versions of the standards. Does not allow roundtrip to other standards. Is there a better way? Roundtrip Interoperability

14. Version Chaos DITA 1.1 1.0 DocBook 5.0 4.5 4.4 4.3 4.2 S1.1 S1.0

15. “What a Tangled Web we Weave” DITA 1.1 1.0 DocBook 5.0 4.5 4.4 4.3 4.2 S1.1 S1.0 1.0 ODF More?

16. Version Control DITA 1.1 1.0 DocBook 5.0 4.5 4.4 4.3 4.2 S1.1 S1.0 1.0 ODF Interop Framework More?

17. Yes, there is a better way! n Roundtrip interoperability via content transforms to a neutral interchange format n Maintain stylesheet transforms to and from this neutral interchange format n Allows interoperability between more than just DocBook and DITA (for example, Open Document Format and more!) n And… without inventing a new grammar Doc Standards Interoperability Framework

18. Bridging content standards in a meaningful way!

19. Why Include ODF?  People already use it  Proof point for providing interoperability to other standards  Microsoft OpenXML  LegalXML  TEI  ?  Potential use of ODF as a surrogate authoring application that doesn’t know about DocBook or DITA!

20. Choosing an Interoperability Framework Standard n Not another new grammar! Please?!? l Hard to keep up with existing standards l Re-Use/Re-purpose an existing standard l Leverage existing tools, technology l Shorter learning curve, faster adoption rate n What DITA, DocBook, ODF (and others) have in common? l Designed for producing Content! l Common Structural Components n Headings (Sections) n Paragraphs n Lists n Tables n Images n etc.

21. What’s Behind the Interoperability Framework? n XHTML Microformats l http://microformats.org/about/ http://microformats.org/about/ l “Semantic HTML” l Humans first, machines second l Provides basic structural abstractions common to “content-based” XML standards (DocBook, DITA, ODF, etc.) l All of these standards have HTML renditions anyway n Transitional XHTML 1.0 l Well-formed XML with a DTD using HTML markup

22. Implementing Microformats n Use XHTML elements for “common” structures l table, p, ul, ol, img, code, pre, abbr, acronym n Use “generic” structural elements as abstraction layer l div, span n Use “title” attribute to store original element name n Use “class” attribute to specify “semantic category” n Preserve additional semantic data l Use tag n Valid virtually anywhere n Attributes as elements n Enable introspection... l Use namespaced attribute/value pairs

23. Preserving Source Mappings The Goal: Preserve Source Semantics In the Interchange DITA - outputclass is the appropriate mapping extension to preserve semantics DocBook - remap attribute designed for preserving source transforms DocStandards Interoperability Framework – utilizes a combination of title attribute and an object child or namespaced attributes to store source metadata element contains metadata (origin format, Interop declarations) element contains content payload

24. Mapping the Standards DITA Element n title n steps n step n substeps n p n ul n ol n note type=“note” n note type=“caution” n note type=“warning” n b n u n i DocBook Element n title n procedure n step n substeps n para n itemizedlist n orderedlist n note n caution n warning n emphasis role=“bold” n emphasis role=“underline” n emphasis role=“italic” To develop the interoperability framework, a mapping of content elements between the standards will be needed: DocStandards Interoperability Framework Elements Other Doc Standards (ODF, etc.)

25. Mapping Rules n Not all elements have a 1:1 mapping n Some markup will be implied to and from framework: Interoperability Framework (XHTML) DocBook DITA

26. Example DITA Source

27. Example Interoperability Format

28. Interoperability Format to DocBook

29. Interoperability Format to DITA

30. Interoperability Format to ODF

31. How High is the Fidelity?

32. Roundtrip Fidelity DocBook Interoperability Framework DITA Interoperability Framework DocBook

33. DITA Roundtrip Example OR DocBook Interoperability Framework DITA

34. Purity vs. Practicality n “It’s not pure [Insert XML Standard Here]”

35. What Can You Do With the Framework?  Enable interoperability between two or more standards  Enable interoperability between different versions of each applied standard  “Unlock” content in proprietary formats for initial migration to XML Document Standards  Apply the 80/20 rule to semantic accuracy

36. Proposed OASIS TC n Flatirons has proposed an OASIS Technical Committee to continue evolving the Interoperability Framework l docstandards-interop-discuss@lists.oasis-open.org docstandards-interop-discuss@lists.oasis-open.org l Standards members include: n Michael Priestley (DITA) n Scott Hudson (DocBook, DITA) n Don Harbison (ODF) n Jim Earley (DocBook, DITA)

37. Proposed OASIS TC charter n The Doc Standards Interoperability TC is intended to address: l the development and documentation of scenarios for cross-standard content sharing; l a specification for an interoperability framework, including mappings from participating standard formats to the framework; l and requirements on participating standards to improve interoperability.

38. A Call to Arms We need your: Awareness Support Participation! For more information: Email thoughtleader@flatironssolutions.com to subscribe to our whitepaper mailing listthoughtleader@flatironssolutions.com Download our whitepaper at flatironssolutions.com docstandards-interop-discuss@lists.oasis-open.org