[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



 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

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

 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

 * 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

   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.)


   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

 * 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
      "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.