[drupal-docs] XHTML in our documentation - Textile, Markdown, ...

[Vladimir Zlatanov]

> I propose that we ditch HTML authoring and use author using Markdown [1] 
> or Textile [2] formats. These formats are easy to learn, and always 
> output valid XHTML. Plus, we already have Drupal modules for each. Also, 
> I think it will be easier to communicate style rules using one of these 
> syntaxes (e.g. "top level headlines begin with **").
+1 for consistentcy 
-1 for the actual markup

I've been experimenting for the past few months with XHTML documents.
The main reason was similar - I want something which is convertible to
Docbook without complications, useable directly with browsers, easily
styleable with CSS as article or book.

My solution, for the time being, applying a more restrictive discipline 
on how do I write the documents.

For example:

article - html document or div class=article
article title - H1 class=article
article author, date, ... span(s) in a div class=header
....
section div.section
header hN inside the above div
subsection div.section inside a section
.....

This discipline follows the logic of an article, or book as defined in 
Docbook (or latex for that matter), the classes are not 100% nessesary,
but help a lot with the styling and are useful with XLST transforms as
well.

May be a policy similar to the coding standard should be introduced, so
documentation is not accepted unless following an agreed style.

cheers,
Vlado