W3C home > Mailing lists > Public > public-qt-comments@w3.org > July 2005

[Bug 1379] [XQuery] some editorial comments on A.1.1 grammar-note: comments

From: <bugzilla@wiggum.w3.org>
Date: Sat, 09 Jul 2005 04:48:12 +0000
To: public-qt-comments@w3.org
Cc:
Message-Id: <E1Dr7G8-0003ln-LU@wiggum.w3.org>

http://www.w3.org/Bugs/Public/show_bug.cgi?id=1379





------- Additional Comments From scott_boag@us.ibm.com  2005-07-09 04:48 -------
(In reply to comment #0)
> A.1.1 grammar-note: comments
> 
> "Expression comments"
>     Change to "Comments".

Done.  (note the original wording was there to distinguish from XML comments,
but I'm OK with loosing it.)

> 
> "are allowed inside expressions"
>     And elsewhere.

Just lost "inside expression, so... "Comments are allowed everywhere that
<termref def="IgnorableWhitespace">ignorable whitespace</termref> is allowed.".  

> 
> "Note that expression comments"
>     Change "expression comments" to "comments".

Done.

> 
> "are not allowed in constructor content"
>     Insert "direct" before "constructor" ?

Done.

> 
>     Actually, they *are* allowed in constructor content, given a suitable
>     definition of "in":
>         <a> { "foo" (:comment:) } </a>

Modified to "Note that  comments are not allowed in direct constructor content,
though they are allowed in  nested 	<nt def="EnclosedExpr">EnclosedExprs</nt>."
 Still clunky, but good enough, i think.

> 
> "Comments can nest within each other,"
>     "within each other" suggests 'A within B, and B within A.' Change to just
>     "Comments can nest" or "A comment can contain nested comments".

Done.

> 
> "as long as all "(:" and ":)" patterns are balanced, no matter where they occur
> within the outer comment."
>     Well, that's basically what it means for comments to nest.

Yes, but I'm trying to emphasize that commenting out the string "(:", for
instance, (: "(:" :), results in a syntax error.

> 
>     Change sentence to:
>         A comment can contain nested comments. This means that occurrences of
>         "(:" and ":)" in the body of the comment must be balanced.

I slightly prefer my wording.

> 
> "will parse correctly"
>     Leave the parser out of it.  Change to "is syntactically legal".

Done.

> 
> "ignoring the comment"
>     A dangling participle, I think.

Dangling participle removed.

> 
> "<eg (: an example:)> $i//title </eg>"
>     Maybe you intended to put $i//title within braces.

Uh, yes.

> 
> "but characters inside the element is element content"
>     Change "is" to "are".
> 
>     Maybe change phrase to "but the characters that look like a comment are in
>     fact literal element content".

Done.

> 
> "and not an expression comment"
>     Change "expression comment" to "comment".

Superseded by previous.

> 
> "See Comments, Pragmas and Extensions for further information and examples."
>     The name of that section is now just "Comments".

Changed to <specref ref="CommentsPragmasExtensions"/>

> 
>     It's silly to split information and examples between here and A.2.3. Please
>     merge them.

Grammar note changed to:

<gitem id="parse-note-comments"><label>comments</label><def><p>Comments are
allowed everywhere that <termref def="IgnorableWhitespace">ignorable
whitespace</termref> is allowed, and so does not explicity appear on the
right-hand side of the grammar (except in it's own production).</p><p>Comments
are allowed everywhere that <termref def="IgnorableWhitespace">ignorable
whitespace</termref> is allowed.  <phrase role="xquery">Note that  comments are
not allowed in direct constructor content, though they are allowed in  nested 
<nt def="EnclosedExpr">EnclosedExprs</nt>.</phrase>  </p><p>See <specref
ref="CommentsPragmasExtensions"/> for further information and
examples.</p></def></gitem>

The rest has been merged to the comments section.
Received on Saturday, 9 July 2005 04:48:15 UTC

This archive was generated by hypermail 2.3.1 : Wednesday, 7 January 2015 15:45:25 UTC