- From: Daniel Barclay <daniel@fgm.com>
- Date: Thu, 19 Aug 2004 13:08:02 -0400
- To: public-qt-comments@w3.org
Regarding the document currently at
http://www.w3.org/TR/xslt-xquery-serialization/ :
Editorial comments:
Section 1 says:
In this specification the words must, must not, should, should not,
may, required, and recommended are to be interpreted as described in
[RFC2119].
Those logically quoted words should be quoted or italicized (or
otherwise distinguished).
In section 2, the numbered list (1 through 6) doesn't follow a colon
(ending a partial sentence grammatically introducing the list).
Perhaps it should be preceded by:
The steps are:
Section 2 also says:
3. Replace all adjacent strings in the sequence, with a single string
equal to the values of the strings concatenated, each separated by
a single space.
The first comma seems to be extraneous.
It also says:
The tree rooted in the document node ...
Shouldn't that be:
The tree rooted at ...
Section 4 says:
... replacing < by <
That should be
... replacing < with <
("By" fits only when the verb in is the passive voice, as in "A is
replaced by B" (meaning B replaces A (_with_ itself)). Given the
verb form (as a noun), "with" must be used.)
Relatedly, section 9 says:
... allow a specific character ... to be substituted by a ... string...
"Substituted by" is both ungrammatical and illogical (the wrong word
or direction).
That should say:
... allow a specific character ... to be replaced by a ... string...
or:
... allow a specific character ... to be replaced with a ... string...
or, altenatively:
... allow a ... string to be substituted for a specific character ...
(Note that section 9 also says:
The string that is substituted for a character ...
which is correct.)
Section 4 also says:
1. Markup generation produces ...
2. Character expansion is ...
3. Unicode Normalization, if ...
4. Encoding, as controlled by ...
That is, the structure isn't parallel. The last two items don't being
with complete sentences as the first two do.
Section 5 says:
... a trivial XML document wrapper like this
before an example. That is, there should be a colon after the word
"this."
In multiple places, character sequences are not quoted. It would make
things less ambiguous if they were quoted (or otherwise distinguished),
especially since some of them contain characters that could be taken to
be English punctuation, and the adjacent punctuation could be taken to
be part of the character sequence.
For example, section 5 says:
Specifically, CR, NEL and LINE SEPARATOR characters in text nodes must
be output respectively as 
, …, and 
, or their
equivalents...
It would help if the semicolons were distinguished from the commas.
(Of course, standard English punctuation rules unfortunately put commas
and periods inside the quotes with the quoted words (e.g., my above
reference to the word "this" without a colon).
Perhaps character strings (as opposed to words) should be quoted with
modified quoting (putting only quoted characters between the quotes,
and keeping adjacent punctuation characters outside). Even though
that's not quite standard English, it's fairly common in computer-
related English.)
Note that some places do quote character sequences, for example:
For example, an attribute with the value "x" followed by "y"
separated by a newline will result in the output "x
y" ...
[Later: It seems that some occurrences _are_ distinguished, by being
in a different font. It's not clear whether that is the best solution,
but at a minimum all occurrences should be distinguished at least that
much.]
Section 6 says:
... like the following in the default namespace.
That period should probably be a colon (an indented example follows).
Section 7.4 says:
When outputting a sequence of whitespace characters in the instance
of the data model, within an element where whitespace is treated
normally, (but not in elements such as pre and textarea) the html
output method may represent ...
The parenthesized expression should occur _before_ the (second) comma.
Section 9 says:
... is output "as is", and ...
This that is a regular English quoting of words (as opposed to computer
strings), normal English punctuation rules should be used (the comma
should be inside the quotes).
(Semi-)Technical Comment:
Section 5.7 says:
In XML 1.0, namespace undeclaration is not possible.
Is that really XML 1.0 or is that XML Namespaces 1.0?
Daniel
Received on Thursday, 19 August 2004 17:08:38 UTC