[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Some comments on the spec
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".
##################
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]