Review: 3.4.6. The irrelevant attribute

Hello!

I have reviewed 3.4.6. "the irrelevant attribute" section in the HTML 5  
specification [1] and I found several errors.


1. "In the following skeletal example, the attribute is used to hide the  
*a* Web game until the user logs in:"

The emphasized *a* needs to be removed.

2. The first example contains an error. The section with ID=game needs to  
have the irrelevant attribute set, because the script sets the  
section.irrelevant = false - however, the section was never irrelevant.

3. The second example does not seem to be properly separated from the  
first because the paragraph which immediately follows the first example is  
expected to be an explanation of the first example. However, when one  
reads the paragraph and looks at the code of the second example, it  
becomes clear that the paragraph actually referrs to the second example.  
This is confusing.

4. "In the following example, an image acts as a surrogate for *an* video."

"An" can only be used when the word that follows starts with a vowel. When  
the following word starts with a consonant, you have to use "a". Thus, I  
suggest changing the phrase accordingly.

5. I would suggest improvements for the description of the second example.  
Currently, the description seems ... "dense" and complicated. Here's my  
try to improve the description:

"Example 2:

[... the code ...]

In this case we have an image acting as a surrogate for a video.

When the image is clicked, the script tries to load the video (and  
disables the playback button):
a) If the load succeeds enough that a frame of data has been downloaded,  
the video element hides the surrogate image and shows the video instead,  
along with its controls, and turns on autoplay (so that the video will  
commence playback as soon as enough of it is loaded).
b) If the load fails for any reason, the video and the surrogate frame are  
both hidden (by hiding the paragraph element containing them both), and  
the following paragraph is shown instead, with its unhelpful error message  
and potentially helpful link to download the video directly.

In legacy user agents, the surrogate image would show (though clicking it  
would have no effect) and the link to the video would be present (allowing  
the video to be viewed in another application)."

As you can see, the description is just reorganized, such that it's easier  
to follow.

This reorganization also makes a better separation between the two  
examples.

6. The description of the second example currently starts like this "in  
the following example, an image acts as a surrogate for an video. When the  
image is clicked, *it* tries to load the video (and disables the playback  
button)."

Setting aside the mistake with "an video". I am now focusing on the "it  
tries to load the video". What's "it" in this context? The image tries to  
load the video? The UA? The user? I think an appropriate replacement for  
"it" in this context is "the script tries to load the video".

7. The explanation of the second example contains quite many parentheses.  
As a matter of style, I do recommend using fewer parentheses by rephrasing  
the explanation a bit. Here's my take on this:

"Example 2:

[... the code ...]

In this case we have an image acting as a surrogate for a video.

When the image is clicked, the script tries to load the video and disables  
the playback button:
a) If the load succeeds enough that a frame of data has been downloaded,  
the video element hides the surrogate image and shows the video instead,  
along with its controls, and turns on autoplay, so that the video will  
commence playback as soon as enough data is loaded.
b) If the load fails for any reason, the video and the surrogate frame are  
both hidden, by hiding the parent node, and the following paragraph is  
shown instead, which displays an unhelpful error message and a potentially  
helpful link to the video directly.

In legacy user agents, the surrogate image would show and the link to the  
video would be present, allowing the video to be viewed in another  
application. Clicking on the image would have no effect, even if it might  
cause a runtime error."

In the last phrase, I mention the runtime error, becuase the code should  
actually check if the load() function is available, and blah blah. I  
consider better to mention this fact, just like the explanation mentions  
the error message is not helpful.

8. I would like to comment on the use of the "irrelevant" attribute.  
Shortly, I believe web developers will use this as a quick way to *hide*  
elements - irrespective of the *semantical* use of the attribute. Why was  
this added? Where is it needed? Both of the provided examples seems like  
good candidates for using element.style.display=none with today's UAs.


That's about all for now.


[1]  
http://www.whatwg.org/specs/web-apps/current-work/multipage/section-global.html#the-irrelevant


-- 
http://www.robodesign.ro

Received on Thursday, 2 August 2007 21:00:40 UTC