HallÃchen! Bill Janssen <[EMAIL PROTECTED]> writes:
>> LaTeX seems to be a we-want-to-get-rid-of-it, and reST is still not >> really ready. > > I decided to do the documentation for my latest project, UpLib, in > reST, to see how well it works. My conclusion is that it probably > will never be ready to document Python, because the design goal of > making the reST source read like text conflicts with the goal of > making it functional enough to document a large system. I'm not so pessimistic. I think that only a few constructs are missing to make it suitable for large projects (inclusion and interlinks). But apparently this is already being tackled. For non-Python user guides I use Texinfo. What I really miss is Texinfo's @deffn for explaining functions etc. Yes, I know <http://docutils.sourceforge.net/docs/dev/semantics.html>, but it doesn't solve this issue. reST lacks a standard means of defining function/method signatures, return values, exceptions etc. (Similar structures are needed for classes.) I use field lists at the moment. That's okay, but it's not real logical markup since the reST interpreter has no chance to recognise it as a function definition. Besides, its pdf and HTML results are poor. Other missing things include standardised meta info, i18n (including encodings), formulae (a well-defined subset of LaTeX would be good), and a meta standard for how to use "interpreted text". > [...] > > [...] but next time I'll probably use a simple text markup > language like troff with an appropriate macro package, or better > yet runoff. Do you really think that troff is suitable for large, modern documentation? How many people would have to learn it? How easy is it to install it on Windows? How good are the PDFs generated from it? How is it converted to HTML? (I don't know troff very well, as you can see. ;) TschÃ, Torsten. -- Torsten Bronger, aquisgrana, europa vetus _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
