[whatwg] One document or two?

[Ian Hickson]

On Sat, 26 May 2007, Julian Reschke wrote:
> Nicholas Shanks wrote:
> > Various people have expressed opinions in favour of either one spec to rule
> > them all, or two specs for different audiences. Is not the simplest solution
> > to have two views upon the same spec?
> > 
> > HTML 5, Full Version (User Agent Edition)
> > "<foo> is deprecated and should not be used, but you have to support it
> > anyway."
> > 
> > HTML 5, Abridged Version (Web Author Edition)
> > "<foo> is deprecated and should not be used."
> > 
> > You can even have them at the same URL, with a pair of radio buttons to
> > toggle between them (which just toggles display: none on a class to hide the
> > unnecessary info:
> > "<foo> is deprecated and should not be used<span class="full">, but you
> > have to support it anyway</span>.")
> > 
> > Since I anticipate 99% or more of people who will read the document will be
> > HTML authors finding out about the new spec, Abridged should probably be the
> > default view.
> 
> I think this is definitely the right thing to do.

I've now done this, though I left "complete" as the default view, so that 
people don't come across the spec and miss anything.


> One more thing: although playing with client-side toggles and CSS may be 
> interesting, I think the deliverables should clearly be two different 
> documents, with different names at different URLs.

The documents are now available at the following URLs:

   http://www.whatwg.org/specs/web-apps/current-work/?style=complete
   http://www.whatwg.org/specs/web-apps/current-work/?style=author
   http://www.whatwg.org/specs/web-apps/current-work/?style=highlight

(Note that this either requires JavaScript or a user agent that is 
hard-coded to hide or highlight the elements with the class "impl" as 
appropriate.)

In addition, there are radio buttons to change this dynamically (they set 
a cookie to remember the value, which is overridden by the values in the 
URL, so if you want it to remember the value, don't use one of the URLs 
above). You can also change the value dynamically without JS, if you don't 
have JS or have it disabled, by using your browser's alternative style 
sheet switcher UI. (That's all the JS is doing behind the scenes.)

If anyone can write a tool that uses html5lib to parse a document, then 
filters the resulting DOM to remove any nodes that match a particular 
filter (in this case, "has a class with the value 'impl'"), and finally 
outputs HTML again, I can add it to the pipeline to make a static copy of 
the "author-only" page too, if people want that.


On Sat, 26 May 2007, Elliotte Harold wrote:
> 
> I think it would be better for the abridged version not to mention foo 
> and other deprecated elements at all.

Done.


> > You can even have them at the same URL, with a pair of radio buttons 
> > to toggle between them (which just toggles display: none on a class to 
> > hide the unnecessary info:
> 
> Now that's just evil. Each separate resource should have at least one 
> URL. There may be one source document, but the views are different 
> documents and should have different URLs.

I don't think alternative style sheets are evil; in fact, they seem to be 
quite within the architecture of the Web. Surely you don't think that, 
e.g., GMail is evil for having the same URL for whether your contact list 
is hidden or expanded.

-- 
Ian Hickson               U+1047E                )\._.,--....,'``.    fL
http://ln.hixie.ch/       U+263A                /,   _.. \   _\  ;`._ ,.
Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'