RE: [dita-lightweight-dita] templae specialization, some remarks

Hi Tim,

Thanks for the information and all your work.

“Strictly speaking, however, the base <body> element in LW DITA has a sequence content model: any number of block elements (not including the <section> element), followed by any number of section elements.” This (blue) is why I have made a choice-group for all section-elements but maybe that’s not the right way to interpret this content model. I think you are right, we must decide if we want to allow in the specification to change the base content model or not.

Kind regards, Birgit

From: dita-lightweight-dita@lists.oasis-open.org [mailto:dita-lightweight-dita@lists.oasis-open.org] On Behalf Of Tim Grantham
Sent: Tuesday, January 17, 2017 6:37 PM
To: dita-lightweight-dita@lists.oasis-open.org
Subject: RE: [dita-lightweight-dita] templae specialization, some remarks

Hi, everyone.

Here is my response to Birgit’s comments below.

First, the RNG schema generated by the create-schema.xsl stylesheet was broken by a bug in the stylesheet that was messing up the @class attribute. This fix addresses the initial problems Birgit encountered.

Secondly, I have updated Birgit’s marketing template to fix several issues:

I added a doctype declaration to the template topic. (I have tested it with both the LW DITA topic.dtd and the new LW DITA topic.rng RNG schema.) The doctype declaration is required to generate the default values for attributes (including @class and @specmodel), which the stylesheet requires.
I replaced the @important attribute with the required @importance attribute.
I removed the character text from the <fig> element. The LW DITA <fig> element content model does not allow text.

Birgit wants her section specializations to be part of a choice content model for the <marketingbody> content. Strictly speaking, however, the base <body> element in LW DITA has a sequence content model: any number of block elements (not including the <section> element), followed by any number of section elements.

This raises a fundamental design challenge for the stylesheet. Is it even possible for the stylesheet to check whether the specified content model on a specialized element is a valid one? If it’s possible, how much enforcement should it impose?

In the case of Birgit’s marketing topic specialization, for example, the current stylesheet sees that the content model specified on the <marketingbody> element is choice, but it currently “knows” (through a hard-coded variable) that the base <body> element has a content model of sequence. So what should its behaviour be? Should it just issue an error message and stop? Should it just ignore the conflict and process it with the content model specified by the user? What it currently does is issue a warning message and then process the content model of the <marketingbody> element as a sequence. This is not the content model Birgit wants, however. And to add insult to injury, what she wants would not result in any invalid documents because her choice content model is, in this case, a valid subset of the base element’s sequence content model.

Another starker, case: in LW DITA the <dl> element has a sequence content model of one or more <dlentry> elements. Birgit, in her marketing specialization, wants to rename the <dl>, <dlentry>, <dt>, <dd> elements (in her case, to <specifications>, <specification>, <specifiedterm>, <specifieddesc>). If she sets the specmodel attribute on the <specifications> attribute to “sequence”, she has no way in LW DITA to set the number of occurrences of the <specification> element to more than one. She could set the specmodel attribute on <specifications> to “choice” and then set the importance attribute on <specification> to “required”, but this means the stylesheet must allow her, again, to do so on a base element that has a sequence content model.

(We might be able to at least ameliorate the problem by replacing the @importance attribute with an @occurrences attribute, with values “oneormore”, “zeroormore”, and “one”.)

If the stylesheet has no explicit way to check the validity of any content model defined by the user in a template, it’s going to have to allow users to create choice content models for specialized elements derived from base elements that have sequence content models. This will mean users can create choice content models for specialized elements that might break the sequence of the base element content.

On the issue of conversion from RNG to XSD, I discovered an error in my RNG version of the LW DITA DTD that I have fixed. The RNG output by the stylesheet from Birgit’s marketing topic specialization now converts cleanly to XSD. The Trang tool does not appear to be able to convert the RNG to DTD, though I haven’t figured out why yet.

I will follow this email up with the various updated files.

Regards,

Tim.

-------- Oorspronkelijke bericht --------

Onderwerp:	[dita-lightweight-dita] templae specialization, some remarks
Datum:	27-11-2016 11:45
Afzender:	xstructuring02 <xstructuring02@server48.firstfind.nl>
Ontvanger:	dita-lightweight-dita@lists.oasis-open.org

Hello Tim and all,

I have tried to generate a RNG from my marketing-template. This was no problem and I have got a RNG. After I got the RNG I have treid to generate a XSD from it (using Oxygen). The XSD I get is not valide. This depends on some problems.

First: In the RNG stands:

<start combine="choice">
<element name="marketingtopic">
<optional>
<attribute name="class" a:defaultValue="/marketingtopic "/>
</optional>
<ref name="topic.attributes"/>
<ref name="topic.content"/>
<ref name="title"/>
<element name="prolog">
<ref name="prolog.attlist"/>
</element>
<element name="marketingbody">...

There shouldn't stand a <ref name="topic.content"/> because this make that you get twice the element title and prolog etc. I put this ref in a XML commetn before generating the XSD.

After generating the XSD I get error-messages about the elements I have specialized on <p> and <xref>.

E.g. in my template I have:

This become in the RNG

This looks ok, but in the XSD it went wrong and I get the message that "E [Xerces] cos-nonambig: image and image (or elements from their substitution group) violate "Unique Particle Attribution". During validation against this schema, ambiguity would be created for those two particles."

Honestly, I am not sure if the RNG is wrong or that something went wrong during generating the XSD.

Another problem is that because I cannot define a choice group fort the specialization of section I get a required order even if I set important=”optional” for the child elements.

Example:

When I create a XML-document with the RNG I am not allowed to delete feature within the marketingsection. So we really have to think about how we can specialize elements which basic content model is a sequence of an element followed by de choice-group.

Attached you find the template, the RNG and the XSD.

Kind regards, Birgit

dita-lightweight-dita message