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.

Previous | Next | Home page for the second review

Important: Reviewers, be sure to preface comments with your name and the date, for example, [Eberlein, 18 September 2009]

[WEK, 10 Dec 2009] All comments addressed.

Specialization Module Coding Requirements

[gerjosep, 19 Oct 2009] Review completed.

Recognized XML document constraint mechanisms

[gerjosep, 19 Oct 2009] Review completed.

Constraints domain module DTD coding requirements

[Frankland 5 October 2009]

. . . that defines the constrained content model. For example, the strictTopicConstraints.mod syntax is:

. . .

For example, the strictstrictTopicDomainConstraints.mod syntax is:

[WEK, 10 Dec 2009] Comment obsolete due to other editorial changes.


[s.park 7 oct]: The example entity declaration for topic-constraints is "(topic strictTopic-c)". In strictTaskbodyConstraint.mod, taskbody-constraints is defined as "(topic task strictTaskbody-c)".

The logic supplied for constructing this entity does not explain why "topic" is part of the taskbody-constraints definition. Please help!

In the "Requirements for domain constraints modules", all content except for the first two paragraphs are copy/paste from the structural section. Did you want to make it domain specific?

DTD syntax specialization module coding requirements

[gerjosep, 19 Oct 2009] Review completed.

General element type declaration coding requirements

[gerjosep, 19 Oct 2009]

In section "Module names", remove the bold text, since it's not needed (we say e.g., so etc. does not make sense):

For structural modules, the module name must be the element type name of the top-level topic or map type defined by the module, e.g. "concept", "bookmap", etc.

==>

For structural modules, the module name must be the element type name of the top-level topic or map type defined by the module, e.g. "concept" or "bookmap".

[WEK, 10 Dec 2009] Done.

Same comment applies to the next paragraph:

For element domain modules, the module name must be a name that reflects the subject domain to which the domain applies, e.g. "highlight", "software", etc. Domain module names should be sufficiently unique that they are unlikely to conflict with any other domains.

==>

For element domain modules, the module name must be a name that reflects the subject domain to which the domain applies, e.g. "highlight" or "software". Domain module names should be sufficiently unique that they are unlikely to conflict with any other domains.

[WEK, 10 Dec 2009] Done.

In the "Module files" section:

For domain modules the file name is the domain name plus Domain plus the ent extension, e.g. highlightDomain.ent, newAttDomain.ent.

==> added missing comma

For domain modules, the file name is the domain name plus Domain plus the ent extension, e.g. highlightDomain.ent, newAttDomain.ent.

[WEK, 10 Dec 2009] Done.

General comment: Some of the example code could be better formatted. I can change the source files if need be.

[WEK, 10 Dec 2009] Looks like the formatting got hosed at some point. Fixed.

In the "Element Definitions" section, the last paragraph about the descriptive comment should be moved up in the section. It's lost here, and since the comment usually is the first thing in the element declaration, I feel it should be towards the top. Or at least before the example code.

[WEK, 10 Dec 2009] Done.

[bnevin 20090925]

Structural and element domain vocabulary modules must reflect the same coding requirements for element type declarations. > The coding requirements for element type declarations are the same for structural modules and element domain vocabulary modules.

[WEK, 10 Dec 2009] The short description is a statement of conformance requirement. Therefore the suggested rewrite is not appropriate because it loses the explict "must" statement.

[s.park 7 oct]: Under "Element definitions", it says that each element type must a parameter for the content model and attlist of a certain name, %tagname.content and %tagname.attributes. Is this really a requirement? Is it new to 1.2 to support constraints? If it is new to 1.2, can we say it?

[WEK, 10 Dec 2009] It is a requirement and it is new and no we will not say it is new here, but in the "what's new appendix".

Structural module coding requirements

[gerjosep, 21 Oct 2009]

The last section has the title "Topic and map element attributes" but the paragraph and example apply only to topic. Should we have a similar paragraph and example for the map element, or fix the existing paragraph to include reference to the map element? I've suggested the latter fix as follows:

The topic element type must set the DITAArchVersion attribute to the DITAArchVersion entity and the domains attribute to the included-domains entity. These attributes give processors a reliable way to check the architecture version and look up the list of domains available in the document type.

==>

The topic or map element type must set the DITAArchVersion attribute to the DITAArchVersion entity and the domains attribute to the included-domains entity. These attributes give processors a reliable way to check the architecture version and look up the list of domains available in the document type.

[WEK, 10 Dec 2009] Fixed by adding "or map".

[s.park 7 oct]: The first para says, "The purpose is usually to enhance the user's interaction by making unused elements unavailable."

Isnt the preferred method of limiting element availability in 1.2 via constraints? I'd prefer to claim that the purpose of specialization is to define new content models that provide semantics specific to a particular set of user requirements. Maybe we should remove the second sentence completely?

[WEK, 10 Dec 2009] Removed the reference to making unused elements unavailable, leaving it as "The purpose is usually to enhance the user's interaction by adapting the topic or map type to its particular purposes."

Topic and map element attributes Do we want to tell users to declare the architecture entities in the structural vocabulary module?

[WEK, 10 Dec 2009] The &DITAArchVersion; entity is declared in one of the base declaration sets. It is not declared by specializers.

Topic type module coding requirements

[gerjosep, 21 Oct 2009] Review completed.

