[Python-Dev] status of development documentation

[Nick Coghlan]

Facundo Batista wrote:
> 2005/12/21, Phillip J. Eby <pje at telecommunity.com>:
> 
>> 3. Fredrik believes that more people would participate in updating Python
>> documentation if it didn't require a LaTeX toolchain or LaTeX-friendly editor.
> 
> I'm sure he's right. I'm not talking about any random user that finds
> a doc bug and wants to generate a patch, here I'm talking of my own
> experience:
> 
> I had to correct a few lines in the almost perfect documentation that
> Raymond generated for Decimal. I fighted with my Linux (at that time,
> FC1) to be able to compile the docs, and couldn't do it.
> 
> I ended touching the XML by hand. It worked, but
> 
>   a) Took some time.
>   b) Wasn't really sure that it was well corrected.
> 
> So, I really think that a more human friendly format will help here.
> 
> What I do NOT know, if the effort of converting the whole docs to
> another format is worth it, and that effort should be deviated to
> something that will help more other users to help with docs (for
> example, that the official docs could be annotatted, a la MySQL (AMK
> did something like this, right?)).

If I remember rightly, the biggest problem I had in the whole exercise was 
getting latex2html to run - I actually had to modify the Perl source to get it 
to work (fortunately, I didn't have to try to *understand* said source first - 
other people had already figured out the necessary incantations, so I was able 
to find out how to fix it via a Google search).

latex/tex weren't a big problem, because they were in the distro archives - 
but latex2html was a definite pain.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia
---------------------------------------------------------------
             http://www.boredomandlaziness.org