- From: Michael[tm] Smith <mike@w3.org>
- Date: Fri, 28 Feb 2014 09:02:54 +0900
- To: Steve Faulkner <faulkner.steve@gmail.com>
- Cc: HTMLWG WG <public-html@w3.org>
Hi Steve, Steve Faulkner <faulkner.steve@gmail.com>, 2014-02-25 15:49 +0000: > Section 4.3.10.1 Creating an outline [1] defines an outlining algorithm, > but there are no implementation requirements for user agents. True but there are nonetheless requirements, and other implementations of the requirements. So it's clear at least that the algorithm is implementable. For the UA case what's lacking at this point is any requirement for how UAs must expose it. However, there is already a JavaScript library that follows the spec to provide an "HTML5Outline(element)" method that returns an outline object for a subtree or whole document -- depending on what element you give it -- (and as a bonus an outline.asHTML convenience method to generate an HTML representation of an outline) - https://code.google.com/p/h5o/ So I'd like for the spec to actually explicitly define something like that HTML5Outline(element) method, or an element.createOutline or whatever name. But so far Hixie's not been keen on adding such a createOutline method to the spec, and nobody else has yet specced anything for it. So here we are. > Authors/developers have been lead to believe that the algorithm is > something real that is implemented by user agents, For better or worse, the outline algorithm is actually real already. It doesn't have to be implemented in UAs to be real. It's implemented per spec in some other tools -- including some browser plugins/extensions and in the validator -- so it's not like it's completely irrelevant or something. > this has lead to the > dissemination of incorrect authoring advice in books, on the web etc. Well. I don't think that can be blamed on the spec. The spec clearly does not yet require UAs to expose an outline in way. People who write books about HTML have an obligation to read the spec and understand it. Otherwise they shouldn't be writing books about HTML. > I propose to add a note at the start of section 4.3.10.1 to clarify, > something along the lines of: > > "the implementation of the outline algorithm in user agents is not > required, Its inclusion in the specification is for informative purposes > only. " I think that would be a misleading note, for the reasons I gave above. The algorithm is not there for informative purposes only. It's there so that we can have a standard means for constructing an outline from an HTML document, and interoperability among tools that want to provide some way to expose an outline from an HTML document. So if you were to add a note I'd suggest it be something more like: This specification does not yet require browsers to expose any means for Web authors to programatically generate an outline from a document. Therefore no browsers yet actually directly expose any means Web authors can use for generating an outline. However, JavaScript libraries may provide some mechanism (in fact such libraries already exist) and end users may be able to view an outline for a document by using, for example, a third-party browser plugin that follows the outline algorithm to generate an outline (in fact, such browser plugins already exist). > [1] http://www.w3.org/html/wg/drafts/html/master/sections.html#outlines --Mike -- Michael[tm] Smith http://people.w3.org/mike
Received on Friday, 28 February 2014 00:02:56 UTC