This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.
public-html-comments posting from: Shelley Powers <shelleyp@burningbird.net> http://www.w3.org/mid/4E03F18F.5020907@burningbird.net Aside from the fact that the HTML5 Edition for Web Authors document still has the silly lang attribute in the HTML source, there are other problems with the document, notably an inconsistency of references. If the purpose of the document is to provide a more web author centric view of the HTML5 specification, without burying web authors in the minutia of implementation details, the document only partially succeeds. For instance, we can find a web author centric view of the MediaController[1] . However, if you click on any of the methods, properties, or events listed in the table describing the MediaController interface, you're taken back to the main HTML5 specification--whereby you're completely drowned in implementation detail. Yet right underneath the table are web author friendly descriptions of both the MediaController interface methods and properties. These are what should be what's linked within the MediaController table. In addition, the events also need a more web friendly view, as clicking on each of these also returns the person to the full HTML5 spec. Shelley Powers [1] http://www.w3.org/TR/2011/WD-html5-20110525/author/the-track-element.html#mediacontroller
Shelley, in reply to your comment #0: > For instance, we can find a web author centric view of the > MediaController > http://www.w3.org/TR/2011/WD-html5-20110525/author/the-track-element.html#mediacontroller > However, if you click on any of the methods, > properties, or events listed in the table describing the MediaController > interface, you're taken back to the main HTML5 specification--whereby > you're completely drowned in implementation detail. > > Yet right underneath the table are web author friendly descriptions of > both the MediaController interface methods and properties. These are > what should be what's linked within the MediaController table. Fully agreed, and I think I can actually tweak the build I made that generates the author view such that those links targets are rewritten to point to the author-friendly parts you mentioned. I'll make time to mess around with it this weekend or at the beginning of next week. It'd definitely be a big usability win for the author view. > In addition, the events also need a more web friendly view, as clicking on > each of these also returns the person to the full HTML5 spec. Same thing there -- I have not examined the source markup for those yet, but I expect I can probably fiddle with the build to get the link targets rewritten.
(In reply to comment #1) > Shelley, in reply to your comment #0: > > > For instance, we can find a web author centric view of the > > MediaController > > http://www.w3.org/TR/2011/WD-html5-20110525/author/the-track-element.html#mediacontroller > > However, if you click on any of the methods, > > properties, or events listed in the table describing the MediaController > > interface, you're taken back to the main HTML5 specification--whereby > > you're completely drowned in implementation detail. > > > > Yet right underneath the table are web author friendly descriptions of > > both the MediaController interface methods and properties. These are > > what should be what's linked within the MediaController table. > > Fully agreed, and I think I can actually tweak the build I made that generates > the author view such that those links targets are rewritten to point to the > author-friendly parts you mentioned. I'll make time to mess around with it this > weekend or at the beginning of next week. It'd definitely be a big usability > win for the author view. > > > In addition, the events also need a more web friendly view, as clicking on > > each of these also returns the person to the full HTML5 spec. > > Same thing there -- I have not examined the source markup for those yet, but I > expect I can probably fiddle with the build to get the link targets rewritten. Thank you for your efforts on this.
OK, I took a shot at fixing the links for the DOM attributes such that they should now be pointing at the 'domintro' (author-friendly) stuff instead of going back to the full spec. For example: http://dev.w3.org/html5/spec-author-view/the-track-element.html#mediacontroller Please take a look and let me know if you see any problems. i've not fixed the corresponding links for the event-handlers attributes, but I'm working on that now. BTW, once I get this done, these fixes will of course go into the version we publish as a FPWD.
...and now the changes I was trying in order to deal with the event handlers seem to have regressed the earlier changes I made for the DOM attributes. So please bear with me. I'll post another comment when I have it stabilized.
(In reply to comment #4) > ...and now the changes I was trying in order to deal with the event handlers > seem to have regressed the earlier changes I made for the DOM attributes. So > please bear with me. I'll post another comment when I have it stabilized. Thanks again for your effort to fix the document generation.
OK, after taking a break and then going back and battling a little further with the Frankenstein monster of a build process I hacked together to generate this doc, I think I finally have the output working as expected. So, please do take a look again now: http://dev.w3.org/html5/spec-author-view/the-track-element.html#mediacontroller I did some limited smoke-testing and found a couple of links that aren't getting rewritten as expected, but I'll try to get those figured out and fixed too. But I'm sure there are still some others, so if you find any, please post a comment here.
argh. Regressed it again while trying for fix the exceptions. (re)Fixing now
OK, as far as the links I found that weren't getting rewritten as expected, I figured out the reason and I've fixed it... sorta What I mean by "sorta" is, if you go here: http://dev.w3.org/html5/spec-author-view/the-track-element.html#texttrack_2 ...and then you click on the link for the "textTracks" attribute there (href=#dom-media-texttracks), it actually takes you to the description of "media.textTracks.length" attribute -- not to the description of the "media.textTracks" object itself. But, the description for the "media.textTracks" object is right there in the same "domintro" box, just below the "media.textTracks.length" description. There aren't many cases like this -- only about 20 or so in the whole spec (I know because I had to write some special-casing to handle them) -- and I think for all of them the "real" intended description is going to be in close enough proximity that you won't likely notice it's not taking you to the exact anchor for the description you need. So while that's certainly suboptimal, I hope it's judged close enough to be acceptable. The thing is, due to funkiness of the hack I'm using to rewrite the link targets, it would be a lot of extra special casing to get those links to rewritten to the exact targets (and probably some further regressing while I'm monkeying around with it...). Which is not to say it's not doable, but just not sure it's worth it unless there are some links that are ending up going somewhere way off from where they should be. Anyway, all that said, you will still find attributes in some IDLs that will take you to targets in the full spec (instead of to ones in the author view). For example, if you go here: http://dev.w3.org/html5/spec-author-view/the-track-element.html#htmlmediaelement ...and scroll down and check the links for some of the attributes -- e.g., "autoplay" and "loop" -- you'll see that they point back to the full spec. As far as I can tell the reason for all those remaining cases is just that there are not (yet) any "domintro" (author-friendly) descriptions of those attributes in the spec. So I think the fix is just for "domintro" descriptions for those to actually be added. I think I can actually generate a list of all the attributes for which that's the case. So I think I'll do that and file a separate bug report for it. In the mean time, I think I'll take another break from pulling threads on this so that I don't re-regress anything. So please do check it again now and if you find anything that it seems like I missed, post some more comments.
(In reply to comment #8) > OK, as far as the links I found that weren't getting rewritten as expected, I > figured out the reason and I've fixed it... sorta > > What I mean by "sorta" is, if you go here: > > http://dev.w3.org/html5/spec-author-view/the-track-element.html#texttrack_2 > > ...and then you click on the link for the "textTracks" attribute there > (href=#dom-media-texttracks), it actually takes you to the description of > "media.textTracks.length" attribute -- not to the description of the > "media.textTracks" object itself. > > But, the description for the "media.textTracks" object is right there in the > same "domintro" box, just below the "media.textTracks.length" description. > > There aren't many cases like this -- only about 20 or so in the whole spec (I > know because I had to write some special-casing to handle them) -- and I think > for all of them the "real" intended description is going to be in close enough > proximity that you won't likely notice it's not taking you to the exact anchor > for the description you need. > > So while that's certainly suboptimal, I hope it's judged close enough to be > acceptable. > > The thing is, due to funkiness of the hack I'm using to rewrite the link > targets, it would be a lot of extra special casing to get those links to > rewritten to the exact targets (and probably some further regressing while I'm > monkeying around with it...). Which is not to say it's not doable, but just not > sure it's worth it unless there are some links that are ending up going > somewhere way off from where they should be. > > Anyway, all that said, you will still find attributes in some IDLs that will > take you to targets in the full spec (instead of to ones in the author view). > For example, if you go here: > > > http://dev.w3.org/html5/spec-author-view/the-track-element.html#htmlmediaelement > > ...and scroll down and check the links for some of the attributes -- e.g., > "autoplay" and "loop" -- you'll see that they point back to the full spec. > > As far as I can tell the reason for all those remaining cases is just that > there are not (yet) any "domintro" (author-friendly) descriptions of those > attributes in the spec. So I think the fix is just for "domintro" descriptions > for those to actually be added. > > I think I can actually generate a list of all the attributes for which that's > the case. So I think I'll do that and file a separate bug report for it. > > In the mean time, I think I'll take another break from pulling threads on this > so that I don't re-regress anything. So please do check it again now and if you > find anything that it seems like I missed, post some more comments. Looks good! I appreciate the work. And thanks for the additional work finding the remaining attributes without the "author friendly" view. This generated document is going to be much more approachable to the web page designers and developers who just don't need the implementation material. Thanks again for your effort. Should we mark this as resolved, and close it since you'll handle those without author friendly description in a separate bug?
(In reply to comment #9) > Thanks again for your effort. Should we mark this as resolved, and close it > since you'll handle those without author friendly description in a separate > bug? Yep -- moving to resolved-fixed now. Thanks again for having raised this. It's something that had bothered me previously about the author view as a well, but I'd never worked up enough motivation to actually get around to fixing it, so it helped to get confirmation that it's important, and some nudging to put some effort into getting it done.
Thanks for doing the fix. And filing the bugs on the remaining areas of the spec that don't have an author friendly description. Now if I remember correctly, I've verified the fix so I move this to closed.