[Python-Dev] status of development documentation

[Phillip J. Eby]

At 08:36 PM 12/21/2005 +0100, Fredrik Lundh wrote:
>Josiah Carlson wrote:
>
> > > yeah, because using something that everyone else uses would of course
> > > not be the python way.
> >
> > No, because ReST is significantly easier to learn and use than basically
> > every other markup language I've gotten my hands on.
>
>I'm not really interested in optimizing for you, I'm interested in optimizing
>for everyone else.  They already know HTML.  They don't know ReST, and
>I doubt they care about it (how many blogs accept ReST for comments?)

I think you're asking the wrong question.  A better one is, how many blogs 
require valid HTML for comments, without offering any user-friendly bits 
like converting line feeds and paragraph breaks to BR and P for you?  How 
many blogs offer other humane formats like Textile and Markdown?  (Neither 
of which is very different from a stripped-down and underspecified version 
of reST.)

If anything, I'd think that the fact that blogs found it necessary to 
invent reST-like formats implies that far more people can deal with 
reST-like formats than with unadulterated HTML!

In addition to the syntaxes with names like Markdown and Textile and reST, 
I've seen lots of comment systems with their own primitive markups using 
similar approaches.  So, using the infrequent availability of one 
particular humane format in blogging comment software as an argument for 
HTML is missing the forest for the tree.  If you want to use blog comments 
as a test case, the evidence is overwhelming that people *don't* know HTML 
and/or find it hard to use.  Sure, they have to type it in a text box.  But 
you're the one who picked blog comments as an example.

In any case, blog comments rarely need the full expressiveness of 
reST.  You're not going to need section headings and intra-document links, 
file inclusion, footnotes, etc. in a blog comment, so it's natural that 
anybody inventing their own format is either going to try and make HTML 
more humane, or invent a reST-like mini-markup ala Textile or Markdown.