[Doc-SIG] SGML Python docs

[John Skaller]

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