[s.park 7 oct]: The last codeblock shows the legacy concept declaration; shouldnt it be the declaration for "concept.content"?

[WEK, 10 Dec 2009] Fixed.

Element domain module coding requirements

[gerjosep, 21 Oct 2009]

The declaration (.ent) file must define an entity for each element extended by the domain. The base of the entity name is the abbreviation for the domain and the extension of the entity name is the name of the extended element. For example,the highlight domain (abbreviated as hi-d) extends the ph element, so the entity for the extended element is named hi-d-ph.

==> missing space after commma

The declaration (.ent) file must define an entity for each element extended by the domain. The base of the entity name is the abbreviation for the domain and the extension of the entity name is the name of the extended element. For example, the highlight domain (abbreviated as hi-d) extends the ph element, so the entity for the extended element is named hi-d-ph.

[WEK, 10 Dec 2009] Fixed.

Attribute domain module coding requirements

[gerjosep, 21 Oct 2009]

This comment is probably not for this topic, but it needs to be called out somewhere... I didn't find documentation on when to use @props and when to use @base. I think the arch spec should provide some idea of what the intended use of each is, and scenarios of when one would use one over the other. Reading the spec, I get the impression these 2 attributes are synonyms, in which case the obvious question is why do we have both? I think that @props is for profiling attributes and @base is for everything else.

[WEK, 10 Dec 2009] You are correct in your understanding of @base and @props. @base is not really useful in practice because there would be few global attributes you'd want to add that were not really @props attributes. I would revisit this comment during the 3rd review and try to determine where best to address this bit of detail.

XSD schema specialization module coding requirements

[gerjosep, 21 Oct 2009] Review completed.

General element type declaration coding requirements

[gerjosep, 22 Oct 2009]

In the "Module names" section, remove the "etc." from the following paragraphs:

For structural modules, the module name must be the element type name of the top-level topic or map type defined by the module, e.g. "concept", "bookmap", etc.

For element domain modules, the module name must be a name that reflects the subject domain to which the domain applies, e.g. "highlight", "software", etc. Domain module names should be sufficiently unique that they are unlikely to conflict with any other domains.

[WEK, 10 Dec 2009] Done.

[gerjosep, 25 Oct 2009]

In section "Element definition", the last paragraph should use "examples", not "example", since there are more than one example above in this section:

Each xs:element declaration should include descriptive documentation as in the example above.

[WEK, 10 Dec 2009] Done.

Structural specialization coding requirements

[gerjosep, 25 Oct 2009]

In section "Structural specialization coding requirements":

An XSD structural module declares a top-level map or topic type, implemented as a pair of XSD documents, one that defines groups used to integrate and override the type and one that defines the elements types specific to the type.

==> delete 's'

An XSD structural module declares a top-level map or topic type, implemented as a pair of XSD documents, one that defines groups used to integrate and override the type and one that defines the element types specific to the type.

In section "Structural module schema document"

The root element must reference the DITAArchVersion attribute and domains attribute. These attributes give processes a reliable way to check the architecture version and look up the list of domains available in the document type. The DITAArchVersion attribute is referenced as in the following example:

==> typo

The root element must reference the DITAArchVersion attribute and domains attribute. These attributes give processors a reliable way to check the architecture version and look up the list of domains available in the document type. The DITAArchVersion attribute is referenced as in the following example:

Attribute domain coding requirements

[gerjosep, 25 Oct 2009]

Is the bold word in the following paragraph correct?

The attribute must be reflected in a using shell doctype XSD by including the value "a(baseAttNameattname)" in the domains attribute for the top-level type used by the shell, where baseAttName is one of "base" or "props", whichever the new attribute is specialized from. For example, if the attribute named "new" is a specialization of the props attribute, the domains value would be "a(props new)".

[WEK, 20 Dec 2009] Corrected use proper terminology.

Customization

[gerjosep, 25 Oct 2009]

The bold word "spec" should be "specification":

An element specialization may be required that is inconsistent with the existing DITA hierarchy. Three methods are available to extend beyond the standard, at the cost of losing some of its benefits. Using any of these methods results in vocabulary modules that do not conform to the DITA specification. Documents that use these vocabulary modules may or may not be conforming documents, depending on whether or not they contain components that are not allowed by the DITA spec (for example, attributes not provided by the DITA specification or specialized from props or base).

[WEK, 10 Dec 2009] Done.

This topic refers to "DITA specification" and "DITA standard" interchangeably. We should probably use one or the other, not both.

[WEK, 10 Dec 2009] Done.

In the following paragraph, I suggest we refer to the DITA TC comments page:

You should specialize from the semantically closest match whenever possible. When some structural requirement forces you to pick a more general ancestor, please inform the technical committee: over time a richer set of generic elements should become available.

[WEK, 10 Dec 2009] I don't disagree but I'm not sure what the comments page's URL or other citation is or should be.

The following paragraph is missing a space:

For example, if an authoring group requires the <p> element to be spelled out as <paragraph>, the document type could be customized to change <p> to <paragraph>for authoring purposes. Documents so created can then be preprocessed to rename <paragraph> back to <p> before feeding them into a standard publishing process.

[WEK, 10 Dec 2009] Done.

SpecializationModuleCodingRequirements (last edited 2009-12-10 19:55:02 by ekimber)