[Doc-SIG] Python docs in reST

Fred L. Drake, Jr. fdrake at acm.org
Thu May 26 23:45:50 CEST 2005

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 L. Drake, Jr.   <fdrake at acm.org>

More information about the Doc-SIG mailing list