single-source publishing across multiple formats with george bina and radu coravu

Single-Source Publishing Across Multiple Formats

Radu Coravu

@[email protected]

George Bina

@[email protected]

Copyright @ Syncro Soft, 2015. All rights reserved.


Overview



Overview The idea



Overview The idea

The implementation



Overview The idea

The implementation

Conclusions and Q&A



Structure



Structure Need for speed = need for structure




Structure is important




Structure is importantnot necessarily the actual form of encoding that structurenot necessarily the actual form of encoding that structure

at a logical level...




Structure is importantConsistent what is really

not necessarily the actual form of encoding that structurenot necessarily the actual form of encoding that structure






Consistent structure → automatic processing

Consistent what is really







Consistent structure → automatic processing

Consistent what is really


So we can convert from one form of encoding to another




Existing structured content



Existing structured contentStructure = DITA or XML (for many of us :)



Existing structured contentStructure = DITA or XML (for many of us :)But, we may already have structured content




in other more or less consistent formats




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 over night that cannot move to DITA at all



Encoding DITA

DITA

XML



Encoding DITA

DITA

Lightweight DITA

XML



Encoding DITA

DITA

Lightweight DITA

XML

Markdown

HTML

we can imagine also other formats



Just imagine...Lightweight DITA can be encoded as HTML

though a convention... can we think the other way around?



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



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?



IdeaURLs → DITA Glass magic URLs

DITATopic(table)XML

excel2dita:/urn:files:sample.xls

urn:files:sample.xls

<topicref href="excel2dita:/urn:files:sample.xls" format="dita"/>

excel2dita



URLsURL = Universal Resource LocatorAny document can be accessed though a URLURL encodes information about the document

http://user:[email protected]/path/to/file.ext?param1=val1&param2=val2

Access protocol Access credentials Server 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 zip:archiveURL!/path/to/file.dita excel2dita:/excelURL



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.



Use casesCross-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



The DITA Glass project

Moving from idea to implementation



Processors pipeline - read only

P1P2...P(n)Original contentConverted content

Support “convert:” URLs:convert:/pipelineStepN/.../pipelineStep1!/targetContentURLconvert:/processor=xslt;ss=urn:processors:csvtext2dita.xsl/processor=wrap!/urn:files:x.csv

Custom URL Handler which converts content via a pipeline of stages



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



Implemented processors Excel to XML JSON to XML HTML to XHTML XSLT/XQuery JavaScript Java Wrap Text as XML



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



Examples of formats

Plain HTMLCustom XMLMarkdownExcelComma separated values (CSV)Documentation in custom HTML formatDocumentation 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 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 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. 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

<topicref href="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"/>



Potential Benefits Access to source documentation and Java

class structure in DITA as syntax diagrams Single source content



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



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



Thank you

[email protected]@georgebina

[email protected]@radu_coravu

http://www.oxygenxml.com

http://www.oxygenxml.com/

single-source publishing across multiple formats with george bina and radu coravu

Technology