Comments on wording in "Revenge of the Packages"

[Kent M. Pitman <KMP at MIT-MC>]

These comments refer only to wording that I think should be cleared up;
not to semantic problems in the spec.

I think that

    A symbol that is uninterned (has no home package) is printed preceded by
    ``@b[#:]''.  It is possible, by the clever use of import and unintern,
    to create a symbol that has no recorded home package, but that in fact is
    interned in some package.  The system does not check for this.

would be far less confusing as

    If the symbol's home package is NIL, it will be printed preceded by
    ``@b[#:]''. Uninterned symbols, such as those created by GENSYM,
    are the most common example. It may be possible through `clever'
    combinations of @b[import] and @b[unintern] to create a symbol
    which has no recorded home package, but which is in fact interned in
    some package; for efficiency reasons, this pathological case is not checked
    for, and such symbols will also be printed preceded by ``@b[#:]''.

I think we should try to avoid statements which if read out of context will
have strong implications that are not strictly true.

Also, your descriptions of the syntaxes should take one of two moods, but not
be split. Either you should describe why a symbol prints a certain way, or you
should describe what the reader does when it encounters a certain symbol, or
both separately, but not both mixed together as you do in:

    @b[foo:bar] @\Look up "bar" among the external symbols available in the
    package named "foo".
    
    @b[foo#:bar] @\Look up "bar" among the external and internal symbols
    available in the package named "foo".
    
    @b[:bar] @\The symbol named "bar" is a self-evaluating keyword.
    
    @b[#:bar] @\The symbol named "bar" is uninterned.

I would suggest either describing the meaning of a symbol printing a certain way,
as in:

    @b[foo:bar] @\The symbol "bar" is among the external symbols available in
    the package named "foo".

    @b[foo#:bar] @\The symbol "bar" has a home package of "foo", but is not
    an exported symbol of that package.

    @b[:bar] @\The symbol named "bar" is on the keyword package.
    
    @b[#:bar] @\The symbol named "bar" has no home package information.

or the meaning to the reader of the given syntaxes, as in:

    @b[foo:bar] @\Expect to find an external symbol named "bar" in the "foo"
    package and use that.

    @b[foo#:bar] @\If there is a symbol "bar" on the "foo" package, whether
    external or not, use that. If there is no such symbol, create one and use it.

    @b[:bar] @\If there is an external symbol on the keyword package named
    "bar", use it. Otherwise, create such a symbol (binding it to itself), 
    and use that.

    @b[#:bar] @\Create a symbol named "bar" but do not intern it on any package.

or some such. 
--kmp