Re: "Technical specification"

On May 22, 2009, at 12:07 PM, Larry Masinter wrote:

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

This title is poor for the following reasons:

1) "HTML5 interpreter" is not a normal term used to refer to an HTML5  
User Agent. There is no reason to use this neologism.

2) HTML5's APIs are not defined only for JavaScript. They are defined  
using Web IDL and may apply to any language that has Web IDL bindings.

3) A spec's requirements are normally referred to as "conformance  
requirements", not "implementation requirements". Conformance  
requirements are testable MUST/SHOULD/MAY/MUST NOT etc statements that  
address matters of interoperability. Implementation requirements  
require specific implementation characteristics which are independent  
of conformance.

4) The document contains conformance requirements for authoring tools  
and conformance checkers; it's unclear to me how they could be labeled  
as "HTML interpreters" even if we were to accept the neologism.


Basically this subtitle sounds like your way of saying "this document  
isn't what Larry Masinter thinks an HTML spec should be". And you are  
entitled to express that opinion, but not to have it expressed for you  
by the document title.

In fact, from this title and the other discussion, it's clear that you  
don't disagree that the document describes a vocabulary and associated  
APIs for HTML5. Perhaps you think it does other stuff in addition  
which should be called out. If so, name that stuff, and let's see if  
it is worth adding without making the title overly long. The way I  
would describe the extra stuff is "processing requirements". But I  
think it goes without saying that a language specification should  
describe processing requirements, as it is the norm for just about  
every language specification ever, from SVG to Scheme to XForms to C++  
to Python. But maybe you want to make a case that these should be  
called out anyway.



> 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.

What you quote above describes conformance requirements for  
implementations of the API. It doesn't require any specific  
implementation strategy since all conformance requirements are  
implicitly "as if". This is the correct way to write conformance  
requirements per RFC2119/BCP14.

>
> 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".

Your alternative does not state any conformance requirements, it's  
just a free-floating description. There are no RFC2119 keywords used.

Do you really want to object to consistent use of RFC2119 keywords to  
describe conformance requirements?

Regards,
Maciej

Received on Friday, 22 May 2009 22:16:44 UTC