Documenting our decisions

["Scott E. Fahlman" <Fahlman@C.CS.CMU.EDU>]

I'm not sure that a standard doc has to be very different from a manual,
if the manual is written with sufficient fanaticism.  The Steele manual
has been serving us as a de facto spec for awhile now, and it has been
OK for that purpose, if not great.  Almost all of the ambiguities are
due to failures on our part to think issues things through and to notice
problems, and not due to the style of presentation.  It certainly would
make writing a spec easier if the online text of the Steele book were
available for cannibalization and not legally encumbered.  The Lucid
book might serve us just as well in that capacity, except that its text
has not been debugged by the scrutiny of hundreds of users.  We will
see.

I agree that we don't want to let text formatting become a big thing in
this effort, at least until the real work is done.  But a well-formatted
document with section numbers and an index can be a big help as we go
along.

We obviously don't have the resources to write a formal, 100%
unambiguous language spec.  As far as I know, there has never been such
a thing, even for languages much less complex than Lisp.  But I think
that if we have a reasonably complete and correct manual to start from,
we'll be able to put together a langauge spec that has many fewer holes
than the original manual, which itself is pretty good except in areas
where all of us were confused or just gave up.  Remember that the
original manual was written at a time when there was no implementation
experience with many parts of the language; now we've got the benefit of
some experience, and therefore a much better idea of what things can be
tied down and what things have to be left to implementors.  And we
probably won't specify anything that's unimplementable this time.

We could try to write an add-on to the original book, but I think that
this would not be an acceptable form for the standard in the end, and
rewriting could introduce a bunch of new bugs.  We're much more likely
to get it right if, at any given time, there's a complete manual
reflecting current truth.

The Europeans think that the best way to build an unambiguous spec is to
define a small kernel as precisely as possible, and then to specify the
rest of the language in terms of that -- by providing example code
implementing the rest of the langauge, I guess.  That's a lot of work
too, and has its own set of problems: it's hard to specify just what
elements of the example code are meant to be essential and which can be
changed at the implementor's option.  So unless all systems actually use
the example code, you get big problems.  I think that a manual is at
least as likely to be unambiguous.

-- Scott