This Wiki page is designed to collect comments on the second review of the DITA 1.2 specification, 21 September - 3 October 2009. This review is being conducted by members of the OASIS DITA Technical Committee.
Important: Reviewers, be sure to preface comments with your name and the date, for example, [Eberlein, 18 September 2009]
[WEK, 10 Dec 200] All comments addressed.
[gerjosep, 19 Oct 2009]
The only possible exceptions to this is when a constraint disallows (or requires) an element type that is optional in the unconstrained type but that a processor expects to always occur (or never occur) (for example, because local editorial practice requires it [or precludes it] or other validation mechanisms have required it [or disallowed it] in the past). However, because constraints cannot make required elements optional, constraints can never create the case where an expected and required element on which processing depends is no longer present in constrained instances.
The only possible exception to this is when a constraint disallows (or requires) an element type that is optional in the unconstrained type but that a processor expects to always occur (or never occur) (for example, because local editorial practice requires it [or precludes it] or other validation mechanisms have required it [or disallowed it] in the past). However, because constraints cannot make required elements optional, constraints can never create the case where an expected and required element on which processing depends is no longer present in constrained instances.
[WEK, 7 Dec 2009] Done.
Constraints domain module DTD coding requirements
[gerjosep, 19 Oct 2009]
It's not clear to me what the difference is between a structural constraints module and a domain constraints module, from the examples. I tihnk the example for the domain constraints should help the reader understand this. My confusion probably stems from not understand which domain we're constraining in the example in the last section of the topic.
[WEK, 7 Dec 2009] Updated the example to show an actual domain constraint--the example that was there was just a copy of the topic constraint. Doh.
Constraints domain module XSD coding requirements
[gerjosep, 21 Oct 2009, section titled "strictTopicConstraint.xsd"]
Change section title "strictTopicConstraint.xsd" to "Example of a structural constraints module" and then add a paragraph that says something like "The following code sample shows how the <topic> element may be constrained to create a stricter form of the element. This xs:redefine element would be placed in a file named strictTopicConstraint.xsd."
Also, the example contains the following comment:
constrain content and attributes of <topic> element
[WEK, 10 Dec 2009] Done.
I don't see any code that constrains the attributes, so I think we should remove the bold text or change the example to constrain attributes as well. Alternative, we could add some code that demonstrates constraining attributes, which would probably be useful to implementers who are not overly familiar with the XSD syntax.
Regarding the following paragraph:
For selective restriction there must be a group with a subset list of extension elements for a domain in a reusable constraints module. The group name should be named "qualifierdomain-c-tagname" where qualifier is a for the constraint vocabulary constraint module file, domain is the name of the domain, map, or topic being constrained, and tagname is the name of the extension element being restricted.
It's not clear to me how this fits in. I also don't understand what exactly is being said in this paragraph. What has this got to do with the current example? Should this paragraph be moved to before the examples? It may be a good idea to provide an example of what's being described in this paragraph. Reading further I realized this paragraph belongs to the next example. Move to next section, as indicated in my comment on the next example.
[WEK, 10 Dec 2009] Putting borders on the example figures should address the "what does this text apply to issue" in advance of more thoughtful rework of the content at some future time.
[gerjosep, 21 Oct 2009, section titled "basicHighlightConstraint.xsd"]
- Change the title of this section to "Example of a domain constraints module"
Add a paragraph saying something like: "The following code sample shows how the highlight domain may be constrained to limit the elements that are available in the domain to only <b> and <i>. This code would be placed in a file named basicHighlightConstraint.xsd."
- Move the paragraph that currently precedes this section (the one I didn't understand in the previous section) to this section, before the example.
[gerjosep, 21 Oct 2009, section titled "strictTopic.xsd (shell)"]
Remove this title, and replace it with a <p> that says something like: "The following code sample demonstrates the markup used to constrain the standard <topic> element. This code would be placed in a shell file named "strictTopic.xsd".
I think Eliot was trying to separate the examples out from the normative spec info, which I'm in favor of, but the current rendering results in a confusing format that confuses the reader. We should eventually allow for <example> to be rendered in a way that its title is not formated like section/title.
[WEK, 10 Dec 2009] I've done two things. First, I've set frame=all on the figures that hold the inline examples. That should hopefully provide sufficient visual distinction to avoid confusion of figures with sections. Second, I've created a new topic with more complete examples copied from the original submissions.