[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Rpt#16 MCL 2.0 Ref Ch A, F
- To: INFO-MCL@CAMBRIDGE.APPLE.COM
- Subject: Rpt#16 MCL 2.0 Ref Ch A, F
- From: STEVE.M@AppleLink.Apple.COM (Aladdin Systems,Steven Mitchell,PRT)
- Date: 11 Dec 91 07:58 GMT
File: Rpt#16 MCL 2.0 Ref Ch A, F
To: Sarah Smith
From: Steve Mitchell
Last edit: 12-10-91 @ 9:00pm
Feedback on: "MCL 2.0 Reference"
Reference: October 91.
MCL: MCL 2.0b4
H/W: 4MB Mac SE
OS: System 6.0.5
INITs/cdevs: Minimal
Sarah:
FEEDBACK ON MCL 2.0 REFERENCE - CONTENTS:
Chapter A. Implementation Notes.
Chapter F. For more information.
=============================================
Chapter A. Implementation Notes.
This chapter is very readable and straightforward. The general organization and
order is fine.
page 579. Contents.
There should be a sub-section title on p580 for metaobject
classes.
There should be a sub-section title on p581 for MOP functions.
An intoduction there should explain that the functions
documented are not documented in CLTL2, but some are
documented in The Art of the MOP.
Consider introducing more subsection headings for related
groups (eg by the class of the argument) of documented
MOP functions.
page 580f. Table A-1.
a) Make sure it is printed on a single page.
b) The way the first column line-wraps is bad.
c) How about a diagram? I modified the example in grapher.lisp
to show all subclasses of metaobject:
----- start of modified grapher example src --------
(defclass object-node (node)
((my-object :initarg :object :accessor my-object :initform (find-class
'metaobject))
(my-parents :initarg :parents :accessor node-parents :initform nil)
(my-children :accessor node-children)))
(defmethod node-draw ((self object-node))
(when (call-next-method)
(let* ((topleft (node-position self))
(left (point-h topleft))
(bottomright (add-points topleft (node-size self)))
(bottom (point-v bottomright)))
(rlet ((r :rect
:topleft topleft
:bottomright bottomright))
(#_eraserect r)
(#_framerect r)
(#_moveto (+ left 2) (- bottom 3))
(#_insetrect :ptr r :long #@(1 1))
(without-interrupts
(with-clip-rect-intersect r
(with-pstrs ((str (object-name-string self)))
(#_drawstring str))))))))
(defmethod node-size ((self object-node))
(make-point (+ 6 (string-width (object-name-string self)))
12))
(make-instance 'grapher-window
:root-node (make-instance 'object-node)
:window-title "Metaobject Graph"
:view-font '("Geneva" 9))
----- end of modified grapher example src --------
Note that I also reduced the font and box size.
I suggest changing the example in grapher.lisp to use the
smaller font and box sizes, and provide a menu item
that brings up a dialog for the user to enter or choose
a class to graph, and choose sub- or super-classes.
Then the Reference can XRef graper.lisp as an example.
Don't forget to modify the example to show the package for
internal classes (I didn't look into this).
For the Reference, a vertical rather than a horizontal graph
would
be better. It shouldn't be terribly difficult to do this.
Notes on grapher.lisp:
- in the intro in the file, "usual-node-draw" appears.
- the grapher.lisp file takes painfully long to load on a Mac
II
in a 3MB partition (this wasn't tried on an SE). Gary's
response
to this was that Traps.lisp and quickdraw.lisp should
either be
file compiled immediately by users, or the fasl files
distributed
with MCL (most of the time appeared to be spent
"require"ing QD).
- the stream example (in grapher.lisp in 2.0b4) is very
exciting,
but without zoom control the graph is far too big to
visualize.
Reducing the font and box size helps but doesn't solve the
problem.
d) generic-function is a subclass of
ccl::funcallable-standard-object, but the latter
does not appear in the Class column
e) funcallable-standard-object is internal to ccl.
f) ccl::compile-time-class is shown with only 1 colon.
g) ccl::std-class is shown with only 1 colon.
h) In the para before the table:
"The following table shows the structure..."
should be
"The following table shows the class structure..."
to distinguish it from the next sentence which talks
about metaclasses (the classes of the class instances).
page 581. Near top. Re: ccl::compile-time-class.
"The class class-name works on it and find-class find sit if
given the compile-time environment as its third argument".
(find-class 'ccl::compile-time-class)
-> #<standard-class ccl::compile-time-class>, and
(class-name (find-class 'ccl::compile-time-class))
-> ccl::compile-time-class
a) class-name is a gf not a class.
b) The meaning of "works on it" is unclear.
c) Typo: "find sit".
d) "but none of the other MOP functions returns any kind of
useful information".
I think this means that none of the other MOP generic
functions defined in this chapter has a method for
ccl::compile-time-class. What do they return for a
ccl::compile-time-class?
e) It appears that the third argument does not have to be
supplied, or, when must it be supplied?
f) find-class has no doc string.
page 581f. class-direct-subclasses.
Example.
grapher.lisp contains an example at the end of the file.
It is an excellent example of the use of
class-direct-subclasses.
#<STANDARD-CLASS BAR> is spurious.
(It isn't introduced until p583).
page 582. class-direct-superclasses.
Description.
Typo: The last word should be "form" not "forms".
page 583f. class-prototype.
Syntax.
"class-prototype (class standard-class)"
should be
"class-prototype (class ccl::std-class)".
Description.
"The class-precedence-list function..."
should be
"The class-prototype generic function...".
Example.
The result "3" should be "2". Explain that y is only bound
because of ":allocation :class".
page 584. class-direct-instance-slots.
XRef to slot-definition-name on p589f for an example.
page 584. class-direct-instance-slots.
Example.
The "Example" heading is missing.
Due to working thru the chapter, "(defclass bar..." failed:
> Error: Inconsistent superclasses for #<standard-class gronk>
> While executing: ccl::compute-cpl
page 586. specializer-direct-methods.
Description.
"MCL provides no way to access methods that have
eql specializers".
This needs qualification in case anyone thinks "access"
covers "invoke"!
page 586f. specializer-direct-generic-functions.
Description.
"In the default world, the specializer-direct-methods lists..."
should be
"In the default world, the
specializer-direct-generic-functions lists..."
page 588. method-function.
Description.
Typo. 1st sentence: "funtions".
The other sentences pretend "functions" is singular!
page 589. slot-definition-name.
The index shows it on p590 only.
page 590. copy-instance.
Half a dozen copy-instance methods are defined in
":Interface Tools:ift-utils.Lisp", and calls appear
in Dialog-Editor.Lisp and menu-editor.Lisp.
page 591. clear-clos-caches.
Description.
"The clear-clos-caches function clears CLOS caches
(usually) in preparation for doing a save-application...
...This function is called if the value of the
:clear-clos-caches initarg to save-application is true
(the default)."
These 2 sentences need to be unified. I am a little
confused, especially by "(usually)".
page 592. method-exists-p.
Description.
"...it returns one of the applicable primary methods".
Which one?
Definition.
generic-function.
Can be a symbol.
args.
What do these represent? An example would help.
page 592. *check-call-next-method-with-args*.
Description.
There are 2 "When...then..." constructs.
page 593. *defmethod-congruency-override*.
Description.
There are 2 "When...then..." constructs.
The nil case should be presented directly after the
t case, rather than at the end (especially as it is
the default).
page 595. Types and tag values.
1st para.
"...determine the (primary) type of the object".
Remove parens, and explain "primary".
Tag value 2.
Remove double-quotes from "into".
Tag value 5.
Typos:
"upper 29 bit" should be "upper 29 bits".
"and 23-bit" should be "and a 23-bit".
"signifcand" should be "significand".
Tag values 5 thru 7.
It does not say where the pointer points.
page 596. Types and tag values (cont.)
1st bullet.
The first sentence is sloppy. It should say that if
bits 8 to 15 (or the high byte of the low word or
the most significant byte of the least significant
word of the long word) contain #xF..., or somesuch.
Certainly, the two #xF values are unrelated.
The second sentence should NOT talk about "the upper
16-bit word" but "the most significant word", or
somesuch.
page 597. uvref (cont.)
Description.
"(< 0 index (uvsize object))"
should be
"(< -1 index (uvsize object))"
or, better
"(<= 0 index (- (uvsize object) 1))".
page 598. Repro of the top 2/3 of this page was no good.
I couldn't read it.
page 602. Packages.
"...approximately 900 symbols of Common Lisp".
I don't know where this is in CLTL2. Do you need to
double-check this?
*make-package-use-defaults*.
No doc string.
Also missing from the index.
page 602. Backward compatibility with the lisp package.
*autoload-lisp-package*.
Sarah's new doc string says (among other things):
"When the value of this variable is true, the :lisp package
is automatically loaded when it is required."
This clarification is missing from the Reference.
Also missing from the index.
page 603. Backward compatibility with the lisp package (cont.)
"If you are running your own code, upgrade if possible".
I think of "upgrade" as meaning: get a new version of a
vendor's product and install it, whatever that entails.
page 603. Additional printing variables.
XRef to CLTL2 for the ones in the Print Options dialog.
*print-structure*.
Appears in the Print Options dialog.
I believe the default is not nil but t.
Missing from the index.
page 604. Memory management.
Typos. Line 2:
- "Mac heap". Drop the double-quotes (it's not virtual!)
- "CONS" should be "cons" (lower case).
page 604. Function swapping.
"...about 500 KB free in a 3 MB partition".
Sounds about right but you might want to check it.
page 605. preload-all-functions.
Example.
"(progn
(preload-all-functions)
(purge-functions nil))
This is recommended for configurations of 3 MB or more of RAM".
Give an example of checking for a safety margin.
The following is what I made up for my init.lisp file:
(when (> (ccl::%freebytes) 2000000)
(preload-all-functions)
(purge-functions nil))
Reminder: As of 2.0b4 there were no sample init.lisp files.
If I remember, several were supplied with 1.x.
page 606. Ephemeral garbage collection.
"Version 2 of MCL contains a new garbage collector,".
Insert right after the above: "the ephemeral garbage
collector,".
"ephemeral garbage collector" should be bold, and in index.
Why not rename "thermometer.lisp" to "gc-thermometer.lisp", and be
done with it?
page 607. Ephemeral garbage collection (cont.)
"In general, an invocation of the EGC when MMU support is
unavailable is much faster than a full GC, but much slower
than it would be were such support present".
This sentence is too important to be buried, and it's
convoluted.
I suggest something like this:
" The following will be true in general:
Tip: EGC will be much faster than a full GC, although
collection will occur more often.
Tip: EGC with an MMU will be much faster than without it.".
Gary may have a tip on the relative speed of virtual memory gc.
"The EGC...is said to be active when MCL is in fact using it".
I know what this means but it isn't totally clear on first
reading. "active" conjours up an image of a gc taking place.
I don't think the term is necessarily wrong, but it needs
more explanation.
Also, an explanation of "active" is needed under "egc".
page 607. egc.
Description.
"...attempts to enable and activate...".
I gather the returned result is independent of the outcome
of the attempt to activate the EGC. As noted above, an
explanation of "active" is needed.
page 608. egc-active-p.
Description.
An explanation of "active" is needed.
Has no doc string.
page 609. Full garbage collection.
2nd para, regarding System 6.
Make this a Note or a Tip on System 6. Say what happens under
System 7 - unlimited event processing? I think the answer
is that the following 2 functions set and test whether
events are processed during gc, and that if they are,
under System 7, window and program switching behaves as it
does when gc is not taking place.
Incidentally, while running UniFinder on a Mac SE w System
6.0.5,
the (full) GC kicked in while a source file was in the
process of being open with File / Open.... Although the window
did not come up until the GC was over, the area it would
cover was painted gray at the start of the GC. After the GC
tcompleted, the window appeared, and the screen was updated
correctly. So it doesn't happen only under MultiFinder.
page 609. set-gc-event-check-enabled-p.
Description.
"Lisp performs event processing during garbage collection".
This sentence is spurious. Remove it.
page 610. The evaluator.
1st bullet.
"evalhook and applyhook were removed" and MCL no longer
supports
them.
Should the Reference say why evalhook and applyhook were
removed, and how code that uses them can be converted?
Is there a section in the Reference about differences
between
MCL and CLTL2 due to the latter being superceded?
2nd bullet.
"For looping or self-recursive constructs, the compiling
evaluator is much faster (up to several hundred times)".
Is this due only to Tail Recursion elimination? In which
case
do you mean tail recursive, or even self tail recursive?
page 610. *compile-definitions*.
Note that it appears in the Environment Dialog.
Appears twice in the index (on this page).
page 611. Tail Recursion elimination.
1st paragraph.
It is a single sentence. That's too long and the colon after
tail recursive is clobbered by the italics. It may be
sufficient to change the colon to a period and capitalize
"when". I suggest changing the style of "tail recursive"
to bold and putting it in the index.
It isn't clear. You'll only understand it if you already know!
"when the value(s) returned by a call to a given function
are whatever value(s) are returned from the last function
it calls, the stack space used by the calling function is
deallocated before the called function begins execution".
Better is:
"A function is tail recursive if it returns the value(s)
of the last function it calls as its own. In this case,
the stack space allocated for its returned value(s) can
be deallocated before it begins execution".
Or use a definition from your favorite Lisp text.
3rd paragraph.
*nx-never-tail-call*.
This is internal to ccl.
Naturally it's not in the index.
"compiler policy objects".
Remove the double-quotes.
Add it to the index (there's even a section named for it
lower on this page).
page 611. Self-referential calls.
1st paragraph.
"...debugging tools such as trace and advise violate this
assumption".
Violate in what way?
page 611. Compiler policy objects.
1st paragraph.
XRef "optimize" to CLTL2 p231.
page 612. new-compiler-policy.
Syntax.
Typo. ":allow-tail-recursion-elimiation" is missing an "n".
":inhibit-event-polling" is missing.
The formatting of the keywords is ugly.
Description.
Typo. "compilerpolicy" is missing the space separator.
It needs to be made clear up front that the file compiler
policy
and the compiler policy are mutex, (although both are
created
by this function) and that setting a new policy completely
shadows the existing policy.
page 615. current-compiler-policy.
Description.
"The current-compiler-policy function returns the default
compiler-policy used by interactive compilation".
"default" is not clear here. In the Reference, "default"
generally means "initial", as in the description of
set-part-color. I think "current" is meant. Similarly for
current-file-compiler-policy on p616.
page 616. set-current-file-compiler-policy.
Description.
Typo: "i s" should be "is".
page 617. *always-eval-user-defvars* (cont.)
Say it's the 2nd edition of CLTL.
=============================================
Chapter F. For more information.
There's no mention of phone support! That's unheard of for any software
product,
much less a development system.
If you don't have direct Internet access you're facing a day's delay in each
direction.
The page footer says "Selected Bibliography".
page 738. The single most valuable source.
Say CLTL2 documents the "approximately 900 symbols of Common
Lisp",
as on page 602 of this Reference.
page 738. If you are learning Lisp.
Add Norvig's book.
You should also mention Mark Watson's book (Gary has it) as it
purports to use MCL version 1.
Note that these 2 books and The Art of the MOP have sources.
Norvig and AMOP can be obtained via ftp. Norvig includes an ftp
tutorial. Gary indicated one would be added to the Reference.
I think Lisp Pointers should be mentioned here.
page 739. If you are learning Lisp (cont.)
Is there a compatibility package for Abelson & Sussman?
page 739. If you are learning CLOS.
I think The Art of the MOP must be mentioned here.
The problem I have with Keene is that most of the examples are
not runnable, and some of the functions are CLTL1 (for
example describe & print-object).
There is also a new CLOS book in the stores whose name I forget.
page 739. If you're learning about Macintosh programming.
Mention that Inside Macintosh is is complete documentation on
the interfaces to the Macintosh's internal routines and runs
over 2,000 pages.
page 740. If you would like examples of MCL programming.
This should mention that some of the info-mcl material may also
be found on the AppleLink MCL Discussion area detailed in the
next section.
page 741. Communicating through AppleLink.
This should mention that AppleLink is outrageously expensive.
page 742. Communicating through Compuserve.
Typo.
"info-macl" should be "info-mcl" (4 occurrences).
---------------------------------------------
End of Rpt#16 MCL 2.0 Ref Ch A