View this PageEdit this PageAttachments to this PageHistory of this PageHomeRecent ChangesSearch the SwikiHelp Guide
Hotspots: Admin Pages | Turn-in Site |
Current Links: Cases Final Project Summer 2007

Squeak Documentation Requests

To the general Squeak community: what in Squeak would you like documented? Leave an email address if you don't mind answering questions from a student about the topic. To CS 2340 students: investigating a dark corner of Squeak and documenting it for others is a fine way to get Extra Credit.


Also, Karl Ramberg points out that http://www.squeaknews.com has a growing documentation area. If you write documentation good enough to aid future people taking this class, it would probably be good enough to help people in the general Squeak community.

Missing Page: I found this documentation very helpful. I don't know what version of Squeak this describes.


How's about a comprehensive tutorial for newcomers. I really do not believe that there is a a single comprehensive SQUEAK tutorial for newcomers.

Something that starts with installation, walks them through using the update from server, walks them through the language elements, explains about Projects, change sets, file-in, the standard tools, supplies, COMMONLY USED classes, the Squeak community resources (e.g., Fixes Archive, Swikis, ...), etc.

Something to take the user from complete lack of familarity to the point where they are able to use and extend the PDA PIM applications in the current image.

That might be larger in scope than a single student wants to do for extra credit, but perhaps as a group it could be done.


Connectors

Ned Konz suggests:

Perhaps my New Connectors stuff could stand to be documented first. What's the time schedule? I have to clean it up a bit first... (Ned Konz)

Class Comments

Dan Ingalls suggests:

This might be too broad a request, but I think it's time for a concerted pass over the class comments to get at least a few useful sentences about what each class does and how it works with others.

Then a simple addition with a lot of leverage would be to add a 'find...' command to the browser that would search class comments for matching text, just as the current one searches for matching names.

This would have allowed Benoit St-Jean to find PopUpChoiceMorph when he was looking for menu bar tools this morning.


Ted Kaehler responds:
Students and all,

 The thing that I thirst for is the "basic idea" behind each 
class.  What is the purpose of this class?  That's the thing you 
can't get from reading the implementation.  What are the unwritten 
assumptions?

At 8:02 PM -0700 6/19/01, Dan Ingalls wrote:
>Then a simple addition with a lot of leverage would be to add a 
>'find...' command to the browser that would search class comments 
>for matching text, just as the current one searches for matching 
>names.

 This is already in the system!  Just type what you want to 
search for in any text pane, get the shift menu, and choose "class 
comments with it".  Up pops a MessageSet with all of the class 
comments containing that text.  You can 'Browse Full' from there.

--Ted.


Randal Schwarz responds:
Ted>  This is already in the system!  Just type what you want to
Ted> search for in any text pane, get the shift menu, and choose "class
Ted> comments with it".  Up pops a MessageSet with all of the class
Ted> comments containing that text.  You can 'Browse Full' from there.

So the important thing here is to get the current image to at least
have class comments!  I'd especially like to see some of the
deprecated classes be labelled as such... I know over the past few
years on this list I've seen "oh, don't use that, we're doing it this
way now" more than once.


Serialization Mechanisms (and Ceneral Comments)

Henrik Gedenryd suggests:

I thought it might be useful to answer this on a general level.

I'd say documentation is particularly useful for parts that are not already
documented (particularly, in the Smalltalk-80 book[s], or the squeakbook),
either because they are new or have been changed since then. Also, that the
more "core" the functionality is, and the less likely the code is to change
fundamentally, the more useful documentation would be. (Perhaps this is
obvious and everyone agrees on it?)

Now what would this mean? Morphic is certainly a central new part, but there
are already (too) many different pieces on that.

I'd suggest the whole image segments/SmartFileStream/project loading complex
of various classes. (If not all, then any part of it would be nice.)

This because it could be very useful as a foundation for general modularity
mechanisms, but if they are to serve such a central function, then they
dearly need to be well documented. Just such a small part of this as
veryDeepCopy needs to be better documented. I have learned that part myself
but that was in the hard way. The part where GC is used to map out a part of
memory would be nice to have clearly explained as well. One shouldn't have
to understand the GC implementation to use that mechanism.



Morphic's Redraw Mechanisms


Henrik also suggests:

One piece of Morphic that is not yet documented is the drawing cycle. It is
also not exactly intuitive, it can be really hard to debug. It would be very
nice to have good diagrams and so on that explain double buffering and how
redrawing is triggered and when it is carried out, etc..



EToys

Jim Benson suggests:

I'd love to see a high level abstract overview of how the eToys system is
put together, and how that effects the more concrete implementation. For
example, some of the things sprinkled throughout the image are references to
playfields, flaps, players, and scripts. AFAIK there is no single document
that gives the overview of what these terms mean, how they are related, and,
more concretely, how those concepts show up in the image.

While this is a rapidly changing area of Squeak, the concepts are pretty
well in place and it would be nice to see a short "white paper" of eToys. I
know it would have saved me a lot of time a couple of years ago.


Text Support

Richard O'Keefe suggests writing up how ParagraphEditor and its relatives work.


Low-Level OS Interfaces

Vincent Coetzee suggests:

I have recently been doing some work around using Squeak to produce 
native Cocoa apps on Mac OS X. Documentation regarding the mechanism 
used to channel OS events into Squeak and how the event handling is 
performed in Squeak might be very useful. Is this covered in one of the 
Smalltalk books, or does Squeak use significantly different mechanisms 
for handling this ?


Be sure, guys, that you check what already exists before dipping into this – there is an chapter on some of this stuff in the upcoming Squeak book editted by Mark Guzdial and Kim Rose.

I think the EventRecorderMorph in squeak could be used for a pretty simple walkthrough. I think this would be easiest to do. I think it's supposed to have a compressed audio stream too, but i couldn't seem to find that. It would really be great if a guru would just spend an hour or two making EventRecorder tapes for the newcomers.

Multi-Threaded Squeak


For those interested I've created a little Tutorial on Multi-threaded Squeak. Hope this is helpful to someone.

Jon Olson


audio

Link to this Page

  • Extra Credit last edited on 22 June 2007 at 12:22 pm by balladeer.cc.gatech.edu