[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Some comments on the latest DITA draft
In general, I'm quite happy with the latest draft. Many thanks to Michael and all the others that have worked on this. I reread the entire draft, and I have a few minor comments. Under Naming conventions and file extensions -------------------------------------------- For schema structural type files we have typename_mod.xsd et al., whereas for schema domain type files, we have typename-domain.xsd and typename-domain_group.xsd and for override files, we have customization-purpose.* Having an underscores in some cases and hyphens in others seems destined to cause confusion, especially comparing just typename_mod.xsd and typename-domain.xsd. Under Modularization in Schemas, we talk about "a name consisting of the root structural element name and_domains.xsd." First, note the missing space before the _; second, notice it's an underscore, not a hyphen; third, notice we've got "domains" (plural). I think we've managed to confuse ourselves with our naming conventions. Under Common Attributes ----------------------- Although "id" may at one point have meant "identity" or "identification", calling it the "DITA identity attribute" instead of the "DITA id attribute" is more confusing and didactic than helpful in my opinion. I'd suggest changing "Identity" (and "identity") in the title and first sentence (which seem to be the only places we do this) just to "Id" (and "id"). Also, I think we should include a mention here that the id attribute isn't typed as an XML id or schema xsd:id just in case someone reading this starts to wonder. (If this was mentioned in this section, I didn't see it.) Under Content Reference attribute --------------------------------- The last sentence of the sixth paragraph reads: An editor adopting this approach would need to prevent editing of the snapshot. I'd like us to delete this sentence. It doesn't have anything to do with the definition of the DITA standard per se, and it is too restrictive. Some user processes may allow for "post-processing tweaks" that include editing the snapshot. Or perhaps the only editing of the snapshot is to affect final pass formatting, not content. Or perhaps an editor is smart enough to know how to allow editing of the snapshot that then pushes the changes back into the original topics, perhaps at user option. Regardless, we shouldn't be putting requirements such as this on tools here. xml:lang -------- I'm not sure if this is too picky, but we say "the language applies to the contained content...." In fact, xml:lang also applies to attribute values on all elements within its scope. One could also refer to the "language identification" section of the XML spec: http://www.w3.org/TR/REC-xml/#sec-lang-tag Under Modularization in Schemas ------------------------------- There are many more occurrences of _xxx.xsd where the space preceding the _ is lost; also, there are several instances of things like topic_domains.xsd when our naming conventions said it would be topic-domain.xsd. paul
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]