[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Reviewer notes
Dear Reader,
This file contains my notes to help guide you in reading this draft.
The first thing you should know is that I still have a very long list of
things which I had wanted to finish before distributing this draft, so
don't assume if you see something broken in this draft that I must be
blind or stupid. That may in some cases be true, but more than likely
in many cases the problem was just a sheer lack of time. The document
is very big and it takes time for things to change. So far I'm trying
to make systematic changes of various kinds, so often I've preferred to
wholly eradicate a particular bug throughout the manual rather than to
work on some specific paragraph until it was perfect (although at some
point I plan to do some vanilla section by section, chapter by chapter
work as well).
Given that I do have a list of things not yet done, it's important that
you read carefully the information that follows in order that you not
spend your valuable review time on issues which are redundant with what
I would already be doing. If you are in any doubt about whether certain
classes of comments would be useful, please contact me privately and I'll
be happy to help.
I hope that some people will take some time review parts of this before
the upcoming meeting, but if you are not one of them, don't dispair. There
will be other drafts--and people do burn out after a certain number of
readings, so it won't hurt if a few people pass it up this time and
instead do it next time.
Internet KMP@Stony-Brook.SCRC.Symbolics.COM
Phone (617) 643-1530
==============================
Caveats
Don't use this document as a preferred reference for any implementation.
It probably isn't correct enough yet.
Don't distribute this document to people outside of X3J13.
It probably isn't presentable enough yet.
Don't assume that just because I've typeset this whole document, or
because there is evidence here and there that I have worked on a
section, that I have an overall belief that the section is correct. In
general, very few of these sections get my stamp of approval at this
time.
What to Review
Everyone should print out a copy of chap-0, which contains the table of
figures, table of contents, and an alphabetical index of all functions.
This is essential for being able to get around in any of the other
sections.
Everyone should print out a copy of the glossary. This terminology
information is not yet used consistently throughout, and in some cases
I know it to be used wrong, but it is still an important basis for even
trying to understand the rest of the document.
Beyond that, the sections are organized by topic and I suggest that
people should look at sections that are especially interested in or
that cover areas which they are particularly experienced with.
Hopefully that will be different for different people, so hopefully
we'll get good coverage. I'll be surprised if any single reviewer has
time to do a complete review between now and a March meeting.
Currently the chapters are the following:
0. Index (30 pages)
1. Scope, Organization, References, Defs, Compliance, Extensions (16 pages)
2. Types, Classes, Objects, etc. (82 pages)
3. Syntax (32 pages)
4. Evaluation and Compilation (42 pages)
5. Errors, I/O, Programming Env, Places, Notes about catalog (62 pages)
6. Types (14 pages)
7. (More) Evaluation and Compilation (48 pages)
8. Data and Control Flow (146 pages)
9. (More) Objects (76 pages)
10. Structures (20 pages)
11. Conditions (76 pages)
12. Symbols (22 pages)
13. Packages (40 pages)
14. Numbers (80 pages)
15. Characters (20 pages)
16. Conses (74 pages)
17. Arrays (50 pages)
18. Sequences (40 pages)
19. Hash Tables (18 pages)
20. Pathnames (28 pages)
21. Files (12 pages)
22. Streams (80 pages)
23. Printer (54 pages)
24. Reader (28 pages)
25. System Construction (load, compile-file, ...) (16 pages)
26. Environment (38 pages)
27. Glossary (36 pages)
A. Appendix (12 pages)
This organization is not cast in concrete and will probably change again
somewhat in a subsequent draft (e.g., to merge chapters 2 and 9,
chapters 4 and 7, etc.)
Format of Review Comments
Because of the number of drafts running around, I would strongly prefer
to receive hardcopy with comments directly marked on it, so that there
is no confusion about what place in what draft is being referred to.
The text is changing pretty rapidly, and section numbers are not
necessarily a way to dead reckon things. This also has the advantage
that you can just circle things like typos that are `obvious' and really
require no comment.
If your handwriting is undecipherable or you have some other reason why
you prefer to respond in some other way that merely refers indirectly to a
draft, be sure to specify which draft version you are working with. You
can just say it once in your reply--it doesn't have to be repeated--but
make sure it's there somewhere obvious because without that information,
section numbers are not a unique identifier since text moves around
and sometimes even whole sections move What.
If you see a systematic error related to typography or something else
that can probably be searched for in a mechanical fashion, please just
mark it once (and perhaps mention that it occurs in multiple places)
and I'll search for it online. No need to mark every occurrence.
Some Things To Look For
* Technical errors.
- Things that are missing. These are the very hardest things to spot,
so if you think something might be missing and you're not sure,
mention it just in case. It's easy for me to later verify whether the
item or info you're worried about is elsewhere, or whether it's been lost.
The hard part is thinking to lok for it.
- Things that are wrong.
- Things that look like they are not yet right (i.e., cleanup info
to be merged).
* Ambiguities.
Just write "ambig" next to the item. If you don't think the ambiguity
is obvious--put examples of one or both of the possible readings.
* Reviewer/Editor comments/questions.
Some reviewer comments about ambiguities, errors, etc. have made
visible in the source. They appear in bold, surrounded by braces,
and with the name of the person making the comment usually coming
first. In some cases, it just says that something is wrong and that's
just so you'll know I've already made a note of it. On the other
hand, if you think the comment is wrong, let me know. Or, if the
comment is not a statement of fact but instead just an expression of
opinion or suspicion that you want to offer another opinion about
one way or another, feel free.
* Redundant pieces of text that can be omitted.
Things that can be omitted are constraints which are said in more
than one place where there is really an obvious primary place and the
other place says it only out of paranoia.
For example, a cross reference to a function that not only tells you
to look at the other function but also tells you what that function
does, as in "See CHAR-CODE, which tells you the character code for a
character."
* Redundant pieces of text that are candidates for glossary word status.
Big chunks of text that really are not the property of some
individual function but rather are just a property of the language in
general, especially if they have an obvious name, but perhaps even if
they don't.
* Organizational issues
Don't expect the organization to stay static. I'm not suggesting
that the current organization is best, and I don't want to waste any
time in debate of the full committee at this point about what it
should look like. But I am open to well-motivated suggestions about
changes.
In the end, I hope the structure of the document is sufficiently
modular that last-minute changes to its structure would be easy to
make. At this point, my main concern is that the document be
possible to partition up for reviewers with particular specialties,
and be about the right number of files that my text editor can handle
it in a meaningful way. (There were previously too many files for me
to be able to use my available tools on and I had to reduce the
number from about 1000 to closer to 100. I suspect this new
organization will make others' TeX programs happier, too.)
* DECLARATION-SCOPE
I think the wrong version of this was inserted by someone prior to my
receiving the document to maintain. I've not had time to track down
and fix all the places where this might have an effect. If anyone
wants to note places that are wrong as a result, they should feel
free. But if they don't, I still have it on my list of things to do
myself anyway.
* "instance"
There was a lot of discussion about the ambiguity of "instance".
I've created some new glossary terms which are less ambiguous. These
include "direct instance", "indirect instance", and "generalized
instance". If you see any confusing uses of "instance" which you'd
like to see replaced by these more specific terms, feel free to just
mark a "g", "i", or "d" next to the word instance in your review
comments.
* Examples which modify constants.
We should not have examples that show illegal programming practice
(except where that's clearly indicated). e.g., (DELETE 'A '(A B C)).
* Other things that should have entries.
You'll noticed that I've added Types as a thing with first class
entries. Are there other things?
* Other fields in entries that are so consistently useful that they're
worth separating.
I've added Initial Value fields for parameters.
I've removed Affected By fields for constants.
I've changed "Conditions" to "Exceptional Situations" in functions,
etc. so that I can feel comfortable mentioning not only detected
situations that get signaled, but also undetected situations that are
of an "is an error" status.
* Extraneous glossary words or definitions.
If you think something is a candidate for removal, let me know.
Personally, I don't think there is a problem about having a large
glossary if that's what it takes. Every glossary word pays for
itself almost immmediately in savings over what you'd have to say
every time the word is used elsewhere in the glossary. So they are
not at all an expensive commodity. But it may be that some listed
definitions don't get used (although in some cases you might be
surprised), and I don't mind double-checking and removing or
consolidating those that really aren't needed.
* Glossary words that are poorly chosen.
For example, I'm thinking of renaming "package qualifier" to "package
prefix" to avoid confusion. I wish I could rename "lambda list
keyword" but that's probably too hard. There may be other cases,
though, where confusions result that could be eliminated.
In some cases, as in "SETF method" (a CLOS method named SETF) vs
"setf method" (something that GET-SETF-METHOD deals with), I think we
have to change the language or risk an unreasonable level of
confusion. I will submit a cleanup for this one. There may be others
I don't notice.
* Lost comments.
It's always possible that some comments you made on an earlier draft
didn't get done. If it's just one or two items, perhaps there was a
technical disagreement and there's a reason. Or maybe there is a
comment in the source which notes work to be done later. Or maybe
it's something that Kathy gave me and I didn't realize wasn't already
done. Or maybe it's something Kathy didn't give me. There could be
many reasons.
But whatever the reason, please don't let yourself spend a lot of
time saying the same things over again without talking to me first to
make sure it's not just a mixup. If something really did get lost,
there may be nothing to be done but repeat some work, but I wouldn't
want that to happen without us being sure up front. Thanks.
* Things I Didn't Think Of.
This is a compendium of things that I thought of for you to look for.
Perhaps I'm overlooking things that are important. Help me at the
meta-level by mentioning any other classes of things that I should
have people look for but have forgotten to mention.
Some Things Not To Look For (And Why)
* "is an error"
Lots of people have marked cases like this as old fashioned, but
there are situations where it is syntactically complicated to avoid
this. As such, I think a few cases will persist, and we'll continue
to just identify it as a synonym for "undefined consequences". In
any case, this can be mechanically detected, so don't worry too much.
* Don't worry if cross references to named sections seem confused.
I plan to search mechanically for these and fix them later. The main
problem is that currently the names are hardwired into the text, so
every time anything is moved or renamed, all the wired names get
screwed up. I will make this process more mechanical at some point
and that problem will naturally go away.
I apologize for any confusion this causes in tracking the cross
references. Section 6.1 is referred to in a number of places, and I
think it is now Section 5.5. (I mention this only because I know
it's a common offender; there are probably others less used but still
important that I'm not mentioning. Sorry about that.)
* Don't worry if some glossary words don't show up in italics.
I have changed the font of a bunch of glossary words to help me get a
feel for how things will look when this is done, but by no means have
I dont them all. It's easy to search for these and mark them later
in a mechanical way so it's not worth every reviewer's time to search
for them manually.
* Don't worry if some glossary words which name datatypes appear sometimes
hyphenated and sometimes not.
Ultimately I plan to provide non-hyphenated synonyms for all of these
in the glossary. That means the running text will talk about
"simple bit vectors" (in italic) rather than "objects of type
simple-bit-vector" (with the type name in bold). The reasons for
this change are several:
- the italic word "simple bit vector" is shorter, and will not
sacrifice formal precision.
- the italic word "simple bit vector" can be hyphenated because
it will be all in English instead of involving lisp symbols.
- avoiding use of "of" will avoid erroneous parses due to faulty
prepositional phrase attachment.
"the argument must be a sequence of objects of type array"
the sequence? the object? if it just says "a sequence of arrays"
with "sequence" and "arary" in italic, that will make things
shorter and less ambiguous.
But I have not made this change completely yet, and it's easy for me
to do mechanical searches later to find these. Reviewers need not
spend time on this.
* Keyword arguments.
Currently, keyword arguments are referred to in the running text of
descriptions with the colon on them. e.g., it sometimes says things
like
"If :FOO is true ..."
or "If the :FOO option is true ..."
According to the style I've adopted, the former usage is an incorrect
one since all keywords are true. The latter usage is better, but too
verbose. I plan to remove the colons and just refer to the parameter
without colon in the font used for all parameters, as in
"If <foo> is true ..."
where <...> denotes italics. It's easy for me to mechanically search
for all offenders, so don't worry about marking these.
* Uses of toplevel SETQ.
SETQ to free variables not proclaimed special are not portably
defined in CL. Most (perhaps all) implementations permit this
interactively, and take it to refer to dynamic variables. Many
examples do this and I will either rewrite the examples or put a
global disclaimer somewhere that says that readers should assume that
all free references to such variables are assumed to have been
defvar'd or some such. In any case, it's not worth anyone wasting a
lot of time finding in this review.
* Do not worry about keywords sometimes appearing in bold and sometimes
in the typewriter font.
I'm part way through converting these to a consistent theory. All
CL-defined symbols (things in the COMMON-LISP and KEYWORD packages)
will ultimately appear in bold. All user-defined symbols, sample
code, etc. will be in typewriter font.
Middle Ground (Things You Might Or Might Not Want To Look For)
* Exceptional Situations.
The issue ERROR-CHECKING-IN-NUMBERS-CHAPTER was tabled, but at that
time X3J13 agreed unanimously in an informal vote in Jun-89 meeting
to allow drafting committee to put in stuff like this. So I've
started doing that but haven't completed it. It only affects places
in the Exceptional Situations fields of things. If you notice places
where it's present and you think it's wrong, please feel free to note
it. If you notice places where it's not present and you think it
should be, it might be that I've just not gotten to it--feel free to
note it then, too, if you want, but if you want to ignore it on this
pass and catch it next time around, that's fine.
* Affected By, Side Effects, and Exceptional Situations: None or The Implementation.
I think that when these fields just contain "None" or "The
implementation" they are sometimes suspect. I've been fixing some
of these as I run across it, but feel free to note other cases.
Also, if you spend enough time looking at a "None" and believe it to
be "right", please be sure to mark it as such to help me know which
ones still need to be checked out.
* Syntax.
There are a lot of Syntax fields which have little glitches in them.
Some of these are on my list to fix when I have time, but some errors
are hard to spot, so don't be shy about marking things that are
suspicious or troublesome to you.
* Missing cleanups.
If a cleanup isn't listed in the master table of what cleanups have
been merged, it's not essential that you mark it down. I'll be
getting to the other cleanups later. If you want to note cleanups
that aren't included just in case you're worried that they're not on
my list, that's fine. If you want to mark places you hope they'll be
mentioned, that's fine, too. But don't feel obliged.
The master table of cleanups is a plain text file (not a .dvi file)
called issue-index.text
* Missing definitions in glossary
Some glossary items say "needs a definition". In most cases, I'm sure I'll
be able to contrive one on my own, I just didn't have time to do it before
this draft (probably because I noticed the need for the term right before
I had to freeze the sources). If you want to suggest a definition for any
of these, feel free, but there's no necessity.