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


(PS. By mistake, I sent this email to the www-html mailing list yesterday.  
Apologies for that.)


-- 
http://www.robodesign.ro

Received on Friday, 3 August 2007 09:46:46 UTC