Dick's guidelines

[<masinter@arisia.xerox.com>]

I read Dick's message as some guidelines on how to rewrite stuff that
got added recently -- cleanup issues, the condition system, the new
glossary, etc. I didn't read it as a criticism of you. It seemed like
these were principles that you mainly had followed. There only seem to
be a couple of important areas where you seem to differ (there doesn't
seem much leverage in arguing whether we use 'plain english', is
there?)  I think the issue is that if anybody else writes something
for you, we should agree on style guidelines. Right? Dick produced
some, and you have some disagreements about it. I think most of his
advice is of the form of "things to take out to improve technical
consistency and accuracy." If we're worried about technical
consistency and accuracy, we can help out a bit by removing
implementation advice that may be incorrect, at odds with changes in
the semantics; we can remove 'advice to users' that might be incorrect
or incompatible. We can improve technical accuracy by disambiguating
whether we mean "some process which resembles LOAD" from "the actual
call to the function LOAD". I think Dick is trying to help achieve the
goals you want to accomplish "technical consistency and accuracy".
Maybe he needs to be more suave about it.  Think of Dick's list as
"things for reviewers to keep in mind." Does it give too much
implementation advice that might be outdated? Lets take it out. Do we
describe in great detail how a user might use a construct, with style
guides? Maybe we should take it out, especially if it would shorten
the standard some.

Right?

Larry

- - - - - - - - - - - -
6> "Do not use Common Lisp function names as verbs...."

I think that using Lisp functions as verbs is a little bit too cute
and it is probably a good idea to avoid it, but it isn't a big deal.

7> Try not to start a sentence with a Common Lisp function name...

I like reading "The function LOAD can be used ..." better than reading
"LOAD can be used ..." where there's even the slightest possibility
that someone might think "The property LOAD can be used..." or "The
variable LOAD can be used ...." or "The EVAL-WHEN tag LOAD can be used
..."

8> "Don't give advice to users..."
>> I don't think this can be a hard and fast rule...

I don't think any of these rules are "hard and fast", are they? 
Seems like good advice, though. Is there any particular instance where
you and Dick disagree about 'advice to users'?

9> "Don't make claims that might be false..."
This seems like good general advice, and there are a couple of
exceptions, like "might be signalled". Its a good thing to keep in
mind when reviewing the standard, though.

10> "Don't provide implementation advice...."

Your response was "Same as #9", but I'm not sure how it applies.
Clearly there are some cases where we've been unable to describe
things except in terms of a reference implementation, and other places
where we've been unable to describe how someone might use something
('what's this for, anyway?') without some description about possible
implementations. Again, a good thing to keep in mind when reviewing.