Errors in MSDN Library's Web Development section
The MSDN Library’s Web Development section is an important reference source for many web developers. Its accuracy is therefore important. But I can’t seem to find anywhere to report errors in the documentation. Does anyone know who to talk to if we need to get errors fixed?
In case anyone is reading this message who can fix such errors, the example given for the HTML Q element [1] is erroneous:
<P>He said,
<Q>"Hi there!"</Q>
If you consult the referenced HTML 4.0 specification, you'll discover that this example is seriously mistaken [2]. The specification states explicitly: ‘Visual user agents must ensure that the content of the Q element is rendered with delimiting quotation marks. Authors should not put quotation marks at the beginning and end of the content of a Q element.’
Developers following MSDN’s example will find that many user agents will, following the W3C’s specification, add delimiting quotations marks to the superfluous ones included in the text: including Amaya, Lynx, Gecko-based browsers, Opera, the current WebKit build (WebKit is the base for Safari and OmniWeb), Konqueror, and apparently Internet Explorer for Mac. Assistive technologies set up to differentiate quotations from surrounding text (for example, Window-Eyes can be configured to announce ‘quotation’) will irritate their users by reporting the quotation marks as well.
A better example might be:
<P>He said, <Q>Hi there!</Q>
Of course, this leaves the problem of legacy browsers, Trident-based browsers, and assistive technology that fails to report <Q>. MSDN might wish to recommend that developers worried about those create HTML that uses quotation marks in the textinstead of (notin addition to) Q. A span around the quoted text (not including the quotation punctuation) could carry a lang attribute for the quotation.
It could also make the following recommendation to those who wish to use the correct semantic element:
a) Using JavaScript, replace Q elements with their text properly delimited by quotation marks.
b) Using conditional comments, style Q differently with CSS as a fallback for Trident users with JavaScript disabled.
But the key thing is to fix the broken example.
[1]http://msdnwiki.microsoft.com/en-us/mtpswiki/05dfs802.aspx
[2]http://www.w3.org/TR/1998/REC-html40-19980424/struct/text.html#h-9.2.2
Q element
=========
In your examples for the Q element, you might like to show off it's LANG and CITE attributes. For instance:
<P>He said, <Q LANG="fr">Bonjour, ?a va?</Q> However, I did not reply at once.</P>
Or
<P>Rousseau opens the book with a paradox: <Q CITE="http://hypo.ge-dip.etat-ge.ch/athena/rousseau/jjr_cont.html#L1/1" LANG="fr">L’homme est n libre, et partout il est dans les fers.<Q>
Window-Eyes for example actually reads these quotations in French, which is rather cool. :)
If you were to provide a JavaScript fallback for display of quotation punctuation in Trident-based browsers, you might replace the second example with:
<P>Rousseau opens the book with a paradox: <A HREF="http://hypo.ge-dip.etat-ge.ch/athena/rousseau/jjr_cont.html#L1/1">“<SPAN LANG="fr">L’homme est n libre, et partout il est dans les fers.</SPAN>”</A>.</P>
The A holds the information previously conveyed by the CITE attribute; the SPAN is placed within the quotation punctuation so that the quotation marks are read by screen readers in the host language (English in this case) and the quotation content is read in its own French.
Q element
=========
In your examples for the Q element, you might like to show off it's LANG and CITE attributes. For instance:
<P>He said, <Q LANG="fr">Bonjour, ?a va?</Q> However, I did not reply at once.</P>
Or
<P>Rousseau opens the book with a paradox: <Q CITE="http://hypo.ge-dip.etat-ge.ch/athena/rousseau/jjr_cont.html#L1/1" LANG="fr">L’homme est n libre, et partout il est dans les fers.<Q>
Window-Eyes for example actually reads these quotations in French, which is rather cool. :)
If you were to provide a JavaScript fallback for display of quotation punctuation in Trident-based browsers, you might replace the second example with:
<P>Rousseau opens the book with a paradox: <A HREF="http://hypo.ge-dip.etat-ge.ch/athena/rousseau/jjr_cont.html#L1/1">“<SPAN LANG="fr">L’homme est n libre, et partout il est dans les fers.</SPAN>”</A>.</P>
The A holds the information previously conveyed by the CITE attribute; the SPAN is placed within the quotation punctuation so that the quotation marks are read by screen readers in the host language (English in this case) and the quotation content is read in its own French.
=================================================
I figured since you thought my tipoff about Q was helpful I ought to take a closer look at the documentation related elements and attributes. I've found a few other things that aren't quite right.
BLOCKQUOTE element
==================
Unfortunately, the example for BLOCKQUOTE [1] adds superfluous quotation punctuation and gives the impression that BLOCKQUOTE should be used for short bits of direct speech (which is probably the place of Q).
<P>He said,
<BLOCKQUOTE>"Hi there!"</BLOCKQUOTE>
Also, while that might well validate as HTML 3.2 (which is what MSDN refers to in this instance), it would no longer validate as HTML 4.01 because you would need a block element such as P or DIV inside BLOCKQUOTE. Web developers would probably want to be made aware of that.
Something lengthier might be better:
<P>Hobbes presents an extremely pessimistic view of human beings in a state of nature:</P>
<BLOCKQUOTE CITE="http://etext.library.adelaide.edu.au/h/hobbes/thomas/h68l/chapter13.html">
<P>Whatsoever therefore is consequent to a time of war, where every man is enemy to every man, the same consequent to the time wherein men live without other security than what their own strength and their own invention shall furnish them withal. In such condition there is no place for industry, because the fruit thereof is uncertain: and consequently no culture of the earth; no navigation, nor use of the commodities that may be imported by sea; no commodious building; no instruments of moving and removing such things as require much force; no knowledge of the face of the earth; no account of time; no arts; no letters; no society; and which is worst of all, continual fear, and danger of violent death; and the life of man, solitary, poor, nasty, brutish, and short.</P>
</BLOCKQUOTE>
CITE attribute
==============
Interestingly, the example code for the CITE attribute [2] gets the quotation punctuation issue right by *not* including the quotation marks inside Q. Unfortunately, it also gets things wrong by treating Q as though it was a block element, when it should use BLOCKQUOTE:
<HTML>
<BODY>
<Q id="greatQuote" cite="http://www.Shakespeare.the.great.com">
To Be or Not to Be, That is the Question</Q>
</BODY>
</HTML>
A better example might be:
<P>As Claudius and Polonius withdraw, Hamlet enters and begins his most famous monologue: <Q cite="http://www-tech.mit.edu/Shakespeare/hamlet/hamlet.3.1.html#64">To be, or not to be: that is the question<Q>.</P>
The CITE attribute is arguably especially useful for this sort of pinpoint reference.
CITE element
============
The CITE element is incorrectly described. MSDN defines a "citation" as "a reference to a book, paper, or other published source material" [3]. That's not a description of a "citation" in ordinary English (you can cite *anything*; it doesn't need to be published material); nor does it reflect the description of CITE in the HTML specifications. The cited HTML 3.2 specification states CITE is to be "used for citations or references to other sources" [4]. The current HTML 4.01 specification [5] offers an example that confirms that CITE is not limited to published materials:
As <CITE>Harry S. Truman</CITE> said,
<Q lang="en-us">The buck stops here.</Q>
Of course, given that browsers tend to depict CITE in italics by default, in practice one would probably wish to add CLASS="person" to CITE in that example and style that plain with CSS:
cite.person { font-style: normal; }
Anyhow, I hope this helps. You folks can doubtless come up with even better examples to demonstrate these elements and attributes. They may be tricky to write, but web developers need all the examples of good markup they can get. :)
References
==========
[1] http://msdn.microsoft.com/library/default.asp?url=/workshop/author/dhtml/reference/objects/blockquote.asp
[2] http://msdn.microsoft.com/library/default.asp?url=/workshop/author/dhtml/reference/properties/cite.asp
[3] http://msdn.microsoft.com/library/default.asp?url=/workshop/author/dhtml/reference/objects/cite.asp
[4] http://www.w3.org/TR/REC-html32#phrase
[5] http://www.w3.org/TR/REC-html40/struct/text.html#h-9.2.1
