Re: [whatwg] section 3 top headers

(-whatwg to reduce cross-posting)

On Sat, 2 May 2009, Shelley Powers wrote:
> 
> Your top level section headers in Section 3 don't make a lot of sense.
> 
> In particular, you insert a section on the paragraph element, at the 
> same top level that you reference all HTML elements.

This doesn't appear to be accurate... Could you elaborate? Which sections 
are you referring to?


> Why did you plunk the paragraph in as a separate section? And I'm also 
> assuming I misread the bit about other elements straddling paragraphs. 
> I'm assuming you don't mean that something like

I'm not sure I understand what you mean here.


> And let's look at the section headers:
> 
> Introduction
> Documents
> Elements
> Content Models
> Paragraphs
> APIs in HTML documents
> Dynamic Markup insertion
> 
> There's no cohesive pattern to this section. One moment you're talking 
> about Elements in the DOM, the next paragraph elements. And you're 
> actually defining the paragraph element, but the elements are described 
> fully in Section 4. Where you also describe the paragraph element.

If you have any concrete suggestions for how to make it clearer, please 
let me know.

Of note, the "paragraph" section you cite here isn't about the <p> 
element, so it doesn't seem appropriate to have it with the <p> element.


On Sun, 3 May 2009, Philip Taylor wrote:
> 
> Some specific suggestions for this section (mostly based on blog 
> comments):
> 
> Possibly the term "paragraphs" should be changed, to prevent people 
> confusing it with the paragraph (<p>) element. (Shelley suggested 
> "structural blocks". I can't think of any particular suggestions). The 
> "paragraphs" concept seems to be used in very few places, so it doesn't 
> seem worth using a common term that people will already assume some 
> (incorrect) meaning for.

The term is literally the dictionary meaning of "paragraph" ("a distinct 
section of a piece of writing, usually dealing with a single theme and 
indicated by a new line, indentation, or numbering"). What other term 
would you recommend?


> The first paragraph of the "paragraphs" section should be explicit that 
> this is a more general concept than just the <p> element. Perhaps a 
> (non-normative) description like "A paragraph is defined here as a run 
> of <a href>phrasing content</a>." would put people in the right frame of 
> mind to read the rest of the section, so they don't think it's just 
> talking about <p> elements.

I've tried to add a note to this effect.


> The concept of "straddl[ing] paragraph boundaries" is non-obvious, and 
> should be illustrated by examples. When it's first mentioned, the text 
> should refer to the second and third examples later in the section, and 
> the descriptions of those examples should explicitly say that the ins/a 
> elements are straddling the boundaries.

I've moved the examples around to try to make this clearer.

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

Received on Friday, 5 June 2009 22:17:45 UTC