Hallöchen! "Fred L. Drake, Jr." <[EMAIL PROTECTED]> writes:
> On Thursday 26 May 2005 18:09, Torsten Bronger wrote: > > [...] > >> I have thorough experiences with XML (http://tbook.sf.net), and I > > That site appears to be down at the moment. Well, I misspelt it: tbookdtd.sf.net. At the moment it's only XML, so I'm looking for a human-friendly input format. I've evaluated many Wiki formats, but reST is the most promising so far. >> think that it's the best way to archive and to process >> documentation. Since you can't (well, don't want to) input it >> directly, something like reST with an XML backend -- among others >> -- is the way to go, in my opinion. > > It's not clear to me that you really want an extra front-end to > hide what's happening. Writing in ReST only makes sense if ReST > sufficiently reflects the data model. In the current situation I don't see a reliable way to get to XML. Even if you don't use XML in the typical workflow, its possibility alone assures flexibility and reusability. It's just so drop-dead simple to do all this with XML. One month ago I completed a texi2latex converter in XSLT, which covers more spec features than the original processor(!) with only 120kB of source code (and XSLT is verbouse). For our students newspaper, I use wiki --> XHTML --> LaTeX with great ease. Our authors come from all faculties and are mostly Word users, but with this system they submit ready-to-use articles. (Wiki --> XHTML is done with Python, of course. ;) Theoretically, you *can* achieve this also with an appropriately constrained LaTeX, therefore my question about a well-defined subset. LaTeX becomes really nasty not until you use more than ASCII, which is rare in computer documentation. However, for this way there must be a real "Python doc" LaTeX with an explicit specification. > [...] > >> Even if for really complex projects the reST source becomes >> somewhat cluttered, too, it can be an efficient replacement for >> LaTeX docs. It contains so many clever tricks to keep the "plain >> text" appearance that I'm optimistic that the rest can be added >> rather nicely, too. > > I'm skeptical. If the actual data model is hidden, what I suspect > will happen is that more documentation will be written with the > presentational layer in mind and the logical markup skipped ("it's > supposed to be italic, right?"); This definitely is a problem with the current reST, however, I think it's solvable. There is a finite number of typical text patterns in computer docs, and the reST standard must give you the canonical way to write them. At the moment, the format is a little bit wishy-washy, and the specification even more so. For some things there doesn't seem to be a data model yet. Maybe reST should be designed not so much as something with an XML backend, but as a frontend to an XML format one has agreed upon in the first place. You're right agree that a documentation format is only useful if it delivers logical markup, and this would be a step towards it. I admit that a certain amount of implicit behaviour will always be necessary (aka magic). However, I find this desirable, because often you have to make things clear to LaTeX that the doc processor could and should figure out itself. This may be a matter of taste, though. Tschö, Torsten. -- Torsten Bronger, aquisgrana, europa vetus _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
