[Doc-SIG] RE: Doc-SIG digest, Vol 1 #145 - 4 msgs

[Ken Manheimer]

Ping wrote:

> Remember the old adage that says that every math equation in a book
> will cut its readership in half?  Well, imagine something similar --
> every additional syntactic construct or tag will cut the *writership*
> in half (or some fraction).  Even though more tags may mean more

I think this is a brilliant way to frame it.

> expressive power, it also means a more difficult choice to make every
> time one uses a tag -- beyond a certain point it becomes debatable
> which tag is the correct one to use, and then all is lost.  Also, the
> more complex the system becomes, the less predictable the failure
modes
> will be -- till we get to the point you have to debug docstrings
(eek!).

I believe that jim did an extremely good job balancing these concerns
with structured text - i had the impression that david ascher came to
see this, too, when he was looking at alternatives and came back to
structured text.  Moshe makes the point that it's hard to reason about
structured text.  I happen to be sympathetic with this point of view - i
would be reluctant to implement a system myself, because i'd be afraid
of tangling myself in ambiguities that i couldn't resolve for people
writing text or extending the text processing code.  However that
doesn't mean that what jim implemented suffers from this, or that it
can't be rectified where it does!

I guess the upshot is that i think it would be worthwhile investigating
whether moshe's concerns - which i take to be having rigorous,
predictable rules - could be satisfied with structured text, rather than
taking a different path that suffers from the things to which eddy,
ping, and others (me, include) object.

(I don't know whether it was deliberate or not, but i note that both
eddy and ping's messages had the right (or trivially-near right)
bullets/emphasis/etc formatting for correct interpretation by
StructuredText.)

> (The attached example is generated from SocketServer.py as distributed
> with Python 1.5 -- nothing has been edited.)

I'm unable to read the example because i get this list in digest form.
(My fault, sorta, for not fixing this in mailman's MIME handling in
digests when i was working on it...)

Ken
klm@digicool.com