W3C home > Mailing lists > Public > public-html-admin@w3.org > September 2013

[Bug 23246] New: Conflicting documentation - comments within normal elements - misspelling attribute names

From: <bugzilla@jessica.w3.org>
Date: Sun, 15 Sep 2013 01:40:11 +0000
To: public-html-admin@w3.org
Message-ID: <bug-23246-2495@http.www.w3.org/Bugs/Public/>
https://www.w3.org/Bugs/Public/show_bug.cgi?id=23246

            Bug ID: 23246
           Summary: Conflicting documentation - comments within normal
                    elements - misspelling attribute names
           Product: HTML WG
           Version: unspecified
          Hardware: PC
                OS: Windows NT
            Status: NEW
          Severity: normal
          Priority: P2
         Component: HTML5 spec
          Assignee: dave.null@w3.org
          Reporter: lawrence.emke@gmail.com
        QA Contact: public-html-bugzilla@w3.org
                CC: mike@w3.org, public-html-admin@w3.org,
                    public-html-wg-issue-tracking@w3.org

in URL: http://www.w3.org/html/wg/drafts/html/master/syntax.html#elements-0
defining the contents of normal elements is says:

"Normal elements can have text, character references, other elements, and
comments, but the text must not contain the character "<" (U+003C) or an
ambiguous ampersand. Some normal elements also have yet more restrictions on
what content they are allowed to hold, beyond the restrictions imposed by the
content model and those described in this paragraph. Those restrictions are
described below."

This makes reference that "comments" are permitted within elements. 
However, it says that the text must not contain the character "<".

in URL:
http://www.w3.org/html/wg/drafts/html/master/syntax.html#syntax-comments
it states:

Comments must start with the four character sequence U+003C LESS-THAN SIGN,
U+0021 EXCLAMATION MARK, U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS (<!--).
Following this sequence, the comment may have text, with the additional
restriction that the text must not start with a single ">" (U+003E) character,
nor start with a U+002D HYPHEN-MINUS character (-) followed by a ">" (U+003E)
character, nor contain two consecutive U+002D HYPHEN-MINUS characters (--), nor
end with a U+002D HYPHEN-MINUS character (-). Finally, the comment must be
ended by the three character sequence U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS,
U+003E GREATER-THAN SIGN (-->).

This statement indicates that comments must start with "<!--" which 
means that elements cannot have comments! since the "<" is not permitted.

I know the QND solution will be to modify the documentation to eliminate
comments from the allowed content, but I don't think the original language
designers had that intention.  

The real problem is:
To get around the lack of comments within an element, programmers misspell
attribute names to hide the attribute values during debugging.
This leads to a potential error situation. If I create a custom element that 
has attribute ref= and I modify it to xref= for debug purposes, but
forget to remove it, since it works correctly without the ref= attribute, but
then someone changes the custom elements definition to include a new attribute
xref=. Now I have introduced a change in a production software without
having to change the actual code. This is not good!! 

The problem with the "misspelling attribute name" solution is that it uses one
thing (and attribute name) for two purposes. The allowing of undefined
attributes was meant for compatibility in changing definitions. It is now being
used as a way to implement a comment within an element.

-- 
You are receiving this mail because:
You are on the CC list for the bug.
Received on Sunday, 15 September 2013 01:40:13 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 20:37:34 UTC