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 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.  



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 
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. 


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

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:

all the learning ones


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"
    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
Explicit attribute values cascade from map to the map element of the sub
Presumably metadata follows the same rules.  Metadata would override
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
should override the corresponding navtitle, etc.  No need to single out
to behave differently.

Regarding "Shared metadata elements, and the lockmeta attribute":
The locktitle attribute works differently. The locktitle deals with
element and attribute, which is an aberration from the norm of lockmeta.
locktitle attribute would still apply separately to the navtitle


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
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.
when we say 'add' does this mean add as new, replace what may be on the
override some values that are not specified on topics, or override
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


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

   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...


 ...public ID or absolute URI you define, e.g.,

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: 



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]