re: Dick's guidelines

[chapman@aitg.enet.dec.com]

I'm sorry to say that I'm not pleased at all with your message.
Your comments, although they sound well-founded to a person who 
hasn't done much thinking about most of them, are the result of a 
few weeks' worth of thought about what should go into this book
and how the information should be imparted. Your general guidelines
about specification writing were correct, but obvious to anyone
who has ever written a spec, so why did you bother to write them?

The only thing I can conclude from your message is that you would
like to take over writing the standard, because you can't possibly
think that I will have the time or inclination to proliferate your
style throughout the rest of the document (which turns out to be
most of the document). There is too much else to do. 

I like to be objective, take criticism in the light in which it
was intended, and move on. In this case, I have to analyze the
source of the criticism and object to the validity of the
recommendations. I will be contacting the other members of the
drafting committee to get their points of view and will act
according to group consensus. Meanwhile, I doubt I will be sending
out anything to X3J13 as promised. 


>6. Do not use Common Lisp function names as verbs. Say this:
> 
>``The file produced by {\function compile-file} can be loaded into
>Lisp.''
> 
>Or say this:
> 
>``The file produced by {\function compile-file} can be loaded by using
>{\function load} into Lisp.''
> 
>Don't say this:
> 
>``The file produced by {\function compile-file} can be {\function
>load}ed into Lisp.''
This is a method of imparting information. "load" is not a word
that means the same everywhere. Used as an English word, it doesn't
have the semantics associated with the "load" we describe in this
standard. 
 
>Plain English is the language we assume the reader understands. We are
>describing Common Lisp using this language plus a little computer
>science and mathematics. In a formal semantics we could use part of
>Common Lisp to define the rest, but even so we would not invent words
>like SETQ as an English verb.
This advice would be fine if Lisp itself didn't redefine so much
plain English. Using Lisp terms in plain English is plain confusing.
 
>7. Try not to start a sentence with a Common Lisp function name. Try
>to qualify each Common Lisp name with its type, as in:
> 
>``The function {\function load} can be used to load a file produced by
>{\function compile-file}.''
> 
>This provides a lot of local information without a lot of words.
This is style. It imparts little information and there's a big
chance that the wrong words will be attached to a function name
by accident (e.g. The special form "load") that would be much
more confusing than just not saying anything. 
 
>8. Don't give advice to users. This might seem like a heartless thing
>to say, but the specification is a statement of what the language
>does. What users should do depends on the implementation, the software
>organization within which the user operates, the culture, and other
>factors. Stating advice is a guess that that advice will be true under
>all conditions. If you stick to the facts about the effect of
>language constructs, you cannot misguess.
I don't think this can be a hard and fast rule. The advice should
never be part of the "Description" section.
 
>9. Don't make claims that might be false. Do not say that compiled
>code is faster than interpreted code. Don't say that compiled code
>probably will be faster than interpreted code. Don't say some sort of
>error will probably be signaled. Don't state that something will
>typically be done. State what will happen or be true in all
>implementations (those things that will be true because the
>specification states they will be). In fact, don't make any claims at
>all beyond the semantics of Common Lisp.
In the error terminology, we have a "might signal an error". 
 
>10. Don't provide implementation advice. You might be tempted to want
>to talk about great new techniques or something not obvious. But
>someday this advice will be passe. Providing implementation details
>might confuse someone into believing that the semantics follows
>what the implementation advice states.
Same as  #9.


 From #11 on down, it seemed as if you were lecturing me on the proper
way to do things in a specification. My first comment about that is
that I have been working on and thinking about this document totally
for 2 years. If you had said these things 2 years ago, or even a 
year ago, it would've made more sense to me. But now you suddenly 
have the time/incentive to review this document and you feel you
can impose your style in ways that will cause the entire document
(most of which you haven't seen yet) to change. Which brings me
to my second comment: I don't have the time nor intention to make
most of the changes you suggest. It distresses me to even say that,
it infuriates me that I have been put in the position of having to
say it after all this time. You have attended most of the editorial
committee meetings, you have been given drafts starting in 3/88,
why have you waited so long to say anything? I expressed to you and
others many times that I first and foremost didn't want to be wasting
my time and the time of others by taking the wrong approach. If you
succeed in making the style of this book conform to your personal
needs, I will have wasted about a year's worth of time. 

I am the first to agree that a lot more work needs to be done, but
I am MUCH MORE WORRIED about technical consistency and accuracy than
typesetting, for example, at this point. 


At this point I don't know what to do. Your ISO document doesn't look
like the rest of the standard so something will have to change. As I
said, I have a long list of things to change, and the list doesn't
include your style preferences. I have been reassigned and will therefore
only be doing this job when there's available time. I feel now that 
no change or decision I make is safe, and will therefore be very reluctant
to waste my time on the standard. 

kathy