Dynamic Information Model (DIM)
The DIM project is an implementation of an intelligent style guide that not only describes the rules the content should follow but can also enforce those rules. Another goal is to be auto-discoverable, style guide topics being annotated with meta information that allows this.
The intelligent style guide from the DIM project is implemented in DITA. Rules
to enforce the style guide prose are encoded using existing DITA markup, we use
a data list (
dl) element placed into a
section marked with the
attribute set to
These embedded rules are instantiations of generic rules defined in a library.
To instantiate a rule, we just need to specify the rule name and values for its
To make the style guide discoverable, we annotate topics with meta information that described what element or attribute use that topic is about. Thus, this information can be used to point the user back to that topic when the user is interested in an element or attribute that topic describes.
The project contains:
Sample style guide that can serve as a starting point for your own style guide - in case you do not have one already. This was contributed by Comtech Services
Library of generic rules, defined as Schematron abstract patters
XSLT script that will generate a Schematron file that contains all the rules defined in the style guide topics, each with a link that points back so the style guide topic where the rule was defined
XSLT script that will generate an oXygen configuration file that will make the style guide topics discoverable from the documentation tool tips oXygen presents for elements and attributes
oXygen framework that extends DITA support to provide DIM specific actions, that allow to easily define new rules and to annotate topics with meta information
Getting started and deliverables
To get started, clone the DIM project and either use the provided style guide as a starting point, or replace that with your own style guide.
If you open a style guide topic in oXygen make sure you enable the
+ DIM style
from the Styles drop down to see the DIM specific actions. Use the provided
DIM specific actions to annotate topics with meta information and to add rules.
Publish the style guide using the oXygen WebHelp transformation into the
info-model/styleguide folder. This can be easily done in oXygen using the
Generate Style Guide transformation scenario.
gen-rules/gen-mappings.xsl on the style
guide DITA map in order to generate the
rules.sch Schematron file and the
contentCompletionElementsMap.xml configuration file.
The generated style guide output, the schematron file and the configuration file are the deliverables of this project. You can use them to provide the integrated style guide experience to your authors in your real project.
Setting up oXygen to use the style guide
To be able to use the intelligent style guide in oXygen, we need to use the generated Schematron schema to validate the documents we want to enforce the style guide rules on, we need to make the published style guide form accessible and to setup the configuration file so that elements and attribute tool tips will point to the style guide topics that describe their usage.
Associate Schematron schema with files
A Schematron schema can be associated with an XML document either within the document itself, using an
xml-modelprocessing instruction, or it can be associated externally, at the application level.
A Schematron validation can be set outside the document, at the framework level. Each framework configuration has a
Validationtab where you can specify a validation scenario. If no scenario is available, create one containing a validation unit that validates the document with the detected schemas. Then add a new validation unit that validates the document with the generated Schematron schema and depending on your preference, you can add that to be part of the automatic validation, or just leave it to be applied only when the authors trigger the validation action themselves, using the validate action.
Make the published style guide accessible
You can place the generated WebHelp form of the style guide either locally or you may publish that on a web server. In the later case you may consider also generating Feedback-enabled WebHelp, rather than simple WebHelp, to allow authors to send you feedback on the style guide content.
Then, you need to edit the
info-model/rules/catalog.xmlfile to update the
rewritePrefixvalue to point to the base location of your published style guide
<rewriteURI uriStartString="http://example.com/styleguide/webhelp/" rewritePrefix="styleguide/webhelp/"/>
Setup oXygen to show tool tips for elements and attributes
This setting can be done as part of a framework, like the DITA framework for example, which is used to provide DITA editing support in oXygen. Let's say you customized the DITA framework by extending it in a framework named
dita-my-project. Then you need to edit the catalog file to update the
<uri name="http://www.oxygenxml.com/dita/styleguide/contentCompletionElementsMap.xml" uri="contentCompletionElementsMap.xml"/>
For each framework, oXygen will try to load this configuration file from such an URL, and if that is mapped by the catalog to some actual configuration file, then that will be automatically used to provide links to style guide topics from the element and attribute tooltips.
These deliverables can be used also with other tools, the style guide can be published to other formats and you can generate different tools configuration file and then set everything up as you want. The DIM project is about generic ideas but it provides a specific implementation using DITA and oXygen.
The DIM project is licensed for use under the Apache License 2.0.
Copyright © 2015, Syncro Soft SRL