1.
DITA Glass
Perceive everything as DITA
Radu Coravu
@radu_coravu
radu_coravu@oxygenxml.com
George Bina
@georgebina
george@oxygenxml.com

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.
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.
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glass
Java source

5.
Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
DITA GlassDITA Glass
JavaDoc

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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