[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Some comments on the dita 1.2 spec
I will plan to insert our comments into the various wiki pages under http://wiki.oasis-open.org/dita/TechReview1 but just to make sure they get in on time and get archived, I'm also including them below. paul ================ I have not commented on editorial issues (typos, grammatical issues, wording issues, etc.) and rarely on the prose itself. I tried to concentrate on the overall technical content. I'm assuming we will do another pass for the details later on. ----- Are we going to use the convention that capitalized words and phrases such as MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, MAY NOT, REQUIRED, and OPTIONAL have very specific means that are different than the uncapitalized uses of the same words or phrases? I think we should. We'd previously agreed on a draft version of a conformance statement that would define these and some other terms for use in the DITA 1.2 specification, but I don't see that information anywhere in the draft. See http://www.oasis-open.org/apps/org/workgroup/dita/email/archives/200803/ msg00028.html ----- In "About the DITA 1.2 specification" it says: The technical specification consists ...DTDs and schemas [that] define DITA markup for the base-DITA document types.... While the DTDs and schemas should define the same DITA elements, the DTDs are normative.... In "Concrete Document Types and Modules" it says: While the DITA standard provides a starter set of shell DTDs and schemas, these shells are not normative.... There seems to be a contradiction here. Exactly what is normative? My understanding is that the document type shells included as part of the specification are normative, but not definitive or not exhaustive. ----- In "DTD organization" it says: A new DTD can change one or both of these features and still be valid. We should avoid the word "valid" as that has specific XML meaning. Besides, it has no real DITA meaning. I suspect what's meant here is "compliant with the DITA architecture" or some such. Same issue with "XML Schema organization". ----- In "DTD organization", the list of public identifiers: includes the following that aren't in the DITA 1.2 catalog: PUBLIC "-//OASIS//DTD DITA 1.1 Concept//EN" "concept.dtd" PUBLIC "-//OASIS//DTD DITA 1.0 Concept//EN" "concept.dtd" PUBLIC "-//OASIS//DTD DITA 1.1 Composite//EN" "ditabase.dtd" PUBLIC "-//OASIS//DTD DITA 1.0 Composite//EN" "ditabase.dtd" PUBLIC "-//OASIS//DTD DITA 1.1 Glossary//EN" "glossary.dtd" PUBLIC "-//OASIS//DTD DITA 1.1 Reference//EN" "reference.dtd" PUBLIC "-//OASIS//DTD DITA 1.0 Reference//EN" "reference.dtd" PUBLIC "-//OASIS//DTD DITA 1.1 Task//EN" "task.dtd" PUBLIC "-//OASIS//DTD DITA 1.0 Task//EN" "task.dtd" PUBLIC "-//OASIS//DTD DITA 1.1 Topic//EN" "topic.dtd" PUBLIC "-//OASIS//DTD DITA 1.0 Topic//EN" "topic.dtd" PUBLIC "-//OASIS//DTD DITA 1.1 Map//EN" "map.dtd" PUBLIC "-//OASIS//DTD DITA 1.0 Map//EN" "map.dtd" PUBLIC "-//OASIS//DTD DITA 1.1 BookMap//EN" "bookmap.dtd" and is missing the following that are in the DITA 1.2 catalog: PUBLIC "-//OASIS//DTD DITA 1.x Concept//EN" "concept.dtd" PUBLIC "-//OASIS//DTD DITA 1.x Composite//EN" "ditabase.dtd" PUBLIC "-//OASIS//DTD DITA 1.x Glossary//EN" "glossary.dtd" PUBLIC "-//OASIS//DTD DITA 1.x Reference//EN" "reference.dtd" PUBLIC "-//OASIS//DTD DITA 1.x Task//EN" "task.dtd" PUBLIC "-//OASIS//DTD DITA 1.x Topic//EN" "topic.dtd" PUBLIC "-//OASIS//DTD DITA 1.x Map//EN" "map.dtd" PUBLIC "-//OASIS//DTD DITA 1.2 Map//EN" "map.dtd" PUBLIC "-//OASIS//DTD DITA 1.x BookMap//EN" "bookmap.dtd" PUBLIC "-//OASIS//DTD DITA General Task//EN" "generalTask.dtd" PUBLIC "-//OASIS//DTD DITA 1.x General Task//EN" "generalTask.dtd" PUBLIC "-//OASIS//DTD DITA 1.2 General Task//EN" "generalTask.dtd" Also missing--but perhaps intentionally so--are all those for: subjectScheme.dtd classifyMap.dtd all the learning ones machineryTask.dtd ----- In "XML Schema organization", under XML Schema catalog identifiers, the entire listing is wrong. It gives URLs instead of the URNs. See the catalog-dita-xsd.txt file in the latest DITA 1.2 set of XSDs. Are we distributing the URL based XML schemas as part of DITA 1.2? If so, should we say something like: The DITA 1.2 specification includes both URN and URL based versions of the XML schemas. The URL versions are included as a convenience for use with tools that do not support catalog based resolution and are not normative. ----- In "Topic content" it says that images can be inserted at the block level. The image element can also be inserted within a block (aka inline), so we should just remove the words "at the block level". Same thing with object (Multimedia) which can also be inserted inline. ----- I don't think we should repeat the "Topic modules" under topics. It is just giving a list of DTD and XSD modules, and that's already been done under the general introduction part. ----- In "Definition of DITA maps" it says: DITA maps are documents that collect and organize references to DITA topics to indicate the relationships among the topics. . . . A DITA map file references one or more DITA topic files using <topicref> elements. That completely leaves out the fact that maps can reference maps. We need to augment this discussion to include maps referencing maps. Likewise with the "Purpose of DITA maps" topic. ----- In "DITA map attributes and metadata": 1. Under "Attributes shared by DITA maps and DITA topics", we say: DITA maps use the same metadata and reuse attributes that are used by DITA topics: Instead of 'same' and 'reuse', use the same terminology of 'common metadata' and 'common attributes'. Somewhere 'locktitle' needs to be addressed from a map level. Since it does not cascade, at a map level, it is obsolete. The list of attributes should include: dir, search. 2. Under "toc, navtitle, locktitle": <locktitle? can override <navtitle>, but not <title>, which is the main title. Some of these attributes take values from ancestors, and some don't. Such cascading is mentioned in the description of some of the other attributes, but is missing for these three. Note: Somewhere there needs to be a description of use of locktitle vs. lockmeta and its use with navtitle metadata. 3. Under "processing-role" the phrase "cascades from previous topics" should be "cascades from the closest ancestor". 4. Under "scope" (and perhaps elsewhere) don't we mean "cascade" instead of "inherit"? ----- Under "Inheritance of attributes and metadata in maps" we say: Inheritance is additive except where this would cause a conflict. Inheritance is additive only on those attributes that accept multiple values. Otherwise explicit values override implicit values. The "Specifying a value for the chunk..." sentence seems out of place. And "chunk" isn't in the list of attributes that cascade shown above. A section that appears to be missing is the map to map cascading behavior. Explicit attribute values cascade from map to the map element of the sub map. Presumably metadata follows the same rules. Metadata would override metadata on the top level map tag of the map. If there is no explicit metadata tag on the submap, then one would be 'added' for processing. ----- Under "Topic properties in topics and maps": Regarding "Attributes or child elements of <topicref> element", we agree with the statement in the spec and not the draft comment. The short description should override the corresponding short description. The navtitle should override the corresponding navtitle, etc. No need to single out one to behave differently. Regarding "Shared metadata elements, and the lockmeta attribute": The locktitle attribute works differently. The locktitle deals with navtitle, element and attribute, which is an aberration from the norm of lockmeta. The locktitle attribute would still apply separately to the navtitle metadata. ----- Under "Metadata inheritance between maps and topics": We seem to be missing a discussion of map to map cascading of metadata. Does the <audience> information supplement or override like-named audience? In other words is it a wholesale replacement of information if the names are the same, or is it another audience added with the SAME name, etc. So when we say 'add' does this mean add as new, replace what may be on the topic, override some values that are not specified on topics, or override everything in a topic. This is the same for elements. In the table: * <navtitle> for DITA 1.2 needs to be added. * <shortdesc> Does not override topic short description? ----- I don't think we should repeat the "DITA map modules" under DITA maps. It is just giving a list of DTD and XSD modules, and that's already been done under the general introduction part. ----- Under "Miscellaneous Attributes" it says xml:lang is described at http://www.w3.org/TR/REC-xml/#sec-lang-tag (which is true), but then goes on to say its values are "as described in RFC 4646". But the referenced part of the XML spec says: The values of the attribute are language identifiers as defined by [IETF BCP 47], Tags for the Identification of Languages; in addition, the empty string may be specified. I suggest we just delete the "as described in RFC 4646" phrase. ----- In "IDs and references" it says: URIs are described in RFC 2396. RFC 2396 is obsolete. URIs are now described in RFC 3986. ----- In "IDs and references" the first sentence of this section reads: Because topics are the basic units of information within DITA, the id attribute for the topic must be unique within the document instance. That's not really true in that the reason for the conclusion is not what the "because" statement says. The last sentence of this section reads: The id attribute for DITA topics is of type ID in XML, and so must be unique within the document instance. That statement is correct. Furthermore, the first sentence seems out of place even if it were correct. I suggest just deleting the first sentence of this section. ----- Under "DITA processing" there is a "Navigation behaviors" topic with very little content except mentions of tocs, related links, and indexing. Other than the obvious commonly understood ideas of tocs, links, and indexes, what processing is explained here? Is any of this processing "DITA processing"? If so, we need to explain it. If not, then it shouldn't be listed under "DITA processing". ----- I assume the "Attribute inheritance" topic remains to be written (as least as of the July 17 build I am reviewing). ----- Under "Chunking" I assume the "Topicheads and [implicit] title-only topics" part remains to be written. ----- In "The xml:lang attribute" we say: This attribute must be set to a language identifier, as defined by IETF RFC 4646 (http://www.ietf.org/rfc/rfc4646.txt) or successor. That's not true--because it can also take the null value--but it's also not good to do an end-around the XML spec which is the spec that really defines xml:lang. We should just say xml:lang is described in the XML spec at http://www.w3.org/TR/REC-xml/#sec-lang-tag, perhaps: The xml:lang attribute is described in the XML Recommendation at http://www.w3.org/TR/REC-xml/#sec-lang-tag . ----- In "The xml:lang attribute" under "Usage in maps" we say: The expected language inheritance behavior on the map.... The inheritance of xml:lang is defined in the XML spec, and we can't change that, so we shouldn't talk about it. However, we're not really talking about inheritance here (from map to topic), we're talking about cascading, so the fix here is to change the word "inheritance" to "cascading". ----- In "Specialization, constraints, and concrete document types", fourth para, we say: Each vocabulary module has a globally-unique name by which it can be referenced (e.g., a PUBLIC ID or absolute URI). In fact, the XSDs use URNs for which the modifier "absolute" is not exactly appropriate. We should delete the word "absolute". ----- In "Recognized XML document constraint mechanisms" the bulleted list reads: XML document type declarations XSD Schema That should read: XML document type declarations (DTDs) XML Schema declarations (XSDs) and later in the following paragraph, where we say: XML DTDs and XSD Schemas it should be: XML DTDs and XSDs ----- In "Element type class hierarchy declaration (the class attribute)" we say: The class attribute provides a mapping from the element's current name and its more general equivalents. I suggest instead: The class attribute usually provides a mapping from the element's current name to its more general equivalents, but it can also provide a mapping from the current name to more general and more specialized equivalents. ----- In "Element type class hierarchy declaration (the class attribute)" it should be made clearer that there must be (at least one) space following the initial - or +. Also, while I would assume that the term "space-separated" means one or more spaces, since this is a specification, it must be made clearer whether multiple spaces are allowed or not. Perhaps something like: The class attribute syntax is as follows: * An initial "-" or "+" character, "-" for element types defined in structural vocabulary modules, "+" for element types defined in domain modules followed by one or more spaces. * Followed by a sequence of one or more module/type pair tokens of the form "modulename/typename", with each pair of tokens separated by one or more spaces, where modulename is the short name of the vocabulary module and typename is the element type name, e.g., "topic/topic", "topic/p", "hi-d/i", etc. Tokens are ordered left to right from most general to most specialized. For example, the value of the class attribute for the <concept> topic type is "- topic/topic concept/concept ". * At least one trailing space character (" "). The trailing space ensures that string matches on module/name pairs can always include a leading and trailing space in order to reliably match full tokens. For example, in XPath expressions, the correct way to select elements is to use an expression with the following form: *[contains(@class, ' topic/p ')] ----- The entire "Specialization-aware processing" is non-normative and talks about potentially implementation-dependent processing. This represents a new addition to the DITA specification and as such it does not belong in the DITA specification or at least not in the DITA 1.2 specification without a proposal and a lot more discussion. It might be better to put this information into a non-normative "best practices" document and even then it will require a good deal of work. ----- The discussion (preceding the examples) in "Foreign generalization" is too prescriptive for a standard. It gets right down to describing specific processing and even the file name to use. This needs to be rewritten to describe intent, not a detailed implementation of that intent. I'm not sure how "Processing foreign content" fits in to this issue. That topic is more draft comments than content, so I suggest these two topics be considered together and rewritten. ----- In the note in "Concrete document types", we say: ...new public identifier or absolute URI... and ...public ID or absolute URI you define, e.g., "urn:public:example.dom/dita/doctypes/map". In fact, the XSDs use URNs for which the modifier "absolute" is not exactly appropriate. We should delete the word "absolute" in both cases. Also, the example URN is inappropriate and should more likely be something like: urn:example.com:dita:doctypes:map ----- In "Modularization and integration of design", we say: The separation of markup into modules, in accord with the XHTML modularization initiative, (http://www.w3.org/TR/xhtml-modularization/ ), makes it easy to extend the hierarchy.... Modularity was not invented by the XHTML modularization initiative, it's not clear what it means to be "in accord" with that initiative, and this gratuitous phrase adds nothing to--and does not belong in--the DITA 1.2 spec. We should delete: , in accord with the XHTML modularization initiative, (http://www.w3.org/TR/xhtml-modularization/ ), -----
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]