RE: "Technical specification"

(I didn't pursue the discussion on the www-tag list because it seemed to be clear that this was not going to a TAG discussion topic. (at least, there was no pick-up by other TAG members) and that the conversation belongs elsewhere. I've spent much more time editing IETF documents than W3C ones, and that history colors my perspective.

Within W3C, the relevant guidelines are:

    http://www.w3.org/TR/qaframe-spec/
    http://www.w3.org/2003/Editors/

and (I think most simply):

   http://www.w3.org/1999/09/specification 


which has the simple rule:

"The document should state what sort of things is (sic) being defined."

Of course, the title of the document is one place where the document states what it is defines.

I think "A vocabulary and associated APIs for HTML and XHTML" doesn't match closely what's in the document. There is a vocabulary (the HTML4 vocabulary with additional terms and some terms dropped), but more accurately the document normatively defines functional requirements for implementations of HTML+JavaScript interpreters. 

So I might suggest something like:
"HTML5: Implementation Requirements for HTML5 interpreters and Related JavaScript APIs"

might be a more fitting subtitle? While the document also gives authoring advice for those wishing to produce content which would work with HTML5 interpreters, such advice is scattered through the document, and the primarily focused on interpreters. 

It might be possible to create a more traditional language definition using the bulk of the material, but expressed in less operational terms. I was hoping for something like that from Mike Smith's document, and still have hopes it might be produced.

Let me try to be more specific. To picked a paragraph at random (but there are hundreds like this):

" The DOM attributes width and height must return the rendered width and height of the image, in CSS pixels, if the image is being rendered, and is being rendered to a visual medium; or else the intrinsic width and height of the image, in CSS pixels, if the image is available but not being rendered to a visual medium; or else 0, if the image is not available or its dimensions are not known. [CSS21] On setting, they must act as if they reflected the respective content attributes of the same name."

This tells one how to implement image.width and image.height and what they "must return". The term "available" is not well-defined except through providing algorithms for fetching images and predicting the behavior. There's no particular reason to know whether, for example, an image specified through a "data:" URI  is "available" or not (I could guess, but I'm no sure), or whether one that requires authentication is "available", or whether, say, the image URI points to a resource which is available (sic) in several different sizes but has a preferred size (is that the intrinsic width and height?) Is the specification tied to only HTTP, file and ftp URIs? 

A language definition would define the terms more abstractly, not from the perspective of the implementer of an interpreter.

For example:

"The DOM attributes width and height are the width and height of the image, in CSS pixels, if known, or else 0 if not known. Typically, if the image is being rendered visually, the width and height are of the rendered image; unrendered images may have an intrinsic width and height. Width and height may not be known if the image is not currently "available" -- still being retrieved, not loaded, or in an otherwise unknown format."

The difference is significant from a conformance point of view. It gives implementations leeway to implement access methods for images, but warns authors of JavaScript programs that use  of width and height should not rely on details of exactly when they are known. image 

I think it's a better language -- allows a more extensible, well-defined, and ultimately a more predictable web, to not tie down forever the exact mechanisms of "available".  

Larry
-- 
http://larry.masinter.net

Received on Friday, 22 May 2009 19:08:07 UTC