[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Rpt#16 MCL 2.0 Ref Ch A, F

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
    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
             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
   (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))
         (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)))
(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
                   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
                    in a 3MB partition (this wasn't tried on an SE). Gary's
                    to this was that Traps.lisp and quickdraw.lisp should
either be
                    file compiled immediately by users, or the fasl files
                    with MCL (most of the time appeared to be spent
"require"ing QD).
                  - the stream example (in grapher.lisp in 2.0b4) is very
                    but without zoom control the graph is far too big to
                    Reducing the font and box size helps but doesn't solve the
             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
                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.
                grapher.lisp contains an example at the end of the file.
                   It is an excellent example of the use of
                #<STANDARD-CLASS BAR> is spurious.
                   (It isn't introduced until p583).
page 582. class-direct-superclasses.
                Typo: The last word should be "form" not "forms".
page 583f. class-prototype.
                "class-prototype (class standard-class)"
                   should be
                "class-prototype (class ccl::std-class)".
                "The class-precedence-list function..."
                    should be
                "The class-prototype generic function...".
                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.
                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.
                "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.
                "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.
                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.
                "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.
                "...it returns one of the applicable primary methods".
                   Which one?
                   Can be a symbol.
                   What do these represent? An example would help.
page 592. *check-call-next-method-with-args*.
                There are 2 "When...then..." constructs.
page 593. *defmethod-congruency-override*.
                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.
                   "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
page 597. uvref (cont.)
                "(< 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?
                No doc string.
                Also missing from the index.
page 602. Backward compatibility with the 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.
                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.
               (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)
                  (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
                   "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
                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.
                "...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.
                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
                   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.
                "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
                   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
                      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
                      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.
                   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
                   Violate in what way?
page 611. Compiler policy objects.
             1st paragraph.
                XRef "optimize" to CLTL2 p231.
page 612. new-compiler-policy.
                Typo. ":allow-tail-recursion-elimiation" is missing an "n".
                ":inhibit-event-polling" is missing.
                The formatting of the keywords is ugly.
                Typo. "compilerpolicy" is missing the space separator.
                It needs to be made clear up front that the file compiler
                   and the compiler policy are mutex, (although both are
                   by this function) and that setting a new policy completely
                   shadows the existing policy.
page 615. current-compiler-policy.
                "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.
                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
   much less a development system.
If you don't have direct Internet access you're facing a day's delay in each
The page footer says "Selected Bibliography".
page 738. The single most valuable source.
             Say CLTL2 documents the "approximately 900 symbols of Common
                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.
                "info-macl" should be "info-mcl" (4 occurrences).
End of Rpt#16 MCL 2.0 Ref Ch A