[Doc-SIG] SGML Python docs

[John Skaller]

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