DocBook vs DITA Radu Coravu [email protected] @radu_coravu DITA for Software Documentation About the Author I’m a Hub: Feedback (questions, Open Source Projects End users problems, improvement requests) Help, Blogs/Presentations workarounds Technical Support (Me) Improve Oxygen XML Editor Improve product documentation Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation DocBook vs DITA “Comparing DocBook and DITA is like comparing two different types of birds” Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation DocBook 5 vs DITA 1.3 ● Compare standards/vocabularies ● Compare publishing systems ● Compare documentation/communities Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Short History DocBook DITA ● 1991 – First DTD ● 2001 – First DTD HAL Computer IBM Systems and O'Reilly ● 1998 – OASIS ● June 2005 - OASIS ● Current version: 5.1 ● Current version: 1.3 ● Extensive XML ● Extensive XML vocabulary (366) vocabulary (461) Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Main Purpose DocBook DITA ● Books, articles in web or ● Topic-oriented PDF format information “DocBook is a general “The Darwin Information purpose [XML] schema Typing Architecture (DITA) specification defines a set of particularly well suited to document types for books and papers about authoring and organizing computer hardware and topic-oriented information, as well as a set of software (though it is by mechanisms for combining, no means limited to these extending, and constraining applications).” document types.” Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Versioning DocBook DITA ● Three major versions ● 4 minor versions (1.0, (3, 4 and 5). 1.1, 1.2 and 1.3) ● Numerous minor ● Latest Version is DITA (maintenance) 1.3 releases. ● Latest version is DocBook 5.1. Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation DocBook Specs Versioning Rules ● Minor versions (“point releases,” such as V2.2) could add to the markup model, but could not change it in a backwards-incompatible way. ● Major versions (such as V3.0) could both add to the markup model and make backwards- incompatible changes. ● Major-version introductions must be separated by at least a year. Problems updating from DocBook to DocBook 5 (DocBook 4 for was in 2006). Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Schema DocBook DITA ● Initially: DTD ● Initially: DTD ● Now: Normative - ● Now: Normative - Relax NG, available Relax NG, available also as DTD and XML also as DTD and XML Schema Schema Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Content Reuse DocBook DITA ● xi:include ● Conrefs Problems: Harder to ● Keyrefs validate, duplicate IDs ● Conkeyrefs ● Entity references Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Linking DocBook DITA ● Internal links based on ● Direct/indirect ID/IDREF constraints ● Related links ● Links based on ID/IDRef and ● Relationship tables. XLink standard. Neat stuff: ● You can add links on all DocBook elements ● You can define xreflabel on any element ● Olink (linking across publications) Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Media resources (images, audio, video) DocBook DITA ● Support for ● Only image referencing images, references (direct or videos and audio indirect) resources ● Scale, scalefit, width, ● Scale, scalefit, width, height depth ● Align ● Content area width, depth ● Align ● Valign Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Block Elements Trivia DocBook DITA ● Article ● Topics ● Books ● Div’s – Chapters ● Sections (non- ● Topic (new in 5.1) nesting) ● Sections – Numbered – Recursive – Simple Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Tables DocBook DITA ● CALS table ● CALS table ● HTML table ● Simple table ● Informal table ● Internal table Table related info: Table related info: ● Support for table footer ● Table Orientation attribute ● Table Orientation attribute ● Table page wide scale ● Table page wide scale (pgwide) (pgwide) ● Profiling on any table cell Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Inline Elements Trivia DocBook DITA ● Emphasis with roles ● Bold, italic, instead of underline bold/italic/underline ● Inline equations ● Inline equations ● Inline SVG ● Inline SVG ● UI element refs like ● UI element refs “guibutton, guilabel, “uicontrol” guimenu, guisubmenu” Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Other Common Vocabulary Features ● Keywords ● Index terms ● Footnotes ● Image maps ● Embed SVG and MathML. Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Profiling/Filtering DocBook DITA ● 14 pre-configured ● 7 pre-configured profiling attributes attributes ● Values are semi-colon ● Values are space separated separated ● Filter using transformation ● Filter using DITAVAL parameters file ● You can filter based on any attribute Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Extending/Restricting the vocabulary DocBook DITA ● Once you extend ● Specialize, restrict, vocabulary it's no extend vocabulary longer DocBook Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Mainstream Publishing Engines DocBook DITA ● DocBook XSLTs: ● DITA Open Toolkit HTML, XHTML, (open source): WebHelp, EPUB, HTML5, XHTML, PDF, PDF, Eclipse Help, Eclipse Help Java Help – Based on mixture of – Based mostly on XSLT ANT build files, Java 1.0 and a couple of code and XSLT 2.0 Java extensions stylesheets Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation DocBook Publishing Diagram Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation DITA OT Publishing Diagram Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation PDF Publishing Customizations DocBook DITA ● PDF font, paper size, ● You need XSLT columns can be knowledge and to customized with build customization parameters folder or plugin for any customization ● Special support for FOP, XEP ● Special support for FOP, XEP, Antenna ● Anything else configurable via XSLT House Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation HTML-based Publishing DocBook DITA ● HTML (old), XHTML ● HTML5, XHTML ● Chunked ● Eclipse Help HTML/XHTML ● Eclipse Help ● WebHelp output ● EPUB Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation HTML Publishing Customizations DocBook DITA ● CSS ● CSS ● Lots of parameters ● XSLT customization ● XSLT customization Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Extra DocBook Publishing Features ● Custom Processing instructions ● Some parameter XSLTs generate documentation. ● Java Extensions to: – Add line numbers to program listings – Determine the intrinsic size of an image – Provide syntax highlight in program listing Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Communities DocBook DITA ● DocBook Users List ● DITA Users List (general questions) (Yahoo Group, Google Group) ● DocBook Apps Users List (publishing- ● DITA-OT Users List related) (Google Group) Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Online Help Resources DocBook DITA ● Vocabulary ● Vocabulary – DocBook Definitive Guide – DITA Specification ● Publishing: ● Publishing: – DocBook Complete Guide – DITA Open Toolkit documentation Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Trends DocBook DITA Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Questions ● Why is DocBook getting replaced by DITA? ● Do we have anything to learn from the DocBook specification? ● Do we have anything to learn from the DocBook publishing system? Copyright @ Syncro Soft, 2014. All rights reserved. DITA for Software Documentation Thank You! Questions? Radu Coravu [email protected] @radu_coravu Copyright @ Syncro Soft, 2014. All rights reserved..