OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[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

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 

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.

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:

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


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]