Bug 16350 - Fix occurances of RFC2119 terms in notes
Fix occurances of RFC2119 terms in notes
Status: RESOLVED FIXED
Product: WebAppsWG
Classification: Unclassified
Component: DOM3 Events
unspecified
PC Windows NT
: P2 normal
: ---
Assigned To: Travis Leithead [MSFT]
public-webapps-bugzilla
http://lists.w3.org/Archives/Public/p...
: LC, needsReview
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2012-03-13 23:03 UTC by Travis Leithead [MSFT]
Modified: 2012-03-13 23:09 UTC (History)
5 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Travis Leithead [MSFT] 2012-03-13 23:03:17 UTC
PORTING last call comments from email to bugs for tracking purposes
[see http://lists.w3.org/Archives/Public/public-webapps/2011OctDec/0226.html]
------------------------------------------------------------------

On Thu, 13 Oct 2011 03:19:26 +0200, Jacob Rossi  
<Jacob.Rossi@microsoft.com> wrote:

>>> Note: For programming languages which do not allow optional method
>
>>> parameters, such as Java, the implementation may provide two
>
>>> EventTarget.addEventListener methods, one with 2 parameters, and one
>
>>> with 3 parameters.
>
>>
>
>> Is this a note or is it normative? You can't have both.
>
> This is a note that suggests a workaround for implementations in  
> languages that don't support optional arguments. It's not normative. An  
> implementation may do this, or it may not-up to the implementer (since  
> optional useCapture isn't required).

'may' is an RFC2119 term. Don't use it in notes.

>
>>> If a listener was registered twice, once for the capture and target
>
>>> phases and once for the target and bubbling phases, each must be
>
>>> removed separately.
>
>>
>
>> It's not clear if this is a UA requirement.
>
>
>
> This is intended for authors:
>
>
>
> target.addEventListener("foo",bar,false);
>
> target.addEventListener("foo",bar,true);
>
> target.removeEventListener("foo",bar,false);
>
>
>
> This only removes the first of the two listeners.

It doesn't look like a note to me. It looks like a conformance requirement  
(since it contains the word 'must'). If it's targeting authors, it means  
they're being non-conforming if they don't remove their event listeners  
any time they register a listener twice (one capture and one bubbling). If  
you intend it to be a note, clearly mark it as a note and don't use  
RFC2119 terms.

>
>
>>> The content authors should also remove their EventListener from its
>
>>> EventTarget after they have completed using the listener.
>
>>
>
>> I wonder why this is a "should".
>
>
>
> It's a coding "best practices" suggestion towards authors.

'should' is not a suggestion, it's a conformance requirement.

...

It seems to me you need to be more careful in your usage of RFC2119  
keywords. Also see http://ln.hixie.ch/?start=1140242962&count=1

-- 
Simon Pieters
Opera Software
Comment 1 Travis Leithead [MSFT] 2012-03-13 23:09:44 UTC
Adding a few folks who participated on the thread.

------
I did a run through the entire spec to try and make all the notes RFC2119-clean. The latest revision of the spec has these changes. Please review to see if this satisfies this bug.

(Note, there may be other occurances of RFC2119 terms used _outside_ of notes, where the intent of the spec author may have been to specify a note. If you come across these, please report them as new bugs!