[Python-Dev] status of development documentation

[Phillip J. Eby]

At 01:40 AM 12/22/2005 +0100, Martin v. Löwis wrote:
>Phillip J. Eby wrote:
> > 1. Fredrik doesn't want to have to install a LaTeX toolchain in order to
> > get an HTML version of the documentation
> >
> > 2. Fredrik likes using whatever tools he has for editing HTML better than
> > whatever he has for editing LaTeX
> >
> > 3. Fredrik believes that more people would participate in updating Python
> > documentation if it didn't require a LaTeX toolchain or LaTeX-friendly 
> editor.
> >
> > (Of course, these are equally arguments for using other formats besides
> > HTML, especially formats that are closer to plain text.)
>
>Except, of course, for any other format (than HTML), you would have to
>substitute "Fredrik" by somebody promoting that other format.

To be clear: I don't advocate a switch; I'm okay with the current tools, 
since I have managed to get LaTeX to work on both Cygwin and Linux, which 
is enough for my needs.  I'm endeavoring only to point out that the 
arguments being advanced for HTML seem shaky to me.


> > By the way, I'm not sure I see what the problem with authoring Python
> > documentation with reST would be.
>
>Really not? How do we get from where we are to where you would like
>us to be?

Again, I'm not advocating a switch.  I'm only questioning the statements 
people have brought up about reST not being adequate.  I'm curious to know 
what features are lacking, and whether this is an accurate assessment or 
just a general impression.  If there are specific issues with reST, it 
would be good to know what they are.


>With this, I mean both technically (but perhaps I'm unaware
>of some tool that does the conversion automatically and lossless)
>and emotionally (but perhaps everybody but Fredrik and Barry could agree
>to switch to reST).

I don't advocate a switch, for precisely the reasons you are bringing up 
here.  Fredrik is the one advocating a switch.  If there *is* to be a 
switch, however, I would advocate that reST be the format in the absence of 
compelling reasons otherwise.

Since Barry and I think one other person mentioned issues with reST, I 
would like to know what they are.  I don't think it's appropriate to have a 
"reST isn't adequate" meme being propagated without some definition of 
*how* it is considered inadequate, such as what features are missing or 
what misfeatures are present.  This would be helpful for the docutils team, 
I'm sure, and in any case in the event there was a PEP to decide on a new 
format, it would need to specifically address any rationale for why reST 
should *not* be used.

And I'm personally just curious as well.  I've done some fairly substantive 
work in both the existing LaTeX-based tools:

http://svn.eby-sarna.com/*checkout*/PyProtocols/docs/ref/libprotocols.tex?rev=184&content-type=text%2Fplain

and using reST:

http://svn.python.org/projects/sandbox/trunk/setuptools/setuptools.txt

And I didn't encounter any deficiencies of reST, so I'm genuinely curious 
to know what it is I'm missing.  It's true that the simplest standalone 
reST tools don't support very sophisticated indexing, but I had the 
impression that the more advanced tools (and certainly the docutils 
libraries themselves) had considerable flexibility in this regard.

If someone has examples of actual "Pythondoc" markup that don't translate 
to reST, I'd be really interested in seeing them, just for my own 
education.  Of course, I'd also be curious how common such constructs are.