Re: adding a note to 4.3.10.1 Creating an outline

On Fri, Feb 28, 2014 at 11:02 AM, Michael[tm] Smith <mike@w3.org> wrote:
> 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) -


I like that idea, but I would prefer it to be declarative since it has
clear rendering consequences.

Cheers,
Silvia.

>
>   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:14:18 UTC