> >>By the way my vote is -1 on moving to html as the standard markup format > >>and +1 on working on docutils to turn that into an usable input format. > >>Additionally - having a wiki version, or a version that accepts user > >>commentary would be a very useful way of gathering additional > >>information. Of course someone has to maintain this... I think AMK did a > >>simple implementation of this a while ago - although it had usability > >>issues and the resulting data didn't seem to be used. I guess this is > >>all part of the ongoing discussion. > > > > > > There was a long and detailed discussion about using ReST as an input > > format for documentation a while ago. The consensus was that ReST > > does not allow sufficient markup for technical documentation, which is > > necessary for this kind of document. > > > > Doesn't currently - or can't ? I thought it was just the current state > that was a problem. I'd be disappointed if it was never likely to be > possible to create the python docs with reST.
Well, be disappointed. It does not currently, and most likely won't. As much as we all would like some kind of magic silver bullet text format that just "knows" what we mean and want to express, it is rather unlikely that ReST develops to become that for every kind of domain. ReST does a fair amount of *generic* structure inference, and that is its scope. The amount of ugly directives and markup being regularly proposed on the docutils mailing-list indicates that ReST may have already reached its potential in terms of automatically guessing structure from simple text files. Even if this is not the case, extending ReST to include keywords for functions, variables, classes, lists of arguments, etc. would render it into just an equally ugly form of input equivalent to the current LaTeX sources, ... and without the power of expression of TeX macros! You see, for the technical docs we NEED to indicate the nature of the identifiers, not just to render them consistently, but for generating indexes, and cross-references, and for plenty of fother reasons. You can't do that in ReST (well, the interpreted roles do take you part of the way, but not enough). At some point you have to tell the computer all the information that is in your head, and the ReST format simply does not stretch that far, and LaTeX is a great tool for this at the moment. What sucks now is the inflexibliity of the produced document: the tools to convert from the LaTeX sources to other formats are nothing short of wizardry (i.e. LaTeX2html). What would be great IMO is if we could obtain some kind of meaningful intermediate representation from the source, from which we could then generate various output formats (a bit like how docutils is structured). I saw some project like that a while ago, generating XML from LaTeX sources, never had time to check it out more seriously. cheers, _______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig
