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

[Chris Messina]

This is really something of an unforunate discussion. I think what
Moshe wants is completely legitimate and in fact, necessary. But in
reading over this thread, all I hear is debate about implementation.

Here's the deal: we need standard markup across all drupal
documentation. This is essential to creating good stylesheets that
will output the material properly for various viewing devices (screen,
print, assistive technology). It doesn't matter whether it's HTML or
XHTML so long as its consistent.

If we can agree on that, we can move to the next discussion, which is
"what should our standards be?" We effectively need a styleguide for
drupal docs, just like there is a code styleguide. This should cover
both naming conventions and the preferred markup for various types of
information. For example, as has been recently recommend, inline code
snippets should be contained in <code> tags; blocks of code should be
contained in <pre><code> tags. That kind of information would be
included in a drupal documentation styleguide.

Lastly, once the styleguide and conventions have been established, we
can worry about implementation. As Moshe correctly points out, Textile
and Markdown produce valid code, a requisite for the stylesheets I
mentioned above. However, not everyone agrees that an intermediate
language should be used to markup the documentation. Ok, fine. That's
not the issue; we need valid output that everyone can write. If it's
plain XHTML or HTML, great. But it needs to be universally agreed upon
for which standards are enforced, just as standards are enforced for
drupal code style in patches.

I would recommend going ahead and using XHTML to make our documents
future-ready; though I'm a fan of Textile, I do see how it's not going
to be universally prefered. For those wanting Textile or Markdown,
they can write up their docs in their preferred language and then run
it through a utility like Textilet
(http://dealmeida.net/en/Projects/PyTextile/greasemonkey_and_textile.html)
and submit the output to drupal docs.

Whatever is decided, I think that the productive and more interesting
discussion to be having is "what do our standards and conventions for
drupal docs look like?" rather than "what input language do we use to
create valid markup?"

Hope this gets the discussion back on target....

Chris


On Thu, 17 Mar 2005 06:51:20 -0500, Moshe Weitzman <weitzman at tejasa.com> wrote:

> I understand the resistance to Markdown and friends, but I am not
> hearing viable alternative proposals. If we don't enforce validity at
> authoring time, we will get tag soup just like our current handbook.
> Ensuring validity is really the minimum we should do - ensuring
> consistency would be even better.
>