[documentation] the documentation site is too broken and lacks formatting and writing style

[Charlie Lowe]

Robert Castelo wrote:
> 
> If there's a problem exporting markup with sub-headings, could we not 
> deal with that at the code level, parse the output and break it up into 
> sub-pages on export?

What about using the XHTML 2.0 heading/section specifications for input:

http://www.w3.org/TR/2004/WD-xhtml2-20040722/mod-structural.html#sec_8.5.

This gets away from the problem with using <h2>,<h3>... when 
documentation writers create the HTML for book pages. Could a filter 
process this and then we could just use <section> and <h> instead? 
Drupal could produce <h2>,<h3>...  on output.