<style>
td {
vertical-align: top;
}
td, th, table {
border: 1pt solid black;
}
tr.new {
background-color: #EAEAEA;
}
</style>
<table cellspacing=0>
<tr>
<th>MB
<th>Clause no.
<th>Paragraph
<th>Type of comment
<th>Comment
<th>Proposed change
<th>Sec obs
<tr>
<td>NO
<td>
<td>
<td>ge
<td>Throughout the document some clauses, like for example 3.5, have
text before the first numbered subclause. This is not allowed under
the ISO style, and in fact also disallowed in is.rnc.
<td>Reorganize the document to conform to ISO style.
<td>
<tr>
<td>NO
<td>
<td>
<td>ge
<td>Throughout the document the text "an error is flagged" recurs.
This is awkward, because it raises the question of what it means to
flag an error, and this is nowhere answered. It would be better to
use the more common phrasing of saying something "is an error", and
then to have a separate clause stating what to do in the case of
errors.
<td>Rephrase throughout, and add an extra clause.
<td>
<tr>
<td>NO
<td>Introduction
<td>2
<td>ed
<td>Text refers to "the TMDM". Normal usage is "TMDM".
<td>Remove "the".
<td>
<tr>
<td>NO
<td>2
<td>
<td>ed
<td>References to ISO 13250-2 and -3 are not in the ISO-mandated
style.
<td>Correct the references.
<td>
<tr>
<td>NO
<td>3.1
<td>2
<td>ed
<td>The term "CTM documents" is unnecessary, and potentially
misleading, since CTM does not need to appear in "documents".
<td>Rephrase to avoid the term "CTM documents".
<td>
<tr>
<td>NO
<td>3.2
<td>1
<td>ed
<td>This paragraph is a verbatim copy of a similar paragraph in
the XTM 2.0 specification. It does not really add anything to the
specification.
<td>Remove paragraph.
<td>
<tr>
<td>NO
<td>3.2
<td>3
<td>te
<td>Text says that the byte stream is converted to a character
stream, but does not say how.
<td>Define character conversion process.
<td>
<tr>
<td>NO
<td>3.2
<td>6
<td>ed
<td>The paragraph "Each CTM processor ..." is awkwardly formulated.
<td>Replace with "The following QName prefix is predefined, and
shall be recognized by all CTM processors:"
<td>
<tr>
<td>NO
<td>3.2
<td>6
<td>te
<td>Is it necessary to have a predefined prefix? Users can define
this prefix if they need it.
<td>Remove paragraph.
<td>
<tr>
<td>NO
<td>3.3.1
<td>2
<td>ed
<td>Text says "Space (#x20) characters are allowed everywhere".
This seems to imply that only ASCII character 32, space, is
allowed, and that the other three whitespace characters are not
allowed.
<td>Alter text to say "Whitespace character are allowed everywhere".
<td>
<tr>
<td>NO
<td>3.3.2
<td>2
<td>te
<td>Production [2] uses "#xA" as line separator, but different line
separators are used on different platforms. This needs to be
specified more carefully.
<td>Alter text to account for different line separators.
<td>
<tr>
<td>NO
<td>3.3.2
<td>3
<td>ed
<td>Text says "This part of ... allows nesting". This is clumsily
phrased.
<td>Alter text to say ", and may be nested."
<td>
<tr>
<td>NO
<td>3.3.3
<td>[5]
<td>te
<td>Production [5] refers to RFC 3987 for part of the production.
This makes it harder for implementors to know exactly what is
allowed and what is not. There is every chance that implementations
will differ in what they accept here, harming interoperability.
<td>Define production explicitly.
<td>
<tr>
<td>NO
<td>3.3.3
<td>
<td>ed
<td>Second para of first note says "An IRI which is not ...". This
is normative, and so does not belong in a note. Further, it should
really be specified in the grammar.
<td>Remove para and incorporate this in the grammar.
<td>
<tr>
<td>NO
<td>3.3.4
<td>1
<td>ed
<td>Text says "They [QNames] are declared as follows:", which is
confusing, as the reader is likely to think this means that the
following will show how QNames are declared in CTM. In fact, the
productions show the syntax for QNames. This awkward phrasing recurs
for many, many grammar fragments throughout the document.
<td>Rephrase paragraph to "QNames are used to abbreviate IRIs. The
syntax of QNames is as follows:" Also rephrase other corresponding
sentences in the spec.
<td>
<tr>
<td>NO
<td>3.3.6
<td>
<td>ed
<td>The note is clearly meant to be normative, and so should not be
a note.
<td>Make the note a normal paragraph.
<td>
<tr>
<td>NO
<td>3.3.7
<td>
<td>ed
<td>The note is clearly meant to be normative, and so should not be
a note. The semicolon should be made optional in the EBNF instead.
<td>Remove the note and adapt the EBNF.
<td>
<tr class=new>
<td>NO
<td>3.3.7
<td>[18]
<td>te
<td>One of the arguments for adding the embedded topic syntax was
that this would be very useful for TMCL, and might even remove the
need for templates. The new TMCL draft does not use embedded topics
at all, and it is not clear that they would be very useful. At the
same time, they substantially complicate the implementation of CTM.
There seems to be no compelling reason to keep embedded topics.
<td>Remove embedded topics.
<td>
<tr>
<td>NO
<td>3.3.8
<td>
<td>ed
<td>The clause describes the creation of locators from the
wildcards, but does not say where these locators. Nor is there any
mention of any topic being created.
<td>Make it clear that a topic is created, and where the locators go.
<td>
<tr>
<td>NO
<td>3.3.9
<td>[22]
<td>te
<td>The production explicitly states that there may be whitespace
(WS) after the '@' character, but does not specify that whitespace
is allowed around the comma. This is inconsistent, and seems
unnecessary when 3.3.1 states that whitespace is allowed everywhere.
<td>Remove the WS reference from the production.
<td>
<tr>
<td>NO
<td>3.3.9
<td>3
<td>ed
<td>The text refers to "the [scope] property of the Topic Maps
construct", which is rather awkward.
<td>Rephrase to "the [scope] property of the statement".
<td>
<tr>
<td>NO
<td>3.3.10
<td>1
<td>ed
<td>The text refers to "Topic Maps construct", which is a rather
awkward term.
<td>Rephrase to "statement".
<td>
<tr>
<td>NO
<td>3.3.10
<td>[23]
<td>te
<td>Same as above.
<td>Remove the WS reference from the production.
<td>
<tr>
<td>NO
<td>3.3.11
<td>1
<td>ed
<td>Text says "...used to assign a type to <em>a</em> Topic Maps
item in which it occurs...", which is grammatically incorrect.
<td>Replace "a" by "the".
<td>
<tr>
<td>NO
<td>3.3.11
<td>2
<td>ed
<td>Text says "...Topic Maps item...", which is inconsistent with
the terminology used in TMDM.
<td>Rephrase to "information item".
<td>
<tr>
<td>NO
<td>3.4
<td>[31]
<td>ed
<td>The production just references the XML Schema spec. It would be
better to incorporate the full production in the grammar. Similarly
for [32].
<td>Specify the grammar explicitly.
<td>
<tr>
<td>NO
<td>3.4
<td>NOTE
<td>ed
<td>The note is clearly meant to be normative, and so should not be
a note.
<td>Make the note a normal paragraph.
<td>
<tr>
<td>NO
<td>3.4.1
<td>
<td>ed
<td>The interpretation of the various escape sequences is not
defined in the text, leaving implementors to guess what is meant.
<td>Define the interpretation.
<td>
<tr>
<td>NO
<td>3.5
<td>[40]
<td>te
<td>The grammar says "(directive* reifier)?" which means that it is
impossible to have a directive without a reifier. This is unlikely
to be what is actually meant.
<td>Redefine to "directive* reifier?".
<td>
<tr>
<td>NO
<td>3.5.1
<td>
<td>ed
<td>Production [41] is explained in 3.5.1, but defined in 3.5. For
context it might be better to define it in 3.5.1.
<td>Move production to 3.5.1. Alternatively, remove 3.5.1 entirely,
or merge it into the previous clause.
<td>
<tr>
<td>NO
<td>3.5
<td>
<td>te
<td>Directives, as defined here, must be terminated by a newline,
but this seems unnecessary. Whitespace is not significant elsewhere
in the grammar, so why make an exception here?
<td>Remove the restriction.
<td>
<tr>
<td>NO
<td>3.5
<td>
<td>te
<td>Directives use "#xA" as a line separator, just like production
[2], which has the same problems.
<td>Remove the restriction. Alternatively, fix as with [2].
<td>
<tr>
<td>NO
<td>3.5.2
<td>
<td>ed
<td>The text says encoding names are to be given in the form
recommended by XML 1.0. XML 1.0 references an IANA registry. We
should do the same.
<td>Reference IANA directly.
<td>
<tr>
<td>NO
<td>3.5.2
<td>
<td>te
<td>The text says the encoding directive must be on the first line,
if given. This is insufficient. There must be no whitespace before
the directive, either. The purpose of this is to allow implementors
to auto-detect the character encoding, as in
<a href="http://www.w3.org/TR/REC-xml/#sec-guessing">XML</a>.
The encoding detection/directive must also be connected with the
byte-to-character stream conversion in 3.2.
<td>Change text accordingly.
<td>
<tr>
<td>NO
<td>3.5.3
<td>4
<td>ed
<td>The text says "this part of ... recommends", which is awkward.
<td>Change to "Its usage is recommended for ...".
<td>
<tr>
<td>NO
<td>3.5.3
<td>5
<td>te
<td>The text sets out strict requirements for where the version
directive can appear in terms of line breaks using prose. Does this
need to be specified in terms of prose rather than EBNF, and does it
matter how many line breaks there are before the version directive?
The EBNF already requires this directive to be in the prolog, which
should be sufficient.
<td>Remove entire paragraph.
<td>
<tr>
<td>NO
<td>3.6
<td>NOTE
<td>ed
<td>The note is normative, and so should not be a note. However,
this requirement should be worked into the EBNF grammar instead.
<td>Remove the note.
<td>
<tr>
<td>NO
<td>3.7
<td>[45]
<td>ed
<td>In this production the parentheses around the OR group appears
to be missing.
<td>Insert parentheses.
<td>
<tr class=new>
<td>NO
<td>3.7
<td>[45]
<td>te
<td>Strictly speaking, the semicolons (";") after each statement are
not required, and in actual CTM files their appearance is
aesthetically not very pleasing. On the other hand, their presence
may make finding syntax errors easier for novices.
<td>Discuss whether to remove semicolons.
<td>
<tr>
<td>NO
<td>3.8
<td>
<td>ed
<td>Clause 3.7 covers the "topic-tail", which primarily consists of
names and occurrences, which are covered in 3.9, 3.10, and 3.11. In
between comes associations in 3.8, which cannot be part of the
topic-tail. This order is distracting for readers.
<td>Move 3.8 after 3.11.
<td>
<tr>
<td>NO
<td>3.8
<td>[51]
<td>ed
<td>A separate type production with processing rules has already
been defined in 3.3.11, and is used in 3.9 and 3.10. Why not here
also?
<td>Remove production and use type instead.
<td>
<tr>
<td>NO
<td>3.8
<td>NOTE
<td>ed
<td>The note uses "shall" indicating that it is normative, but in
reality it is just advising users not to put a "(" next to an
unbracketed IRI. This could be solved by disallowing "(" characters
in IRIs if the EBNF for IRIs is given explicitly.
<td>Disallow "(" in IRIs and remove the note. Alternatively, reword
the note so it does not seem to be normative.
<td>
<tr>
<td>NO
<td>3.12
<td>1
<td>ed
<td>The definition of what a template is is quite poor, and does not
at all refer to the uses of templates.
<td>Rewrite.
<td>
<tr>
<td>NO
<td>3.12
<td>
<td>ed
<td>The scope of template declarations is not explicitly defined,
although it is alluded to many places in the spec.
<td>Define the scope explicitly.
<td>
<tr>
<td>NO
<td>3.12
<td>[61]
<td>te
<td>Production template-body allows the prefix directive to occur
within a template body. This raises the issue of the scope of the
prefix declaration (both for the specification and in the minds of
users), and also complicates the grammar slightly. It also makes
implemenations more complex, and the value of this is disputable at
best.
<td>Change the grammar to disallow prefix directives in template
bodies.
<td>
<tr>
<td>NO
<td>3.13
<td>[64]
<td>te
<td>The need for a separate topic-template-invocation is not clear.
Why must templates invoked in a topic block be invoked with a
parameter when templates outside a template block do not need this?
<td>Remove production.
<td>
<tr>
<td>NO
<td>3.13
<td>NOTE
<td>ed
<td>The note is normative, and so should not be a note. Secondly,
instead of directly defining the scope rules for template
definitions, this note indirectly describes the effects of these
rules, which is awkward and difficult to read.
<td>Remove note.
<td>
<tr>
<td>NO
<td>3.13
<td>
<td>ed
<td>This clause does not actually define the effect of invoking a
template, nor how template variables are bound. One assumes there is
a rule for including the topic in a topic block as the first
parameter, but this is not defined anywhere.
<td>Define how template invocation works.
<td>
<tr>
<td>NO
<td>3.14.1
<td>
<td>ed
<td>The scope rules for prefix bindings is not defined.
<td>Define the scope rules.
<td>
<tr>
<td>NO
<td>3.14.1
<td>[69]
<td>ed
<td>This production defines a reference as either an IRI or a random
collection of non-WS characters. The text does not define the
interpretation of the second alternative.
<td>Explain or remove second alternative.
<td>
<tr>
<td>NO
<td>3.14.2
<td>
<td>ed
<td>The text defining the interpretation of the include directive is
much too vague and awkwardly written. There is no reference to the
processing of the iri-ref, nor to how deserialization is to be
performed, and so on. It is possible to guess the intent behind the
text, but it could be stated much more directly.
<td>Clean up and fill out the text.
<td>
<tr>
<td>NO
<td>3.14.3
<td>
<td>ed
<td>The text in this clause suffers from the same problems of
vagueness as that of 3.14.2.
<td>Clean up and fill out the text.
<td>
<tr>
<td>NO
<td>3.14.3
<td>
<td>te
<td>Are syntax identifiers case-sensitive or not? And is "CTM" or
"ctm" the syntax identifier?
<td>Tighten up the text.
<td>
<tr>
<td>NO
<td>3.14.3
<td>
<td>te
<td>The "xtm" syntax identifier is not clearly defined. Does this
mean XTM 1.0, XTM 2.0, or both? There are no references to other
specifications here, making it even more difficult to know what is
meant.
<td>Define separate identifiers for XTM 1.0 and 2.0, and reference
the specifications.
<td>
<tr>
<td>NO
<td>3.14.3
<td>
<td>te
<td>What happens if some implementors start using, say, "LTM" to
mean Ontopia's syntax, and then later ISO updates CTM, defining
"LTM" to mean something else? Should ISO reserve parts of the
namespace for itself? Or should syntax identifiers be PSIs?
<td>Discuss.
<td>
</table>