DITA-OT Plugin Customization. : Case study: DITA to Qt Help.

Abstract

In a world of rapidly developing technologies accurately structured documentation has become an important part of every successful project. Technical documentation usually includes three types of information: processing instructions, background information, and references. A common attribute of inaccurately written documentation is a mixed structure of the content. That can cause reading inefficiency and confusion for the users.

DITA (Darwin Information Typing Architecture) solves the issue by introducing a strict model of authoring. Every piece of created information shall follow the rules: it shall be focused on a single idea, and belong to one of the offered information types: concept, task or reference. DITA offers XML-based templates for each of these three information types.

DITA-OT (DITA Open Toolkit) is a software tool for processing of DITA source. Information created in DITA can be transformed into PDF, HTML, Web Help and other formats. Apache Ant script, XSLT, and Java are the core languages for the most of the DITA-OT processing modules.

The goal of this project was to develop a DITA-OT transformation scenario that generates Qt help files for Qt Help Framework from the DITA content. The scenario was implemented by creating a DITA-OT plug-in that uses the “DITA to XHTML”, and “Merge DITA content” built-in transformations as an input for generating Qt files. The XHTML transformation was chosen as a better solution than HTML5 due to better compatibility with the XML-based Qt help files. The plug-in was written using Apache Ant script and XSLT scenarios to generate the requested output.

Nopeasti kehittyvän teknologian maailmassa tarkasti järjestelty dokumentaatio tuli tärkeäksi osaksi jokaista onnistunutta projektia. Tekninen dokumentaatio sisältää yleensä kolmenlaista tietoa: käsittelyohjeita, taustatietoa ja viitteitä. Epätarkasti luodun dokumentaation yleinen piirre on sisällön sekarakenne. Tämä voi vaikeuttaa luettavuutta ja johtaa käyttäjien sekaannuksiin.

DITA (Darwin Information Typing Architecture) ratkaisee ongelman ottamalla käyttöön tiukan kirjoitusmallin. Luodessaan luvun kirjoittajan on noudatettava seuraavia sääntöjä: se on keskittynyt yhteen ideaan, ja kuulu yhteen tarjotuista tietotyypeistä tyyppiin: konsepti, tehtävä ja viite. DITA tarjoaa XML-pohjaiset mallit kaikille näille kolmelle tietotyypille.

DITA-OT (DITA Open Toolkit) on DITA-lähteen käsittelytyökalu. DITAlla kirjotettua informaatiota voidaan muuntaa PDF:ksi, HTML:ksi, Web Helpksi ja muiksi tiedostomuodoiksi. Apache Ant script, XSLT, ja Java ovat ydinkielet useimmissa DITA-OT:n pricessointimoduuleissa.

Tämän projektin tavoitteena oli kehittää DITA-OT-muunnosskenaario, joka tuottaa DITA-sisällöstä Qt-ohjetiedostot Qt Help Framework -ohjelmalle. Skenaario toteutettiin luomalla DITA-OT -laajennus, joka käyttää sisäänrakennettuja muunnoksia "DITAsta XHTML:ään" ja "Yhdistä DITA-sisältöä" sisääntulona Qt-tiedostojen luomiseen. XHTML-muunnos valittiin paremmaksi ratkaisuksi kuin HTML5, koska se oli paremmin yhteensopiva XML-pohjaisten Qt-ohjetiedostojen kanssa. Laajennus kirjoitettiin Apache Ant script ja XSLT-skenaarioiden avulla.