[Doc-SIG] DocStrings 0.3: Suggestion for documentation syntax (very long)

[Moshe Zadka]

David, sorry to pick on you, but this will be a rather collective answer.

On Fri, 4 Feb 2000, David Ascher wrote:

> not, etc. etc., but I don't think that Fred learned anything that he didn't
> know before.

I agree. It was a bit pointless.

> FWIW, I am tentatively opposed to Moshe's proposal, the tentatively because
> I haven't had a chance to give his proposal a fair look.  The 'look and
> feel' of the markup, however, doesn't sit well with me.  I will do a more
> serious critique in the next few days.

Great! 

> Moshe, could you step back a little and explain why we should undo the
> relative agreement we'd established (IMO) before IPC8?

Well, I certainly seemed to steer enough negative feelings!

For one thing "I didn't know we had one". For another thing, my proposal
had one thing no other proposal I know of had: a clear definition of the
driving forces behind it. Now, one thing I would like to know is whether
it was bad design (my goals were wrong) or bad implementation (my proposal
didn't meet those goals). I must say that no-one seemed to give it as
much as a chance -- that is, re-write one docstring in it.

As to Greg's objection, well, I can certainly live with something which
"guesses" what the words mean based on some delimiters. I'm doubtful that
I could write it, and I'm even skeptic that anyone will do a good enough
job that it will replace the semantic markup completely, but we can give
it a try. 

In short, what I want (and I think deserve) is more then people saying
"Yuck!" -- I want to see if version 0.4 can be better. 

If people think my proposal is so horrible it can never be fixed, then
if someone could show an alternative proposal, it would do us all some
good.

crushed-by-the-multitudes-ly y'rs, Z.
--
Moshe Zadka <mzadka@geocities.com>. 
INTERNET: Learn what you know.
Share what you don't.