Re: adding a note to 4.3.10.1 Creating an outline

Hi Mike, comments inline

--

Regards

SteveF
HTML 5.1 <http://www.w3.org/html/wg/drafts/html/master/>


On 28 February 2014 00:02, 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.
>
>
right its a case of no software is required to implement the algorithm to
be conforming to the spec, but if one does then there are requirements to
followed.



> For the UA case what's lacking at this point is any requirement for how UAs
> must expose it.
>

right

>
> 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/
>

there is also a XSLT implementation producing a TOC in ePub
https://code.google.com/p/daisy-pipeline/wiki/HTMLUtils#html-outliner.xsl


>
> 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.
>

The problem is and has been that authors have been lead to believe the
outline is something real in browsers and other user agents such as AT. But
in user agents the heading level is purely derived from the level indicated
in the heading name 1,2,3,4,5,6. the effects of sectioning elements on
heading level are theoretical only, and this appears unlikely to change at
this time.


> > 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.
>

It has obviously not been clear. The spec has been written primarily for an
implementer audience and what is clear to implementers is not always clear
to non implementers due to the style of language used. There was/is
authoring advice  suggesting using all h1's is ok as their level is
dependent on their nesting in section and numerous code examples to this
effect. I have been editing the spec to clarify and think there is a need
to make further edits.


>
> > 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.
>

sure, i just dashed off the text to elicit feedback.

>
> 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).
>


thanks for the feedback and proposed text

>
> > [1] http://www.w3.org/html/wg/drafts/html/master/sections.html#outlines
>
>   --Mike
>
> --
> Michael[tm] Smith http://people.w3.org/mike
>