[Doc-SIG] Python docs in reST

[Fred L. Drake, Jr.]

On Thursday 26 May 2005 17:10, Skip Montanaro wrote:
 > I'm not convinced we actually need to change markup systems either.  My
 > suggestion that perhaps migrating to reST was motivated by:
 >
 >     * my dread (real or imagined) that trying to coax different output
 > from latex2html would be a big PITA

LaTeX2HTML can be a pain to extend, but it's doable, and we generally don't 
need to do much that isn't Python-specific.  When we do, it's generally 
because we want to make it easier to affect the presentation in a systematic 
and cross-browser way (rather than rely on advanced CSS implementations).

 >     * a perhaps invalid assumption that reST-as-input would generate more
 >       documentation contributions based upon the occasional comment I've
 >       seen over the years that (paraphrasing), "I can't contribute - I
 > don't know how to use LaTeX."

That comes from people looking for excuses; most people who ask for ways to 
contribute don't follow up, and I'm very careful to point out that the use of 
LaTeX is not required.

 > I'm personally comfortable with LaTeX.  Fred has yet to complain about my
 > markup errors, so if we can find other ways to address the above
 > problems/perceptions, I'd actually be happy to keep LaTeX.

I think most of the actually limitations of LaTeX aren't that important.  If 
we could make a few changes, it would be nice, but there isn't anything 
pressing that needs to be changed.  There are enough things that we simply 
don't yet deal with.


  -Fred

-- 
Fred L. Drake, Jr.   <fdrake at acm.org>