[drupal-docs] Styleguide

[Moshe Weitzman]

>
> There are two (related) problems: violation of encapsulation, and 
> violation of separation of presentation and content. I'll expand:
>
> Headers suggest a hierarchical structure, and so does the book 
> module's hierarchy.   These two schemes for structure can quite easily 
> be in conflict.   At the same time, HTML's definition does not give 
> control over ordering of h1, h2, etc. elements.   So it's possible to 
> write valid HTML with an H1 section 'inside' an H2 section, for 
> example.   This is syntactically valid but logically silly.  Book 
> module at least enforces its hierarchy.
>
> If you're putting H1, H2, ... elements inside of a book page for a 
> reason other than sectioning, you're violating the 'intent' of these 
> elements, i.e., using the header elements as presentational markup.   
> This is asking for trouble, for reasons which I hope are well 
> understood.  If you are trying to indicate structure, why not let book 
> module handle it?  Isn't that its main purpose in life?
>
> In addition, preventing 'internal sectioning' would lead to smaller, 
> flatter nodes, which should be easier to read, to edit, and to 
> navigate.

i wonder if someone would make these statements after writing a bunch 
of book pages. The statements sounds nice, but are impractical. We 
*should* to provide some approved way for authors to add structure 
within a single page. And a list does not always satisfy this need. To 
describe all but the most simple concepts, you want structure.

If we force authors to create subpages every time they want structure 
we will not end of with "smaller, flatter nodes which are easier to 
read and navigate". We will end up with deep, annoying hierarchies 
where it takes 7 clicks to get to the damn URL for the Contrib 
repository (e.g Handbook => Contributors Guide =>  Development => CVS 
=> Repositories => Contributions => Configuration). Another example 
might be a page like http://drupal.org/node/12352. We should not 
recommend that authors break up such a page into many subpages, IMO

Noone would argue that header tags should be used for getting big bold 
letters, so lets concentrate on the structure issue.