At 11:03 9/09/98 -0400, Fred L. Drake wrote:

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.

In some sense .. that's a necessary truth. :-)

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.

But it produces paper! Today, we want Web enabled documents. Do you know anyone that has a paper copy of the docs?? I don't. I never will, either.

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.

It's no longer true. See above. Paper isn't useless: but it isn't the first use media for free software. IMHO.

...

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.

The point is that to generate the module at all it _has_ to be converted to interscript and given a heading. That leaves annotating the code and adding user doco, which is the _easy_ part even though it reqiures more work -- it can be updated by users with patches and contributions. BOTH the software and doco.

...

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.

I disagree, very strongly. The whole point of literate programming is to put the code and docs together in a single file so they can be maintained together. Donald Knuth agrees with me. :-) ------------------------------------------------------- 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