xslt-xquery-serialization editorial comments (and one semi-technical)

Daniel,

    In [1], you submitted the following comments on the July 23 draft of 
Serialization.[2]  Thank you for the thorough review.  I have accepted all 
of your comments, except as noted below.

    I would be grateful if you could check the next draft of 
serialization, when we publish it, to verify that the changes I've applied 
are satisfactory.

> 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.

The wording of this step has changed, so the extraneous comma is no longer 
there.

> It also says:
> 
>    The tree rooted in the document node ...
> 
> Shouldn't that be:
> 
>    The tree rooted at ...
> 
> Section 4 says:
> 
>     ... replacing < by &lt;
> 
> That should be
> 
>     ... replacing < with &lt;
> 
> ("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.

Unicode normalization is now a substep of character expansion, but I've 
made the structure of what was 4 mirror those of 1 and 2.

> 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 &#xD;, &#x85;, and &#x2028;, 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&#xA;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?

Thanks,

Henry
[1] 
http://lists.w3.org/Archives/Public/public-qt-comments/2004Aug/0066.html
[2] http://www.w3.org/TR/2004/WD-xslt-xquery-serialization-20040723/
------------------------------------------------------------------
Henry Zongaro      Xalan development
IBM SWS Toronto Lab   T/L 969-6044;  Phone +1 905 413-6044
mailto:zongaro@ca.ibm.com

Received on Monday, 18 October 2004 15:22:30 UTC