Re: [dita-lightweight-dita] Lightweight DITA specialization topic to RELAX-NG schema stylesheet

[Carlos Evia <cevia@vt.edu>]

This looks very interesting. 

Yes, let's talk about it Monday during the call.

Also, let's talk about my presentation for the big TC on Tuesday. They expect me to give an update on LwDITA, and I can run my speech by the SC before the actual call.

Thank you,

Carlos

-- 

Carlos Evia, Ph.D.

Director of Professional and Technical Writing

Associate Professor of Technical Communication

Department of English

Center for Human-Computer Interaction

Virginia Tech

Blacksburg, VA 24061-0112

(540)200-8201

On Fri, Oct 28, 2016 at 11:58 AM, Tim Grantham <tgrantham@timgrantham.com> wrote:

Hello, everyone.

 

I have updated the template tool and its associated files. I’m proposing adding the following content to the readme.md file. Let me know if you have any questions or concerns about it. Or we can review it during the call on Monday. After the review, I’ll send all the files to Carlos and Mark for upload to the repository.

 

How to Use the Template Tool

The template tool consists of a single XSLT stylesheet called “create-schema.xsl”. It generates an RELAX-NG schema from a valid Lightweight DITA template topic.

 

To run the stylesheet on the template topic, you need to have the following files all in the same directory:

·         Your template topic

·         create-schema.xsl

·         topic.rng and topicMod.rng

·         commonElementsMod.rng

·         highlightDomain.rng

 

You also need a tool that can apply the stylesheet to the template topic, one that supports XSLT 2.0. To test the generated schema, you will also need an XML editor that can validate DITA topics against an RNG schema. oXygen 18 can provide both of these capabilities.

 

The basic steps to using the tool:

1.       Create your template topic, following the rules defined above.

Note: This version of the stylesheet does not support the @specrole attribute, or the use of @conref attributes.

2.       Run the create-schema.xsl stylesheet, using the template topic as the input (source) document.

3.       Save the output (result) document as an .rng file in the same directory as the other .rng files specified above.

4.       Create a test XML topic, inserting the following statement immediately after the XML declaration:

<?xml-model href=""><your-specialization>.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>

 

Template Tool Future Development

Still to do:

·         Split the output from the stylesheet into two modules: topictype.rng and topictypeMod.rng.

·         Consolidate the current LW DITA RNG files into two files: topic.rng and topicMod.rng.

·         Add jing-trang, a program that generates DTDs and XSDs from RNG schemas.

·         Add support for the @specrole attribute.

·         Incorporate the files into a plugin for the Open Toolkit.

 

Template Tool Design Goals

Beyond meeting the requirement for an XSLT stylesheet that could generate a RELAX-NG schema based on the proposed template specialization features of Lightweight DITA, the template tool has also been designed to be as compatible as possible with the full DITA 1.3 standard, so that a future version could support template specialization for DITA 1.3. Consequently, the supplied RELAX-NG schemas of the Lightweight DITA DTDs are simply edited versions of the existing RELAX-NG schemas for the full DITA 1.3 standard, and so use the same structural and naming conventions. The current version of the stylesheet absolutely depends on these conventions, so that it can, for example, efficiently inherit the content model of a base element, but still define a new @class attribute and content model for the specialized element.

 

An additional design goal was to enable specializations of specializations. The current design therefore requires a minimal but necessary level of modularity, and a file naming convention, for the two RNG schema files that should be generated by the tool: a topictype.rng file, a “shell” schema that declares the root element and that includes by reference topictypeMod.rng, a file that defines the content model for the root element. When a user wants to create a topic specialization from another specialized topic, they can define the template using the latter specialization, and the tool will automatically enable inheritance of that specialization’s content model.

 

Testing the Template Tool

The template tool needs more testing to expose errors in the following areas:

·         In the RELAX-NG schemas for the base Lightweight DITA topic type, which have been edited from the schemas for DITA 1.3 to conform to the current version of the LW DITA DTD.

·         In the XSLT stylesheet. Errors could arise from a misunderstanding of the design requirements, or from faulty logic or design.

 

Version 0.4 of the create-schema.xsl stylesheet includes some minimal error checking, including not permitting a value of “choice” for @specmodel when the base element has a content model of sequence. More error checking should be added, especially to catch content modelling errors like setting the @importance attribute to “required” on an element when the parent’s content model has been defined as “choice”. Eventually, the stylesheet might have to be able to inspect the base element’s schema to determine whether the user has set valid values for the @specmodel and @importance attributes, and to provide appropriate guidance for fixing the errors.

 

Examples

The template tool includes the following example files:

·         template.dita, which defines a new topic type called “tlotermtopic”, which includes definitions of specialized domain elements and a specialization of the @props attribute.

·         tlotermtopic.rng, a schema generated by create-schema.xsl when it is applied to template.dita

·         tlotermtopic.dita, an example tlotermtopic document that conforms to the tlotermtopic.rng schema