On 12/21/05, Barry Warsaw <[EMAIL PROTECTED]> wrote: > On Wed, 2005-12-21 at 20:36 +0100, Fredrik Lundh wrote: > > > I'm not really interested in optimizing for you, I'm interested in > > optimizing > > for everyone else. They already know HTML. They don't know ReST, and > > I doubt they care about it (how many blogs accept ReST for comments?) > > Sorry, but HTML and (even more so) XML are not human-writable. :) Yeah, > we can all do the simple stuff, but I absolutely hate authoring in HTML, > and it would be a nightmare if the documentation production system > didn't handle lots and lots of magic for you (like weaving in the right > footers, css, etc. -- oh wait, that's ht2html!). > > reST is a fine language but it seems more suitable to simpler linear > documents like wiki pages and PEPs, rather than those with complicated > nested structure. > > Maybe it's just because I came in late on this thread, but what exactly > is broken about the current LaTeX documentation? > > -Barry
Good point. Nothing is really "broken", but it's just not flexible because there is no way to get a solid document model from LaTeX to do some conversion and processing on. i.e. you convert from LaTeX direct to the output. Having the intermediate representation would allow generating nicer output, and in more formats, without necessarily having to reparse the input everytime either. What we need is not necessarily a change of syntax: the problem is not the input, it's the conversion. The input is fine--if someone can't learn the super simple LaTeX macros for the Python docs, I don't want to imagine what kind of prose they would come up with. LaTeX is NOT hard, at least if you limit yourself to the stuff you need to document Python code. About ReST: Somehow there is a recurrent stream of people--include me at some point-- who think that ReST could express any document structure for any task, and that if we use that we will be happy ever after. ReST does an amazing job of inferring generic document structures from text, but for documenting source code, you really want to be able to say "This is a function", "this is an optional argument", etc. ReST does not provide this kind of functionality, and if you try to stretch the interpreted roles to do this you get an equally ugly syntax as LaTeX input (I would even argue that I prefer the LaTeX source). Also, ReST has many gotchas: if you will infer structures from invisible markup, it's very easy to make mistakes, and there are many cases where it's not clear what the parsed document will be like, you have to "learn" a lot of how it parses the documents, and the corner cases, by checking with rst2pseudoxml.py. I'm facing this problem with some of my Nabu extractors, which attempts to extract semantically meaningful chunks out of the docutils tree, for example, contact information. If there is a problem it is not the input, it's the toolchain and conversion. _______________________________________________ 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
