Documenting our decisions

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

It seems to me that we want to focus on the production of a coherent,
complete document for ANSI Common Lisp (maybe later to be ISO Common
Lisp).  We can't really expect the community to rally around the
existing Digital Press book plus a long list of corrections and a couple
of new chapters.  Nor are we likely to find as many of the problems and
inconsistencies if we just handle each problem as an isolated issue.
Our most productive periods in developing this language were when we
were trying to hammer out large sections of the book to meet a deadline.

I don't think that a new edition of the Steele book will do the job.
Digital Press has been reasonably cooperative so far, but I doubt that
they will give up their copyright, and we just cannot produce a document
for the Common Lisp standard that says "Copyright Digital Press" on it.
If that book were in the public domain, we could use its actual text as
a starting point, but I don't see this happening.  So it looks like we
have to develop a new document.  Of course, the Common Lisp it describes
will be very similar to the Common Lisp described in Steele.

Ideally, there should be two documents, both kept online in some form
that most people can easily FTP and print (TeX?), and both kept up to
date as each decision is made.  One of these documents would be the
manual documenting the proposed standard; the other would be a list of
all the deliberate incompatible changes that we have made to the
language as described in the original silver book.  When we're done, the
former is our report to ANSI; the latter is a guide for all the
companies that need to update their implementations and all the users
who need to fix things in their code.  The standard document needs to be
as clear and unambiguous as we can make it; it does NOT necessarily need
to be organized a a tutorial or as a convenient manual for the working
programmer, nor does it need to be subtly witty.  There will presumably
be a lively market for other Common Lisp books, including the
second edition of Steele, that will fill those needs, but the new
document should become the definitive language standard.

These documents should either be public-domain or they should be
copyrighted by someone not associated with a manufacturer.  If
copyrighted, there should be explicit blanket permission for anyone to
reproduce the document without charge, as long as the text is reproduced
in its entirety and any additions to the text are clearly marked as
such.  [Question: is a public-domain document acceptable to ANSI and
ISO, or do they require the ability to copyright the thing for
themselves?  After being burned once, I'm not too keen on working on
this thing and yielding up the copyright to ANYONE.]

Several times in the last few months I have come close to volunteering
to write a new, public-domain manual meeting the above conditions and to
keep it online here at CMU.  This impulse arose out of frustration at
seeing issues be almost settled and then unravel again.  Each time I've
thought about this, I've come to my senses.  Writing a new manual from
scratch is more work than I am prepared to do in the next year.  But
Gabriel tells me that Lucid has written a new manual, equivalent in
content but not in form to the Steele book, and therefore free of the
Digital Press copyright.  He also says that Lucid might be willing to
put the sources for this document in the public domain to serve as a
starting point for the new specification.

I haven't seen this new manual yet, but if it's in good shape and if we
can indeed arrange to use it without awkward restrictions, I will
probably volunteer to hammer it into a spec and to keep it up to date
(with a little help from my friends at CMU and, I hope, from all of
you).  It would be kept online and freely FTP'able at CMU.  We will not
get into the hardcopy business, but maybe ISI can do that, charging
enough for copies to recoup the costs or maybe some company will decide
to crank these out quickly and cheaply.

The model would be that I get this into some initial kind of shape while
the rest of you debate the issues currently on the table.  Maybe some of
the rest of you can work on particular sections.  Once the document is
presentable and in line with current truth, we make a few passes through
it, chapter by chapter, debating and fixing problems and ambiguities as
we find them.  Once we're happy, we ship it up to X3J13.

If anyone has a different model of how to do this, please speak up.  If
there's anyone else out there who would like to do this, I'd be happy to
step aside or would be willing to help carry some part of the load.  But
please don't volunteer unless you're really serious about doing this.
If we end up with a big backlog of changes to go in, things rot quickly.

Please note: I said I MIGHT volunteer for this, and that sentence had a
couple of "if's" in it.

-- Scott