[whatwg] Editorial comment r/e summary element

[Ian Hickson]

On Tue, 20 Sep 2011, Bruce Lawson wrote:
>
> Fair dames and damsels of the list
> 
> Consider
> http://www.whatwg.org/specs/web-apps/current-work/multipage/interactive-elements.html#the-summary-element:
> "The summary element represents a summary, caption, or legend for the rest of
> the contents of the summary element's parent details element, if any."
> 
> I read "if any" to mean there may or may not be "a summary, caption or
> legend".
>
> However, a questioner to HTML5 Doctor believes that <summary> can be used
> outside <details>, reading "if any" to sugest that there may not be a
> "summary element's parent details element".
> 
> (She wants to use <summary> at the top of an article to summarise its
> contents, because the ambiguous prose I quote suggests that a parent details
> element is optional).

It means that there might not be a <details> parent. The only way this 
could happen in a conformance situation is if the <legend> didn't have a 
parent at all, which is only possible in unconnected DOM fragments in 
script.


> Can we remove this ambiguity? "The summary element represents an 
> optional summary, caption, or legend for the rest of the contents of the 
> summary element's parent details element" would work.

The summary isn't optional (<summary> is a required child of <details>).

The "if any" style is used all over the spec; I'm not sure how to make it 
clearer without dramatically increasing the verbosity, which I would like 
to do to avoid drawing attention to aspects of the spec that are of 
relatively little practical importance. For example, replacing it with "if 
the element has such a parent" changes this minor point from a two-word 
side note to a whole sentence fragment taking a quarter of the sentence.

Anyone have any suggestions?

-- 
Ian Hickson               U+1047E                )\._.,--....,'``.    fL
http://ln.hixie.ch/       U+263A                /,   _.. \   _\  ;`._ ,.
Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'