[Doc-SIG] Python docs in reST

[Fred L. Drake, Jr.]

On Sunday 22 May 2005 14:39, Martin Blais wrote:
 > 1. why exactly do we want to change the documentation system?  what
 > are the problems with the current approach?  can it just be fixed with
 > the current system?  what would be the advantages of a new system?
 >
 > (I voiced some answers of this question in my previous inquiries,
 > namely, that there is currently no way to unify part of the docs from
 > the source, i.e. function descriptions should be in the source and
 > pulled into the manual sources automatically, to have one single
 > source for all "bits" of docs.

This would be very nice to have.  For the HTML presentation, there's no reason 
we can't add this and stick to LaTeX.  That'll be harder for the typeset 
presentations (though the value of that for the library reference is 
seriously questionable).

 > Other messages seem to suggest that LaTeX is too complicated for
 > contributors.  I personally disagree, but it may be a valid reason if
 > this is the case.  IMHO if someone can't be bothered to learn the 20

I think there's a strong feeling among many people that writing text is not 
itself programming, and that explicit (== "visible" for now) tagging is 
undesirable.  However, any community which handles large volumns of 
structured information eventually finds explicit structure is valuable.  
Thinking of text as less structured than program source is simply wrong; 
historically the "tagging" is simply not visible.

 > (Again, just my HO (and i'm just an observer more than anything else,
 > really), but I don't like the idea of replacing a source format to a
 > new system if the new system doesn't have at least all the features of
 > the old one.  As much as I enjoy working with docutils, it does not
 > seem to offer all that LaTeX and its multiple conversions has to offer
 > now.)

As I found when I started the LaTeX-to-XML conversion tool that's currently in 
the Python CVS, the level of effort to get 100% support is enormous.  There's 
a lot hiding in the use of these tools over the past many years, in spite of 
their shortcomings.


  -Fred

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