DITA Glass

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

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

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.

Java source

JavaDoc

Possible solutions
● Refer to a published version of the Javadoc
documentation through an external link
● Duplicate information like parameter
descriptions in your DITA documentation

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

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

Information Silos
● Marketing
● Development
● Technical
documentation
● Website content
● etc.
Source: http://en.wikipedia.org/wiki/Silo

Problems with information silos
● Duplicate information
– Increased maintenance cost
– Inconsistent data
● Difficult to combine information from multiple
sources into a single publication

One solution
Breaking down the information silos!
Unified information model
(maybe DITA)

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?

DITA
Map
Javadoc to DITA
Excel to DITA
DITA Glass solution:
dynamic content conversion through URLs

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

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

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

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

DITA Glass
Moving from concept to implementation

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

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

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

Implemented processors
● Excel to XML
● JSON to XML
● HTML to XHTML
● XSLT/XQuery
● Javascript
● Java

Examples of third-party formats
Plain HTML
Custom XML
Markdown
Excel
Comma separated values (CSV)
Documentation embedded directly in code}

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"/>

Potential Benefits:
● Dynamically create DITA tables from
spreadsheet tables
● Various table column computations are
automatically done in Excel.
● Single source content

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"/>

Potential Benefits:
● Use online tools to gather content
● Use existing content published by some other
entity

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"/>

Potential Benefits:
● Gather API-related input from developers

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>

Potential Benefits:
● Integrate basic XML Schema documentation in
DITA-based project.

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"/>

Potential Benefits:
● Publish DITA conversion of Javadoc to PDF

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"/>

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"/>

Potential Benefits:
● Publish graphs which dynamically change in
time

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"/>

Potential Benefits:
● Convert database exports to DITA tables
● Edit DITA tables and update CSV content

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

Presentation samples
https://github.com/oxygenxml/dita-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

Thank you
Questions?
radu_coravu@oxygenxml.com
@radu_coravu
george@oxygenxml.com
@georgebina
http://www.oxygenxml.com

DITA Glass

Recommended

Recommended

More Related Content

What's hot

What's hot (14)

Similar to DITA Glass

Similar to DITA Glass (20)

Recently uploaded

Recently uploaded (20)

DITA Glass