On 5/22/05, Skip Montanaro <[EMAIL PROTECTED]> wrote: > >>>>> "Ian" == Ian Bicking <[EMAIL PROTECTED]> writes: > It's not like this is a new problem, is it? It seems to me we should be > able to come up with a reasonable set of requirements and a design that > addresses them. I'd like to avoid hacks that require we deal with HTML as > an input format.
I agree.... talking about doing "hacks" when we're talking about replacing something like LaTeX does not sound very appropriate to me... LaTeX is a very powerful program. I think we need to enumerate the problems that we're having with it now that makes people want to move away from it (apart from the "it's not an all-python solution" idea). In other words, to answer these two questions clearly: 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. 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 macros being used in the LaTeX sources used for the Python docs (which are themselves reasonably well documented and for which ample examples are available) I have to wonder about their capacity to contribute readable prose to the documentation.) 2. what is the precise list of features that are offered in the current documentation system (excluding all the LaTeX features that it is not using) and how can we replace all of them with the new system (docutils or otherwise)? (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.) cheers, _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
