Re: adding a note to 4.3.10.1 Creating an outline

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