dita glass

DITA GlassPerceive everything as DITA

Radu Coravu

@[email protected]

George Bina

@[email protected]

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 referenceinformation 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 itwas a DITA topic

Bring that virtual DITA topic into a map possiblyas a resource only topic and refer to parts of itwhenever you need information from the Javasource



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

http://en.wikipedia.org/wiki/Silo



Problems with information silos● Duplicate information

– Increased maintenance cost– Inconsistent data

● Difficult to combine information from multiplesources 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 documenthttp://user:[email protected]/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 topicencoded 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

MapJava to DITA



A reference to a virtual DITA topicencoded 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 pipelineof 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 oneformat and save in another

convert:/reversePipeline1/…/reversePipelineM/pipelineStepN/.../pipelineStep1!/targetContentURL

P1P2...P(n)

RP1 RP2 ... RP(m)

Target fileEdited file



XML CatalogsDefine 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 fromspreadsheet tables

● Various table column computations areautomatically 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● Single source content



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● Single source content



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 givenname.</documentation> </annotation> <complexType> <all> <element ref="p:family"/> <element ref="p:given"/> </all> </complexType></element>



Potential Benefits:

● Integrate basic XML Schema documentation inDITA-based project.

● Single source content



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● Single source content



Java to DITA● Java to XML● XHTML to DITA

<topicrefhref="convert:/processor=xslt;ss=urn:processors:javaToTopic.xsl/processor=java;jars=urn:processors: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● Single source content



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 topicrefformat values

Implemented in the pre-processing stage of thepublishing engine (DITA-OT)

<topicref href="sample.md" format="markdown"/>

DITA Open Toolkit pre-processing stage whichreceives the stream of content as MarkDownand converts it on the fly to DITA

http://jelovirt.github.io/2015/02/06/dita-markdown.html

http://jelovirt.github.io/2015/02/06/dita-markdown.html



Presentation samples

https://github.com/oxygenxml/dita-glass

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?

[email protected]

@radu_coravu

[email protected]

@georgebina

http://www.oxygenxml.com

http://www.oxygenxml.com/

dita glass

Technology