Documenting our decisions

[Daniel L. Weinreb <DLW@SCRC-QUABBIN.ARPA>]

I agree that the resulting text should be readable and sensible, and I
agree that we should not strive for a 100% unambiguous spec; we don't
want to end up with a Vienna Definition Language monster like the PL/I
definition.  I also agree that we can do a lot better now than we did
last time, partly because we know more about what we're doing.

However, there's another major reason for ambiguities besides the ones
you mentioned: interactions between features.  Yes, there are
declarations.  Yes, there are FLET and MACROLET.  Exactly how do the two
work together?  This isn't the greatest example, but I'm sure you know
what I mean.  I think that to clear up such problems, the manual will
have to get somewhat more rigorous, and it will probably be necessary to
introduce more terminology with strict definitions.

As was pointed out, the stricter it gets, the harder it is to make the
text flow smoothly and be easy to understand.  But I agree that we need
to err on the side of clarity and unambiguity, and keep the writing as
clear as we can in light of that.  There's no getting around the fact
that excellent technical writing is difficult.

You're right about the kernel definition.  To put it another way, a spec
written that way would be extremely constrictive, since you'd have to
imitate every single aspect of the behavior of the example code,
including its behavior on bad inputs, etc.  The Common Lisp spec
explicitly takes the attitude that it only specifies certain behavior,
and other things are termed "an error".  Sure, things would be more
portable and unambiguous if we didn't take that attitude, but it has
been our feeling that implementations would be forced into unacceptable
inefficiencies and compromises by such a strict spec.

Of course, now that we know more about implementations, we could
reconsider some of the "is an error" cases, and consider defining them.
However, given our agenda and priorities, I don't know whether it's
worth spending time on that in any significant number of cases.  We
could keep it in the backs of our minds, though.