[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.
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
<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"
instead
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
behavior.
Explicit attribute values cascade from map to the map element of the sub
map.
Presumably metadata follows the same rules. Metadata would override
metadata
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
navtitle
should override the corresponding navtitle, etc. No need to single out
one
to behave differently.
Regarding "Shared metadata elements, and the lockmeta attribute":
The locktitle attribute works differently. The locktitle deals with
navtitle,
element and attribute, which is an aberration from the norm of lockmeta.
The
locktitle attribute would still apply separately to the navtitle
metadata.
-----
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
audience?
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.
So
when we say 'add' does this mean add as new, replace what may be on the
topic,
override some values that are not specified on topics, or override
everything
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
processing".
-----
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
specialized.
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...
and
...public ID or absolute URI you define, e.g.,
"urn:public:example.dom/dita/doctypes/map".
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:
urn:example.com:dita:doctypes:map
-----
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]