Using "retroactive specialization" to map non-DITA XML to DITA so that it can be processed and managed with DITA-aware tools.

1. Stupid DITA Tricks:
After-The-Fact Specialization
Treating Aircraft Manuals as DITA
Eliot Kimber
Contrext
DITA Europe 2018

2. About the Author
• Independent consultant focusing on DITA
analysis, design, and implementation
• Doing SGML and XML for cough 30 years cough
• Founding member of the DITA Technical
Committee
• Founding member of the XML Working Group
• Co-editor of HyTime standard (ISO/IEC 10744)
• Primary developer and founder of the DITA for
Publishers project (dita4publishers.org)
• Author of DITA for Practitioners, Vol 1 (XML Press)
DITA Europe 2018

3. Agenda
• What did we need to do?
• How did we do it?
• Was it a good idea?
DITA Europe 2018

4. CLIENT CHALLENGE:
LOCALIZING AIRCRAFT
MANUALS
DITA Europe 2018

5. The Problem
• Get XML from suppliers
• XML is different from each supplier
• XML is not DITA
• Want to manage it as though it were DITA
– Take advantage of DITA tools: CMS, localization,
publishing
– Provide consistent authoring environment
DITA Europe 2018

6. The Project
• Presales proof of concept
• Demonstrate feasibility of using DITA tools to
manage non-DITA source from two different
suppliers
• Required functionality
– Authoring in XML
– Translation workflow support
– Production of PDF for use by airline
– Version management (updates from suppliers)
DITA Europe 2018

7. DITA to the Rescue?
• DITA tools provide strong out-of-the-box
support for localization at reasonable cost
• We know any number of DITA CMS products
could support client's management,
authoring, and translation requirements
• Can we apply DITA in this case?
DITA Europe 2018

8. Challenge: Enable Management
and Translation at Lowest Cost
• If the content was DITA out-of-the-box tools
will do what's needed
• Content is not DITA, does not appear to map
easily to DITA
• Airline authors want one system for working
with both Boeing and Airbus MELs
• How to do it?
DITA Europe 2018

9. WHAT DID WE DO?
DITA Europe 2018

10. The Experiment:
Retroactive Specialization
• Using the markup as provided, add @class
attributes to make it look like a DITA
specialization
• Using XSLT add minimum needed to make it
work as DITA with DITA tools
– Topic IDs
– Keys
– Etc.
DITA Europe 2018

11. Retroactive Specialization
• Add @class and other DITA-required
attributes to existing declarations
• Find closest match but don’t worry too much
about semantics or other DITA rules
• Make heavy use of <div>
DITA Europe 2018

12. Retroactive Specialization
Declaration Example
DITA Europe 2018
<!-- DITA class attribute mappings -->
<!ENTITY % dita-univ-atts-mod SYSTEM "dita-univ-atts.dtd">%dita-univ-atts-mod;
<!ATTLIST description
class CDATA "- topic/topic opsproc_exch/description "
xmlns:ditaarch CDATA #FIXED "http://dita.oasis-open.org/architecture/2005/"
ditaarch:DITAArchVersion CDATA #FIXED "1.3"
domains CDATA "(topic topic) (topic ops-exch-d)"
id ID #IMPLIED
>
<!ATTLIST descitem
%dita-univ-atts;
class CDATA "- topic/div opsproc_exch/descitem " >
<!ATTLIST example
%dita-univ-atts;
class CDATA "- topic/fig opsproc_exch/example " >
<!ATTLIST descbody
%dita-univ-atts;
class CDATA "- topic/body opsproc_exch/descbody " >
<!ATTLIST item
%dita-univ-atts;
class CDATA "- topic/li opsproc_exch/item " >

13. Transform to DITA
• Must adjust the source to make it into working
DITA
• Goal: Do as little as possible
• Will need the reverse transform
DITA Europe 2018

14. Transformation Tasks
• Generate DITA maps
• Assign keys to topics
• Ensure all topics have IDs
• Add wrapper elements where required by
DITA (e.g., topic bodies, <dlentry>, etc.)
• Make links into keyrefs
DITA Europe 2018

15. Let's Look At Some Code
DITA Europe 2018

16. WAS IT A GOOD IDEA?
DITA Europe 2018

17. Did It Work?
DITA Europe 2018
• Yes: As far as we were able to test it
• Achieved:
– Added DITA declarations to DTDs
– Implemented transform to DITA
– Import into CMS as DITA
– PDF generation using Open Toolkit
• Conclusion:
– Approach is sound

18. Was it A Good Idea?
• I think so
• Other alternatives very expensive:
– Buy and maintain supplier's CMS offerings
– Build ground-up CMS specific to supplier
vocabularies
– Build from-scratch authoring and publishing tools
• Result is not "pure DITA" but who cares?
DITA Europe 2018

19. Costs of the Approach
• Requires some amount of transform to and
from original source XML
• Transforms need to be maintained over time
• DITA CMS will still require some amount of
customization
• Publishing tools will require customization
DITA Europe 2018

20. Questions?
DITA Europe 2018

21. Resources
• Minimum equipment list description:
http://nata.aero/data/files/committee_mtgm
emos/bestpracticemineqlistbp.pdf
DITA Europe 2018