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. _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
