In today's world, we cannot expect to find a single format for information across an enterprise. People write spreadsheets, markdown, HTML, comments within the source code of different programming languages, structured XML based documents, and so on. This makes it very difficult to publish — as a single publication — content that originates in different formats, without re-encoding that in a common format. We propose the use of URLs to dynamically convert content from one format to another, thus we avoid duplicating information and realize single source publishing across multiple formats. As long as the information has a structure that is machine processable, we should be able to convert from one form of encoding to another. For example, if you have a table encoded as an Excel sheet then you can get a DITA topic out of that just by referring to that file with a URL like "excel2dita:/path/to/excel/file.xls". To test how this actually works, we implemented such URLs that perform dynamic conversions for: Excel to DITA Google Sheets to DITA JavaDoc to DITA Java source to DITA Markdown to DITA HTML to DITA Custom XML format to SVG Comma Separated Values to DITA and back (to test also round-tripping support) Basically, with this simple dynamic conversion technology (just use a URL to point to files in different format and get them as DITA or some other format) we can bridge between formats with advantages of avoiding duplicating content and thus reducing work and potential errors and being able to provide a unified publishing framework across different formats. This presentation was given at Information Development World on October 2, 2015.

1. Single-Source Publishing Across
Multiple Formats
Radu Coravu
@radu_coravu
radu_coravu@oxygenxml.com
George Bina
@georgebina
george@oxygenxml.com

2. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Overview

3. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Overview

The idea

4. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Overview

The idea

The implementation

5. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Overview

The idea

The implementation

Conclusions and Q&A

6. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Structure

7. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Structure

Need for speed = need for structure

8. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Structure

Need for speed = need for structure

Structure is important

9. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Structure

Need for speed = need for structure

Structure is important
not necessarily the actual form
of encoding that structure
not necessarily the actual form
of encoding that structure
at a logical level...

10. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Structure

Need for speed = need for structure

Structure is important
Consistent what is really
not necessarily the actual form
of encoding that structure
not necessarily the actual form
of encoding that structure
at a logical level...

11. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Structure

Need for speed = need for structure

Structure is important

Consistent structure → automatic processing
Consistent what is really
not necessarily the actual form
of encoding that structure
not necessarily the actual form
of encoding that structure
at a logical level...

12. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Structure

Need for speed = need for structure

Structure is important

Consistent structure → automatic processing
Consistent what is really
not necessarily the actual form
of encoding that structure
not necessarily the actual form
of encoding that structure
So we can convert from one form of encoding to another
at a logical level...

13. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Existing structured content

14. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Existing structured content
Structure = DITA or XML (for many of us :)

15. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Existing structured content
Structure = DITA or XML (for many of us :)
But, we may already have structured content

16. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Existing structured content
Structure = DITA or XML (for many of us :)
But, we may already have structured content
− in other more or less consistent formats

17. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Existing structured content
Structure = DITA or XML (for many of us :)
But, we may already have structured content
− in other more or less consistent formats

HTML files

Markdown

Excel or other spreadsheets

CSV

Java source files

etc.

18. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Existing structured content
Structure = DITA or XML (for many of us :)
But, we may already have structured content
− in other more or less consistent formats

HTML files

Markdown

Excel or other spreadsheets

CSV

Java source files

etc.
− that cannot move to DITA over night

19. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Existing structured content
Structure = DITA or XML (for many of us :)
But, we may already have structured content
− in other more or less consistent formats

HTML files

Markdown

Excel or other spreadsheets

CSV

Java source files

etc.
− that cannot move to DITA over night
− that cannot move to DITA at all

20. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Encoding DITA
DITA
XML

21. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Encoding DITA
DITA
Lightweight DITA
XML

22. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Encoding DITA
DITA
Lightweight DITA
XML
Markdown
HTML
we can imagine
also other
formats

23. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Just imagine...
Lightweight DITA can be encoded as HTML
though a convention... can we think the other
way around?

24. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Just imagine...
Lightweight DITA can be encoded as HTML
though a convention... can we think the other
way around?
− An HTML file is an encoded DITA topic
− An Excel file encodes a DITA topic containing a table
− A Java source file encodes a DITA topic that describes
the methods and fields and other information about a
Java class

25. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Back to DITA
Why do we need to get back to DITA (XML)?
How can we get back to DITA (XML) from these
different formats that encode DITA content?

26. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Idea
URLs → DITA Glass magic URLs
DITA
Topic
(table)
XML
excel2dita:/urn:files:sample.xls
urn:files:sample.xls
<topicref href="excel2dita:/urn:files:sample.xls" format="dita"/>
excel2dita

27. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
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

Server

Resource path

Processing parameters

28. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
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
zip:archiveURL!/path/to/file.dita
excel2dita:/excelURL

29. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Not only DITA...
We can use the same idea for any dynamic
conversion from one format to another:
− other XML documents: DocBook, TEI, XHTML, etc.
− dynamic SVG images
− process an Excel sheet with XML processing languages
like XSLT, XQuery, XProc, etc.
− etc.

30. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Use cases
Cross-format publishing using DITA tools of

entire documents
− just refer a “virtual” topic from a DITA map

parts of a document
− refer the “virtual” topic in a DITA map as resource only
− conref the part that you want from a published topic

31. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
The DITA Glass project
Moving from idea to implementation

32. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Processors pipeline - read only
P1P2...P(n)
Original contentConverted content
Support “convert:” URLs:
convert:/pipelineStepN/.../pipelineStep1!/targetContentURL
convert:/processor=xslt;ss=urn:processors:csvtext2dita.xsl/processor=wrap!/urn:files:x.csv
Custom URL Handler which converts content via a pipeline
of stages

33. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Processors pipeline – read/write

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
convert:/rprocessor=xslt;ss=urn:processors:dita2csv.xsl/
processor=xslt;ss=urn:processors:csvtext2dita.xsl/processor=wrap!/urn:files:x.csv
P1P2...P(n)
RP1 RP2 ... RP(m)
Target fileEdited file

34. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Implemented processors

Excel to XML

JSON to XML

HTML to XHTML

XSLT/XQuery

JavaScript

Java

Wrap Text as XML

35. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
URL Syntax Example
Define aliases in XML Catalog:
convert:/processor=xslt;ss=/path/to/excel2d.xsl/
processor=excel;sn=sample!/path/to/sample.xls
excel2dita:/urn:files:sample.xls
<rewriteURI uriStartString="urn:processors:" rewritePrefix="processors/"/>
<rewriteURI uriStartString="urn:files:" rewritePrefix="resources/"/>
Final URL Form:
<rewriteURI uriStartString="excel2dita:/"
rewritePrefix="convert:/processor=xslt;ss=urn:processors:excel2d.xsl/processor=excel;sn=sample!/">

36. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Examples of formats
Plain HTML
Custom XML
Markdown
Excel
Comma separated values (CSV)
Documentation in custom HTML format
Documentation embedded directly in code

37. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
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"/>

38. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Potential Benefits

Dynamically create DITA tables from
spreadsheet tables

Various table column computations are
automatically done in Excel.

Single source content

39. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
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"/>

40. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Potential Benefits

Use online tools to gather content

Use existing content published by some other
entity

Single source content

41. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
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"/>

42. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Potential Benefits

Gather API-related input from developers

Single source content

43. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
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>

44. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Potential Benefits

Integrate basic XML Schema documentation in
DITA-based project.

Single source content

45. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
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"/>

46. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Potential Benefits

Publish DITA conversion of Javadoc to PDF

Single source content

47. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
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"/>

48. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Potential Benefits

Access to source documentation and Java
class structure in DITA as syntax diagrams

Single source content

49. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
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"/>

50. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Potential Benefits

Publish graphs which dynamically change in
time

Single source content

51. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
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"/>

52. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Potential Benefits

Convert database exports to DITA tables

Edit DITA tables and update CSV content

53. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Presentation samples
https://github.com/oxygenxml/dita-glass

54. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Conclusions

DITA Glass can seamlessly bring together
different formats in a single DITA publication

Simple, yet very powerful idea – just refer a
resource thought a URL

A generic approach, not limited to DITA - see
the Excel data to SVG graphics example

Available as part of oXygen 17

55. Copyright @ Syncro Soft, 2015. All rights reserved.
Single-Source Publishing Across Multiple Formats
Thank you
Questions?
george@oxygenxml.com
@georgebina
radu_coravu@oxygenxml.com
@radu_coravu
http://www.oxygenxml.com