Copyright (c) 2016 Freescale Semiconductor Inc.

Ruby gem that will allow ruby constructs to print dita elements.

Currently, Dita is defined by a large set of inter-dependent XML schema files too complex to convert to code using automated means (e.g. JAXB). Consequently, there does not exist a software API for Dita generation in any language. This project's goal is to remedy this by manually creating this API in Ruby, starting with the most commonly used Dita elements and eventually creating a full representation of Dita 1.2 (with some backwards compatibility with earlier versions) in Ruby, and eventually in other languages.

Although this may appear to be a Ruby project, Ruby-Dita primarily consists of the file xml/dita_grammar.xml, which is read by a separate gem Duxml (itself a wrapper for Ox). Please help by expanding that file with more Dita schema rules. See the Duxml documentation on how.

Features - Duxml's lazy-XML shortcuts - Static Dita file validation - Run-time Dita input validation

Roadmap: - Dita documentation made available via code so users don't have to look it up online - Auto-complete/suggest, particularly for large complex elements like Table (see Duxml roadmap) - Undo changes (see Duxml roadmap)

The end result should be a Dita 1.2 API that enables software generation of documentation.

 Q: Why Ruby?
 A: Because of its ease-of-use. Most technical documentation experts are not programmers. Also, the fundamental problem of abstracting technical data into human-readable content is much easier to handle with Ruby's powerful OOP model.

 Q: Why manual conversion?
 A: Because Dita 1.2 is primarily defined in RelaxNG and JAXB's RelaxNG conversion function is experimental. XSD definitions are too complex and would require so much massaging of the files to make them convertible that a manual effort would actually be much faster.

 Q: Who needs this?
 A: Increasingly, technical documentation is being generated by software directly from the design data. However, the results are often not fit for customer-level publication. Dita offers an open-source means of publishing to common web and print formats with enterprise levels of quality. However, experts in documentation are not usually programmers, and programmers do not know or want to learn all of the rules of Dita. This project can be the bridge between the two groups.

from console

gem install ruby-dita

in Ruby

require 'ruby-dita'
include Dita

load or create document

load 'your_file.xml'

edit document

doc << Element.new('topic')
doc.topic << Element.new('title')
doc.topic[:id] = 'topic_id'

set history to be tolerant (strict by default - grammar violations trigger Exception); violations will only log error to history but not interrupt processing

doc.history.strict?(false)

table(column_info, rows)    => #Dita table

topic(title, id)            => #Dita topic