Searching the right approach: Specialization with RELAX NG v

[xephon]

Dear all,

I'm currently thinking about how to specialize my DITA environment. It's some kind of greenfield project, so there's not much to care for (because nothing exists). If I'm right (please correct me, if I'm wrong), the DITA movement will (slowly) depart from the old DTD/Schema approach and RELAX NG will be the successor (> DITA 1.3). Which technology should I now use to specialize my environment?

Eliot Kimber has written a conversion tool to convert RELAX NG (XML) to DTDs/Schemas, see RELAX NG and DITA: An Almost Perfect Match.

One of us (Kimber) has implemented XSLT-based transforms to generate conforming DTD, XSD, and RELAX NG compact syntax modules and shells from the RELAX NG XML syntax modules.

This tool is required, because most tools (including the DITA-OT) require the defined architecture as DTDs or Schemas. So it seems, that I don't have to expect any technology conflicts. Am I right?

Because writing RELAX NG seems to be much easier, I think about using RELAX NG now. What do you think, would that be a good approach? I'm a little afraid, because I could not find anything useful about DITA specialization with RELAX NG out there. Would I become a lonesome DITA relaxer with hours and days of trial-and-error sessions?

Cheers,
Stefan

[Radu]

Hi Stefan,

Actually Oxygen already comes with new file templates for creating RNG-based DITA topics.
This is possible because of a DITA OT plugin which comes pre-installed with Oxygen's DITA OT:

OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT\plugins\org.dita-ng.doctypes

and publishing also works from inside Oxygen with RNG-based topics and maps.
George Bina saw the potential of easier DITA specialization using RNG so he set up a project for it:

https://code.google.com/p/dita-ng/

Indeed if you are running DITA OT from the command line or if you are using other tools, publishing RNG-based topics and maps will not work. It will possibly work some time in the future when RNG-based DITA specializations are embraced by the tools but it will probably take a while.

As you suspected, Eliot embraced RNG-based specialization not necessarily because he wanted to directly use RNG-based topics and maps but because he considered RNG-based DITA specialization easier to do with the final stage being a stage of conversion between RNG and XML Schema/DTD which work in most tools nowadays.

Most of the work Eliot did with respect to RNG to DTD conversion should be updated and available in the DITA NG project on Google Code:

https://code.google.com/p/dita-ng

About this question:

Would I become a lonesome DITA relaxer with hours and days of trial-and-error sessions?

I'm not sure If you have time to experiment it might be worth it.

Regards,
Radu

[xephon]

Hi Radu,

thanks for your reply. Has the org.dita-ng.doctypes been tested to work with the DITA-OT 2.x? If not, that would probably be a show-stopper, because my publishing pipeline relies on that.

I'm still unconfident. The last commit of dita-ng is 15 month ago. Further on, neither org.dita-ng.doctypes nor dita-ng has been released on Github. The latest snapshot of org.dita-ng.doctypes I could find is somewhere in the repo of org.dita-ng.doctypes, see here, and the last commit is from 2012.

I'm confused. Is the plugin and dita-ng still under active development? By whom and where? There is an APL 2.0 license in the root of the plugin, so it should be public.

ATM it seems to me, that the RELAX NG DITA approach would be a powerful tech base, that has been abandoned before its initial release. Am I wrong or do I miss something? I don't want to rely on a tech base that forces me to use DITA 1.2 forever, because no one maintains it to work with future releases of the spec.

Cheers,
Stefan

[Radu]

Hi Stefan,

Here's what I know:

The DITA 1.3 standard (which might be released by the end of 2015) will come with two sets of materials, the usual HTML documentation describing the specs and the RNG schemas which specify the structure of each DITA base document.
So the Oasis 1.3 specification will no longer come with XML Schemas or DTDs to describe the DITA structure. And all corrections to the specs will be made in RNG. This would save the Oasis committee having to maintain two sets of schemas like they do for DITA 1.2 (DTDs and XML Schema).

Eliot Kimber is working on perfecting this automatic conversion between RNG and XML Schema/DTDs because it will be necessary in order for tools like the DITA Open Toolkit to ship with the DITA 1.3 schemas in multiple formats (DTD, XML Schema and RNG). So this conversion tool will need to be completed in order for all DITA editor and publishing tools on the market to have access to the schemas in DTD and XML Schema formats.
You could try to contact Eliot directly ekimber@contrext.com, he most probably has more details about this.

After this tool is completed I think most of the DITA 1.3 specializations will be done with RelaxNG and then converted to DTD and XML Schema. Eliot wanted to update his specialization tutorial to also contain steps for specialization done using RNG but he probably had not found the time to do this.

You can still keep your topics and maps DTD based as this allows all existing tools on the market to work with them.

Regards,
Radu

[xephon]

Hi Radu,

thanks, you convinced me. I'm glad to hear that. That's good news

Best regards,
Stefan

[yamahito]

Hi folks,

Now that google code has been shut down, is there an equivalent github repo for dita-ng?

Thanks,
Tom

[Radu]

Hi,

Recent versions of the DITA OT publishing engine (3.2 and newer) have the capabilities to publish RNG-based topics and maps included:

https://github.com/dita-ot/dita-ot/issues/2019

Regards,
Radu

[chrispitude]

You can use the following open-source utility to create RelaxNG DITA grammars from a high-level description:

https://github.com/chrispy-snps/DITA-plugin-utilities

I developed this utility so that we can easily specialize DITA for our own content. We have about 50,000 pages of documentation successfully using the grammars created by this utility.

Here are some examples from our own grammar.

To create an attribute domain module with constrained values for the attribute,

Code: Select all

 <attributedomain filename="paginateAttMod.rng" domain="paginate">
  <specialize attribute="paginate" from="base" model="(keep-with-next|keep-with-previous|top-of-page|keep-together)*"/>
 </attributedomain>

To create an element domain module,

Code: Select all

 <elementdomain filename="snpsDomain.rng" domain="snps-d">
  <specialize elements="syntax-spec ex equation" from="fig">
   <disallow elements="image"/>
  </specialize>
  <specialize elements="infotip mini-toc" from="div"/>
  <specialize elements="returns-section arguments-section short-description usageerrors-section command-group-section example-section example-subsection shortcut-section library-section gui-section license-section syntax-section syntax-def
ault description-section" from="bodydiv"/>
  <specialize elements="description-subsection" from="section"/>
  <specialize elements="project-label writer-instructions" from="draft-comment"/>
 </elementdomain>

To create a constraint module that collects all our domains together, along with some content model restrictions,

Code: Select all

 <constraint filename="snpsConstraint.rng" domain="snps-c">
  <include_domains>topic hi-d snps-d snpsm-t indexing-d sw-d pr-d ui-d ut-d mathml-d deliveryTarget style xformat paginate snpsatt</include_domains>
  <allow domain="hi-d" elements="sup sub"/>
  <allow domain="sw-d" elements="filepath cmdname"/>
  <allow domain="pr-d" elements="codeph"/>
  <allow domain="ui-d" elements="menucascade uicontrol"/>
  <disallow elements="audience author bodydiv boolean brand category cmdname component copyrholder copyright copyryear created critdates data data-about div dl example featnum filepath gui-section index-base index-see index-see-also index-
sort-as indextermref itemgroup lines linkinfo linklist linkpool longdescref longquoteref lq mathmlref navtitle object param permissions platform prodinfo prodname prognum publisher q resourceid revised searchtitle sectiondiv series shortde
sc simpletable sl sli source state stentry sthead strow titlealts tm vrm vrmlist"/>
  <constrain elements="topic"><nesting model="(topic.element|module.element)*"/></constrain>

  <!-- modify some content models -->
  <constrain elements="term"><content model="(text | required-cleanup | \text | ph.element | sup | sub | user-defined | codeph.element)+"/></constrain>
  <constrain elements="syntax-spec"><content model="(figgroup | titled-definition-list | definition-list | endnote | pre | fn | foreign | unknown | option-list | title)*"/></constrain>
</constraint>

The reason I collect all this into a constraint module is so I can share this for module document-type shell definitions without repetition:

Code: Select all

 <topicshell filename="snpsGlossaryShell.rng">
  <title>Synopsys Glossary</title>
  <header>some header</header>
  <root_element>glossgroup</root_element>
  <include_domains>snps-c glossgroup glossentry</include_domains>
 </topicshell>

 <mapshell filename="snpsRelNotesShell.rng">
  <title>Synopsys Release Notes</title>
  <header>some header</header>
  <root_element>relnotes</root_element>
  <include_domains>snps-c</include_domains>
 </mapshell>

 <topicshell filename="snpsTopicShell.rng">
  <title>Synopsys Topic</title>
  <header>some header</header>
  <root_element>topic</root_element>
  <include_domains>snps-c</include_domains>
 </topicshell>