At 17:10 8/09/98 -0400, Fred L. Drake wrote:
I don't think this is a "pet format" issue;
Actually, I think it is. There are a lot of formats around, and all have advantages and disadvantages. The biggest advantage for any one author is probably familiarity. The biggest advantage for clients is availability of and familiarity with processing tools. This is not to say there are not _technical_ advantages to different approaches. See below.
there are advantages to SGML/XML conversion, once there's a specific DTD and the SGML v. XML decision is made (it's not at all clear which to use). There are also advantages to *not* performing a conversion, primarily that the time saved can be used to actually improve the content of the documentation.
To demonstrate what I mean: my prefered format is 'interscript'. The 'reason' is that I believe in literate programming, but the_real_ reason is that I'm familiar with it and can adapt it to do what I want because I'm the author of it :-) Interscript has decisive 'technical' advantages over all the other formats. For a start, it can generate the lot, automatically, so it subsumes them all. Secondly, it can generate Python, so it is most likely to be used and maintained by program authors, alieviating the current problem of lots of undocumented modules, or, worse, incorrectly documented modules. There are two technical disadvantages -- interscript is new and unstable, and, it would be a fair amount of work to merge the existing documentation with the existing code. The 'real' disadvantage of course is familiarity and availability. I'm not trying to argue for interscript format, I'm trying to explain that the _real_ issue truly is 'pet' formats and that will not be put aside easily by any amount of technical argument. There's work involved, to be done by volunteers. The 'pet' format issue is not only real -- but valid. ------------------------------------------------------- John Skaller email: skaller@maxtal.com.au http://www.maxtal.com.au/~skaller phone: 61-2-96600850 snail: 10/1 Toxteth Rd, Glebe NSW 2037, Australia
John Skaller writes:
Actually, I think it is. There are a lot of formats around, and all have advantages and disadvantages. The biggest advantage for any one author is probably familiarity. The biggest advantage
My understanding of your statement that precipitated this was that you thought "we" (prob. meaning Guido & I) were using the formats we're using (LaTeX) simply because that's what we like. I don't know what went into the original decision to use LaTeX, but I expect it included the issue of availability. I've continued to use it in part because there's a lot of documentation on TeX/LaTeX (both free on the web and published in books), because I know it (*not* because I like it -- I'm quite ambivilant), because it's free, and because I can make it do pretty much everything we need it to do. When that last item is no longer true, I will not hesitate to switch formats to something that will do what we want it to do.
Interscript has decisive 'technical' advantages over all the other formats. For a start, it can generate the lot, automatically, so it subsumes them all.
I'm not at all convinced that this is a benefit, but that can be reasonably debated either way. Documenting that something is not yet documented (which seems the only real option when there isn't documentation) does not seem valuable, and can be distracting.
by program authors, alieviating the current problem of lots of undocumented modules, or, worse, incorrectly documented modules.
The problem of undocumented modules can only be fixed by someone writing documentation. Whether the documentation is embedded in the module or encoded in a separate file (as LaTeX, SGML, XML, or whatever) is a minor technical issue. The problem of incorrect documentation doesn't go away. Perhaps it becomes easier to keep the documentation up to date, but it will never be "free", so documentation will not follow implementation in lock-step. This is not a technical issue so much as a human issue; we are limited and so is our time. (Is this a bug or a feature of time? Careful; trick question!) -Fred -- Fred L. Drake, Jr. <fdrake@acm.org> Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191
participants (2)
-
Fred L. Drake -
John Skaller