re: Dick's guidelines

[Dick Gabriel <RPG@SAIL.Stanford.EDU>]

[In reply to message from chapman@aitg.enet.dec.com sent 31 Jul 89 03:41.]

Au contraire.  You misunderstand all.

First, my qualifications:

1. I worked for nearly 2 years on the CLOS specification, which is part of
this document. During that time I thought long and hard about what a
specification is.  I have spent virtually every working (almost = every
waking moment) working on this specification since June 1.

2. I publish 10-20 papers per year, and have been for more than 5 years. I
am frequently called upon to write committee reports. I have been
practicing and studying the craft, art, and profession of writing,
particularly, but limited to, technical writing, for 20 years.  I think my
thoughts are a little more than the accumulated wisdom of two weeks.

Second, what was this message intended to be.

I changed a lot of material written by people other than those on this
committee. You will all see that material soon. I wanted you to know what
I was thinking when I made those changes. If we all agreed that these were
good guidelines, then there would be less flack later on.

Kathy, the only 2 things that you do that are contrary to my guidelines
are to accidentally mistypeset some things and to use Lisp names as words.
I changed the typesetting problems as I came across them using Emacs
macros I have, and I did not touch a single instance of the use of Lisp
names as words.  I changed hardly one word in the function pages, except
to comment out those things you marked as ``to be deleted,'' and to fix
one or two technical errors.  On typesetting, having learned what I know
about typesetting from Knuth, I tend to be picky about it. He teaches that
carelessness in typeseting in this day and age indicates carelessness in
thought. Being much more worried about technical correctness does not mean
that one ignores typesetting.

Using Lisp names as words is so pervasive that we cannot realistically
change that unless there is a mandate to spend the time. If you read the
CLOS material, you will see that we rarely used Lisp names as words, and
the original document never started a sentence with a Lisp name. I doubt
anyone was particularly confused by the discrepancy between Lisp names and
the English phrases we used.

If you didn't like that document, then you shouldn't have agreed to
let me work on this one.

If the message was to lecture anyone, it was to lecture the various people
whose prose we are including via the cleanups and other such material.
Those writeups are full of random debates and rambling, and I think we
have to tighten them up.  I spent almost all my time rewriting 5.1
(because KMP's style, I hate to say it, is like a random walk. He has an
excellent textbook style and lecture style, but he is not in his element
here.) and chapter 4.  Section 4.2 required several weeks because Sandra,
bless her heart otherwise, did not manage to make clear which environments
were used where, and what the relationships are between them. Moon helped
work that out, because I wasn't sure what the story was.  Section 4.1 only
needed a little straightening of its presentation, which is left largely
as it was.

(If you think the ISO document is much different from the X3J13 document
you submitted to me, you must be horrendously mistaken about how
effectively I work. At several points I was working at the rate of 1
paragraph per hour.)

My message was simply a set of notes I made to myself as I worked on the
document to show you all what things I either tended to repair or that I
would like to see done.

Now, I really don't care whether anyone likes my writing style or
guidelines.  It all boils down to a free market:  If you honestly think
that chapter 4 and the section on conditions were better off before I
worked on them, feel free to revert back.

Why didn't I complain in March of 1988?

There was nothing to complain about then and there is nothing to
complain about now, except for the influx of odd material from the
cleanups, which is of variable quality.

Now, on to the point.

Not only do I not want to take over this document, but I was hoping to bow
out at this point. I tried to make the sections I worked on as close as I
could to what I think a specification should be, and now you (all) can do
one of three things: make the rest of the document like them, make them
like the rest of the document, make everything as different as you like.

				-rpg-