Re: Who is the Intended Audience of the Markup Spec Proposal?

Ian Hickson <ian@hixie.ch>, 2009-01-29 21:15 +0000:

> On Thu, 29 Jan 2009, Michael(tm) Smith wrote:
> > 
> > OK, I've revised it to this:
> > 
> >   This specification is intended for producers of documents
> >   intended to conform to the requirements it describes, and
> >   individuals wishing to establish the correctness of documents
> >   with respect to the requirements it describes.
> 
> Thanks, that helps. The document online doesn't seem to have changed:
> 
>    http://www.w3.org/html/wg/markup-spec/#audience
> 
> ...but that could be a www.w3.org issue.

Or it could be that I just forgot to do a "cvs commit" after I
made the change. :) Sorry -- checked in now.

> Assuming the above audience statement, I have the following review 
> comments:
> 
> * I don't think we need to include the obsolete elements, since they're 
>   not needed for conformance (by definition).

I agree that they are not needed for conformance. However, I think
it's useful to keep them in there at this stage in the life of the
document, in part to help make readers aware of just which
elements are obsoleted (or have been proposed to be obsoleted). I
do think that no elements that we agree are obsoleted should be
included in an LC draft or anything beyond that.

Anyway, I did go ahead and raise bug 6501 for this. If I add a
comment to the Status section or another part of the doc stating
that no obsoleted elements will be included in any draft we may
publish at LC or beyond, would you be OK with that? If so, I'll do
that and close out the bug. If not, I'll keep it open and
encourage people who want to comment on it to do so there.

> * I don't think we should include <canvas>, since just saying the element 
>   exists doesn't really help authors without its API.

I raised bug 6502 for that. I don't agree with you rationale on
this. For a document that restricts its purpose do describing what
a conformant document is and describing what each of the elements
in the language represent, omitting <canvas> would seem to me to
be a bug. The document is explicitly not scoped to actually also
describe the behavior of <canvas> and/or how to actually use it in
a Web application -- but instead just to describe what <canvas>
and its accompanying attributes represent.

> * The comments I gave in 
>      http://lists.w3.org/Archives/Public/public-html/2009Jan/0386.html
>   ...apply; my preferred way of addressing those comments would be making 
>   the draft non-normative and then using formalisms only where it helps, 
>   instead of attempting to be comprehensive.

Raised bug 6503 for that.

> * There are significant authoring requirements missing, e.g. the 
>   requirements on alt="" for <img> and <area>, the rules on 
>   case-sensitivity for boolean attributes.

Those are mostly missing because I've yet to add complete
"Additional constraints" sections describing them. My intent is to
get them all in eventually. At the point when I do believe that I
have them documented completely, I suppose what I'll need to do is
send out a specific review request indicating that, and asking
everybody to review those parts for accuracy and completeness.

> * The <audio> section refers to an "audio controls" element.

Yeah, the <video> section has that too. It's a bug that's an
artifact of that text be slurped in from the assertions.sch file
in the whattf.org schema distribution. I've filed a validator.nu
bug (along with a simple patch) for it:

  http://bugzilla.validator.nu/show_bug.cgi?id=441

I've tweaked my doc build to patch the local copy of the
assertions.sch file I build from, and checked in the change, so
the text that's in now reads:

  The interactive element “audio” with the “controls” attribute
  cannot appear as a descendant of the “a” element.

I may well eventually just dispense entirely with pulling in that
text from the assertions.sch file -- and maybe with having the
separate Assertions section at all, and instead just put those
in an "Additional constraints" subsection.

> * The spec has some implementor-specific terminology like "view" and 
>   "browsing context".

Yes, those terms should not be in this document. I need to reword
the description of what the target attribute represents so that it
doesn't refer to "browsing context"; I've raised bug 6504 for that.

> * The spec doesn't define for authors how relative URLs are resolved.

(bug 6505) Is it necessary for it do so? That is, if the purpose
of this spec remains constrained to describing what a conformant
document is and what the elements and attributes are meant to
represent, would it need to describe how relative URLs are resolved?

> * I like the way all the information one needs about an element is all in 
>   one place (including text/html-specific things like optional end tags). 
>   I think it would be helpful to also include the element-specific APIs, 
>   so that authors don't have to go to yet another reference for those.

(bug 6506) I also personally really like the idea of having the
element-specific APIs in the same place as the rest of that
description of the element (i.e., the way you have it in HTML5
draft), and I know others have said they really find it useful as
well.

That said, it seems that they are not necessary for describing
document conformance nor for describing what the elements
represent (at least not unless you were to actually define their
DOM representations as being what they really represent).

But even if they are not necessary in this document in its current
scope, I still think it could be extremely useful for them to be
there. (The "Typical default display properties" section is also
not necessary, but I think it's still pretty useful -- and nobody
has so far complained about that being in the draft.)

So I'll try to get them into the draft in some form, and after I
do, we can take a look at it and see if they work OK in that
context.

> * A number of attributes have very vague definitions: defer="" and 
>   async="" on <script>, coords="" on <area>, target="" on many 
>   elements, href="" on <base>, etc.

Yeah, I know some of those are not particularly useful in their
current form, and I expect that further review and comments and
specific wording suggestions will help me make refinements to
those kinds of shortcomings in the draft.

> * Examples would be useful throughout.

Agreed. I do plan to add them.

Thanks extremely much for taking time to look through the draft
and provide substantive comments on it. Especially given that I
know you have some serious misgivings about its scope and utility,
I do sincerely appreciate that you made time anyway to look
through it carefully and offer specific suggestions for improving
it (such as it is). I would also very much appreciate more
feedback from you once I get the document further along.

  --Mike

-- 
Michael(tm) Smith
http://people.w3.org/mike/

Received on Friday, 30 January 2009 06:13:37 UTC