[drupal-docs] Styleguide

[puregin]

On 24 Apr 2005, at 11:39 PM, Steven Wittens wrote:

>
>>
>>      I would like to re-iterate that it's very important that we 
>> *not* include
>> any headers in handbook nodes (no <H1> ... <H6>)  The reason: headers
>> are about structure.  Structure should be sole domain of book module 
>> or
>> whatever else holds the content.    Putting header tags into a node
>> gives 'false structure' .    Subsections of a given section, 
>> therefore,
>> should always be constructed as a child of that section.
>>
>>      In fact, perhaps we need a special filter for this situation.
>
>
> I don't see the problem with header tags. Within a single page, the 
> page title is a h1. Below that, we can have h2, h3, h4 etc. It is 
> semantically valid and makes the page more accessible.

Hi Steven,

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.

>
> If there are problems with headers in the printer friendly output, 
> then they should be fixed there. For example by renumbering the 
> headers inside an article automatically when doing the printer 
> friendly output. This isn't all that hard in fact.

This is what I'm doing now.  It's not difficult, but it is a kludge, 
and it does require guessing.  "Is this a real subsubsection, or just 
an emphasized paragraph?"   Should I treat an H1 inside of a node as 
the start of a new chapter?  If so, where does the content in the 
node's children and right siblings go?  If I treat it as a subsection 
of the given section, what do I do with a node that contains the header 
sequence <H1> <H3><H2>?  Syntactically valid, but silly.  Yet, such 
example exist within the present handbook (see 
http://lists.drupal.org/archives/drupal-docs/2005-04/msg00137.html).

We could have complicated rules about how, when, and why H1 and friends 
should be allowed in the book nodes, but enforcing such rules would be 
difficult.  I don't see any useful functionality we'd gain by allowing 
these elements, but we have much to gain by dumping them.

The same considerations apply to any attempts we might make at 
structured import/export of book module content.

Best regards, Djun