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

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

           Summary: [XQuery] some editorial comments on A.1.1 grammar-note:
                    comments
           Product: XPath / XQuery / XSLT
           Version: Last Call drafts
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: normal
          Priority: P2
         Component: XQuery
        AssignedTo: chamberl@almaden.ibm.com
        ReportedBy: jmdyck@ibiblio.org
         QAContact: public-qt-comments@w3.org


A.1.1 grammar-note: comments

"Expression comments"
    Change to "Comments".

"are allowed inside expressions"
    And elsewhere.

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

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

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

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

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

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

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

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

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

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

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

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

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

Received on Wednesday, 11 May 2005 07:32:31 UTC