dita — archive

Some comments on the spec

From: Paul Grosso
To: [email protected]
Date: Wed, 03 Nov 2004 18:23:00 -0000

MHonArc v2.5.0b2 -->

dita message

Subject: Some comments on the spec

From: "Paul Grosso" <[email protected]>
To: <[email protected]>
Date: Wed, 3 Nov 2004 13:18:01 -0500

With apologies that my comments mix typos with more
substantial issues, here is what I have with my 
latest review.

paul

######################################################

Chapter 2. An introduction to DITA
==================================

Definitions and background concepts/terminology
------------------------------------------------

In the definitions of {topic,map,domain} type module, 
we say:
  "A type module that collects...."
Collects?  I don't know what other word to suggest,
but "collects" doesn't quite resonate for me.

Under Declaration terminology, we use the phrase 
"syntactic scheme" as in:
  "The representation within a syntactic scheme 
  (DTD, XML Schema, Relax NG)..."
I'm not sure everyone would agree that DTDs/schemas 
are solely syntactic.  How about "schema technology" 
(note lowercase "s" which, along with the parenthetical 
phrase following the first occurrence, should make 
clear what we mean).

Regarding Document type declaration shell, we 
define this term, but then twice within this para
and the next use the term "document type shell" 
which we don't define.

Regarding the draft comment:
  should we mention here that when we omit instance
  we still are typically talking about instances? 
  eg "maps assemble topics" is equivalent to saying 
  "map instances assemble topic instances". should 
  we even include instance? it's accurate but I'm 
  not sure that it's ever necessary.
I think we should leave the "instance" defns and add
a note as suggested that when we omit instance we 
still are typically talking about instances.  It's 
useful to have the more specific terminology at times
even if we often take shortcuts.

Chapter 3. DITA markup
======================

DITA markup/Common attributes/Identity attributes
-------------------------------------------------
Near the top, we need to explain that DITA ids are 
not of the same type as DTD IDs or XML Schema xsd:id.
Otherwise, someone reading this section is going to 
suffer severe headaches thinking that the values you
show aren't "valid ids."

DITA markup/Common attributes/Content reference attribute
---------------------------------------------------------
Likewise, we need a note here saying this isn't SGML's conref.

Regarding:
  Replacement of the placeholder occurs prior to 
  presentation or other operations on the full topic.
  In this respect, the DITA conref attribute resembles
  the XLink behaviors produced by the combination of an
  embed value for the xlink:show attribute and of an
  onLoad value for the xlink:actuate attribute.
This isn't correct.  XLink's (much misunderstood) "embed"
semantic implies the target is formatted first in its
native location and a presentation is then embedded in 
the presented result.  (Actually, "embed" is mostly for 
graphics, and the XLink spec doesn't define what it means 
to embed XML.)  In the case of DITA's conref, the target 
is pulled into the referencing location first and then 
formatted in it new context.  I suggest something like:
  Replacement of the placeholder occurs after parsing
  of the document but prior to any styling or other
  transformational or presentational operations on the
  full topic.
(No need to mention XLink.)

Regarding:
  a processor resolving a conref should make sure that ... all
  elements within the referenced content fragment are valid
  within the referencing element.
But in an earlier paragraph, we say: 
  the conref is guaranteed to remain valid. That is,
  editing in the source and destination documents won't
  invalidate the content reference
so how can an element within the referenced fragment 
be invalid in the referencing element?  And later we 
say a conref resolving processor should tolerate 
specializations. I agree with the draft comment that 
says this sounds wrong, but I don't have specific
suggested wording improvements.

Regarding the draft comment about xinclude, fwiw, 
xinclude does no validation, so it doesn't provide 
any such checking. 

DITA topics/Information Types/Tasks
-----------------------------------
The first sentence under "Why Tasks" isn't quite a 
sentence. (The way I parse it, it's missing a verb.)

The next sentence with "How do I"?" has an extraneous 
double quote.

DITA topics/Information Types/Reference
---------------------------------------
Second sentence under "Why Reference" starts "A reference 
topics..." which has a subject/verb plurality agreement 
problem.

DITA maps
---------
The last para before "Why DITA maps" seems to have 
three sentences but only one period.

DITA maps/Common DITA map attributes and metadata
-------------------------------------------------
Regarding navtitle, there is a draft comment about 
changing its name to prototitle.  Are we talking about 
doing that in DITA 1.0 or in a future version?

DITA maps/DITA map structure
----------------------------
Third para includes "...they are equivalent toe topicref 
elements..." and the "toe" should be "to".

Fourth para uses the term "relationship table" a couple 
times but there is one occurrence of "relation table".

Chapter 4. DITA specialization
==============================

Specialization, integration, customization
------------------------------------------
A draft comment asks "do we need this here?"  I like 
this sentence, but it doesn't seem to belong here;
it would seem to be useful to have it earlier in the 
document.  Looking back to chapter 2, I notice the 
list of concepts (after the terminology section) are:
  Topics
  Maps
  Information types
  Domains
  Specialization
  Customization
  Integration
It occurs to me that the first four are "things" whereas
the last three are "processes" (sort of).  Perhaps we 
should make the content of chapter 2/Definitions and 
background concepts more like:
  Terminology
  Topics
  Maps
  Information types
  Domains
  Specialization, integration, customization
      Specialization
      Customization
      Integration
so that this misplaced topic in question can then have 
what are currently the last three topics of "Definitions 
and background concepts" as sub-topics. 

Specialization in content/The class attribute/Class attribute syntax
--------------------------------------------------------
Third sentence of the second paragraph says:
  After the starting token are one more blank-delimited
  values, ending with a blank. 
Why ending with a blank?  What happens if this trailing 
blank is missing?  Is a DITA application supposed to flag 
this as an error, just return incorrect results, or recover
by assuming a final blank?  

I understand that having the trailing blank makes the XSLT
easier to write, but like the "alphabetical order" issue
below, this seems like a case where we are adding a requirement
on the user just to make things easier for the computer (or
programmer), and that's the wrong way around in my opinion.

Fourth sentence of the second paragraph says:
  Each value has two parts: the first part identifies
  a module package, for example a topic type or domain
  package name, and the second part (after a period)
  identifies an element type. 
Shouldn't that be "after a solidus"?

Specialization in content/The domains attribute
------------------------------------------------
Just before the draft comment we suggest alphabetical 
order, but then the example doesn't seem to do that 
(or else I can't follow what's meant here).  

Requiring things to be in alphabetical order seems 
wrong to me.  Computers should do things for people 
like sorting and handling comparisons; people shouldn't
have to do such things for computers.

Specialization in content/Generalization
-----------------------------------------
As a general comment, we never defined "generalization" 
in the terminology nor discussed it as a concept in 
chapter 2, and we don't really mention the term until 
page 30.  Personally, I still don't quite understand 
either "why generalization" or quite what it is, so 
assuming I'm not the only one in that boat, I think 
we should add a section in chapter 2's concepts on 
generalization.

Fourth para, second sentence starts:
  The generalizer can specify multiple targets in when pass: 
Probably "when" should be "one".

##################