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.
paul
================
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
such as MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, MAY NOT, REQUIRED,
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.
See
http://www.oasis-open.org/apps/org/workgroup/dita/email/archives/200803/
msg00028.html
-----
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
exhaustive.
-----
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:
subjectScheme.dtd
classifyMap.dtd
all the learning ones
machineryTask.dtd
-----
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