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.
DITA Glass
Perceive everything as DITA
Radu Coravu
@radu_coravu
radu_coravu@oxygenxml.com
George Bina
@georgebina
george@o...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glas...
Upcoming SlideShare
Loading in …5
×

DITA Glass

1,185 views

Published on

In an ideal world, all documentation content would come in one format (and that format should be DITA). But let's face it, content produced in a company is diverse and comes in many forms and sizes.

So how can we single source everything? Can we integrate contributors who use formats like language-specific API documentation, HTML, MarkDown or even Excel spreadsheets or database tables in a DITA-based workflow? Could we convert everything to DITA on the fly? Could we use a magic glass to perceive various data sources as DITA?

We may try to convince everybody to produce DITA content but this may not be always possible. Instead of that we can accept these diverse data formats but look at them as different ways of encoding DITA. So if we put in place the right decoder we will get back our DITA content.

Published in: Technology

DITA Glass

  1. 1. DITA Glass Perceive everything as DITA Radu Coravu @radu_coravu radu_coravu@oxygenxml.com George Bina @georgebina george@oxygenxml.com
  2. 2. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Radu George Overview ● API documentation example ● Generalize to other formats ● DITA Glass idea – URLs and DITA Glass URLs ● DITA Glass prototype implementation ● DITA Glass in action – Excel, CSV, Google Sheets, HTML, MarkDown, JavaDoc, XML Schema to DITA – XML to SVG ● Conclusions and Q&A George and Radu
  3. 3. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Let's start with an example Given: ● A Java SDK ● Java comments within the source ● Javadoc generated documentation Requirements ● Provide an SDK API tutorial in DITA The API tutorial should include reference information for available classes, methods, etc.
  4. 4. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Java source
  5. 5. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass JavaDoc
  6. 6. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Possible solutions ● Refer to a published version of the Javadoc documentation through an external link ● Duplicate information like parameter descriptions in your DITA documentation
  7. 7. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass The DITA Glass solution Point to a Java file using a special URL, as if it was a DITA topic Bring that virtual DITA topic into a map possibly as a resource only topic and refer to parts of it whenever you need information from the Java source
  8. 8. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Many information formats ● XML based formats ● DITA, DocBook, custom XML schema ● Source embedded API documentation ● Javadoc, Doxygen ● HTML ● Markdown ● Office formats ● Spreadsheets, documents, presentations ● PDF
  9. 9. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Information Silos ● Marketing ● Development ● Technical documentation ● Website content ● etc. Source: http://en.wikipedia.org/wiki/Silo
  10. 10. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Problems with information silos ● Duplicate information – Increased maintenance cost – Inconsistent data ● Difficult to combine information from multiple sources into a single publication
  11. 11. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass One solution Breaking down the information silos! Unified information model (maybe DITA)
  12. 12. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Reality This does not really work, at least not over night! Slow down factors: – volume and time of converting the content – people skills – they need to learn new technologies/tools – tools need to be updated to support the unified format – complexity of the unified format This may not be the right solution What can we do in this permanent transition phase?
  13. 13. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass DITA Map Javadoc to DITA Excel to DITA DITA Glass solution: dynamic content conversion through URLs
  14. 14. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass URLs URL = Universal Resource Locator Any document can be accessed though a URL URL encodes information about the document http://user:password@www.example.com/path/to/file.ext?param1=val1&param2=val2 ● Access protocol ● Access credentials ● Location ● Resource path ● Processing parameters
  15. 15. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass A reference to a DITA topic <topicref format="dita" href="URL" /> file:/path/to/file.dita http://server/cgi?file=file.dita DITA XML https://server/path/to/file.dita ftp://server/path/to/file.dita zip:URL!/path/to/file.dita
  16. 16. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass A reference to a virtual DITA topic encoded as a Java file convert:/processor=xslt;ss=urn:processors:javaToTopic.xsl/ processor=java;jars=urn:processors:jars;ccn=j.to.xml.JavaToXML!/ urn:files:java/WSEditorBase.java URL scheme Java-XML to DITA XSLT-based conversion Java source to Java-XML Target Java file Map Java to DITA
  17. 17. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass A reference to a virtual DITA topic encoded as an Excel file convert:/processor=xslt;ss=urn:processors:excel2d.xsl/ processor=excel;sn=sample!/urn:files:sample.xls URL scheme XML to DITA XSLT-based conversion Excel to XML conversion Target Excel file Map Excel to DITA
  18. 18. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass DITA Glass Moving from concept to implementation
  19. 19. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Processors pipeline -read only P1P2...P(n) Original contentConverted content Support “convert:” URLs: convert:/pipelineStepN/.../pipelineStep1!/targetContentURL Custom URL Handler which converts content via a pipeline of stages
  20. 20. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Processors pipeline – read/write ● A processor only converts one way ● But a pipeline can also contain reversed processors which output content ● So you can potentially edit content in one format and save in another convert:/reversePipeline1/…/reversePipelineM/ pipelineStepN/.../pipelineStep1!/targetContentURL P1P2...P(n) RP1 RP2 ... RP(m) Target fileEdited file
  21. 21. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass XML Catalogs Define aliases for different conversions and resource collections convert:/processor=xslt;ss=urn:processors:excel2d.xsl/ processor=excel;sn=sample!/urn:files:sample.xls excel2dita:/urn:files:sample.xls <rewriteURI uriStartString="excel2dita:/" rewritePrefix="convert:/processor=xslt;ss=urn:processors:excel2d.xsl/processor=excel;sn=sample!/"> <rewriteURI uriStartString="urn:processors:" rewritePrefix="processors/"/> <rewriteURI uriStartString="urn:files:" rewritePrefix="resources/"/> file://path/to/.../resources/sample.xls
  22. 22. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Implemented processors ● Excel to XML ● JSON to XML ● HTML to XHTML ● XSLT/XQuery ● Javascript ● Java
  23. 23. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Examples of third-party formats Plain HTML Custom XML Markdown Excel Comma separated values (CSV) Documentation embedded directly in code}
  24. 24. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Excel to DITA ● Excel to XML ● XML to DITA Topic <topicref href="convert:/proc=xslt;ss=excel2d.xsl/proc=excel;sn=sample!/urn:files/sample.xls"/> <topicref href="excel2dita:/urn:files/sample.xls"/>
  25. 25. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Potential Benefits: ● Dynamically create DITA tables from spreadsheet tables ● Various table column computations are automatically done in Excel. ● Single source content
  26. 26. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass HTML to DITA ● HTML to XHTML ● XHTML to DITA <topicref href="convert:/proc=xslt;ss=h2d.xsl/proc=xhtml!/urn:files/care.html" format="dita"/> <topicref href="html2dita:/urn:files/care.html" format="dita"/>
  27. 27. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Potential Benefits: ● Use online tools to gather content ● Use existing content published by some other entity ● Single source content
  28. 28. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass MarkDown to DITA ● MarkDown to HTML ● HTML to XHTML ● XHTML to DITA <topicref href="convert:/proc=xslt;ss=h2d.xsl/proc=xhtml/proc=js;js=converter.js..!/../sample.md"/> <topicref href="md2dita:/urn:files/sample.md"/>
  29. 29. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Potential Benefits: ● Gather API-related input from developers ● Single source content
  30. 30. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass XML Schema to DITA ● Preserve annotations ● Show content model <topicref href="convert:/processor=xslt;ss=urn:proc:xsdToTopic.xsl!/urn:files/personal.xsd"/> <topicref href="xsd2dita:/urn:files/personal.xsd"/> <element name="name"> <annotation> <documentation>Specifies the person family and given name.</documentation> </annotation> <complexType> <all> <element ref="p:family"/> <element ref="p:given"/> </all> </complexType> </element>
  31. 31. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Potential Benefits: ● Integrate basic XML Schema documentation in DITA-based project. ● Single source content
  32. 32. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Javadoc to DITA ● Javadoc HTML to XHTML ● XHTML to DITA <topicref href="convert:/proc=xslt;ss=urn:proc:jdToTopic.xsl/proc=xhtml/!/urn:files:ButtonEditor.html"/> <topicref href="javadoc2dita:/urn:files:ButtonEditor.html"/>
  33. 33. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Potential Benefits: ● Publish DITA conversion of Javadoc to PDF ● Single source content
  34. 34. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Java to DITA ● Java to XML ● XHTML to DITA <topicref href="convert:/processor=xslt;ss=urn:processors:javaToTopic.xsl/processor=java;jars=urn:proc essors:jars;ccn=j.to.xml.JavaToXML!/urn:files:WSAuthorEditorPage.java"/> <topicref href="javadoc2dita:/urn:files:WSAuthorEditorPage.java"/>
  35. 35. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Dynamic reports in DITA ● Excel to XML ● XML to SVG ● SVG referred in DITA topic <image href="convert:/proc=xslt;ss=sales.xsl/proc=excel;sn=sample!/../sales.xml"/>
  36. 36. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Potential Benefits: ● Publish graphs which dynamically change in time ● Single source content
  37. 37. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass CSV to DITA (and back...) ● CSV (Comma separated values) to DITA ● DITA to CSV <topicref href="convert:/rprocessor=xslt;ss=urn:processors:dita2csv.xsl/ processor=xslt;ss=urn:processors:csvtext2dita.xsl/processor=wrap !/urn:files:sample.csv" format="dita"/>
  38. 38. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Potential Benefits: ● Convert database exports to DITA tables ● Edit DITA tables and update CSV content
  39. 39. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Related work Processor support for different DITA topicref format values Implemented in the pre-processing stage of the publishing engine (DITA-OT) <topicref href="sample.md" format="markdown"/> DITA Open Toolkit pre-processing stage which receives the stream of content as MarkDown and converts it on the fly to DITA http://jelovirt.github.io/2015/02/06/dita-markdown.html
  40. 40. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Presentation samples https://github.com/oxygenxml/dita-glass
  41. 41. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Conclusions ● DITA Glass can seamlessly bring together different formats in a single DITA publication ● Simple, yet very powerful – just refer a resource thought a URL ● A generic approach, not limited to DITA - see the XML data to SVG graphics example ● Available as part of oXygen 17
  42. 42. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved. DITA GlassDITA Glass Thank you Questions? radu_coravu@oxygenxml.com @radu_coravu george@oxygenxml.com @georgebina http://www.oxygenxml.com

×