[etoys-dev] Another pass in the Etoys Reference Manual: tiles

Edward Mokurai Cherlin mokurai at sugarlabs.org
Fri Dec 7 16:55:17 EST 2012

On Tue, December 4, 2012 10:42 pm, Steve Thomas wrote:
> Agree with Rita,  while not perfect we as a team spent a lot of time
> working on the chapter and the organization. Not perfect but it does have
> a structure.

A structure that I am following as best I can without guidance. There
is no design document for this manual that I can abide by. I would be
happy to help write one. If you want me to work with you, you have to
work with me. I have not even been able to find out who all the team
members are.

I have asked for assistance in understanding this project many times.
It has never been forthcoming. The only way I have ever gotten a
useful reaction from this group is by simply plowing ahead and then
responding to complaints.

You can do better than this.

> Edward,
> Perhaps it would be best if you made a separate manual and once done you
> can ask for input on that.  Perhaps along the lines you discussed earlier
> (Etoys by Example).

I will write that, or better work with the community to create that.
Would anybody like to join in?

However, the detailed tiles documentation belongs in the Reference
Manual, not in an introductory work. Certainly Etoys By Example cannot
be a reference for Squeak in Etoys or Etoys in Squeak, however one
might wish to view that relationship. But the Reference Manual Vol. 2
idea below would certainly work

>  I think that could add more value as it is a good idea
> and would give people different ways to approach, learn about and use
> Etoys.

It can be an important addition to the literature, but it cannot be a
dumping ground for reference material that you don't want in your
reference manual. But let that pass. We seem to have a solution.

> Thanks for all your input.

You are welcome.

> Stephen
> On Tue, Dec 4, 2012 at 10:04 PM, rita <rita at isg.cs.uni-magdeburg.de>
> wrote:
>> Hi Ed,
>> at the moment, I don't have the time to look through your changes. The
>> common tiles chapter hasn't been in need for additions, so I have to
>> look what you added and find out if it will stay there.

OK. You don't have to look _through_ all my changes to answer the
first question. Just look _over_ them and tell me what you think we
ought to do with the thirty plus categories I documented there. I
would prefer to keep them together, and not distribute them with the
object descriptions, in the interest of discoverability.

>> Please stop making
>> additions before I have the time to look it up. I don't want you to do
>> work that will be removed later.

That doesn't make any sense to me. I have to put my work somewhere in
order to let you look at it. There is no problem if it has to be moved
or removed, although I must ask you not to move any of my material
after the last disaster, when you dumped some but not all of my
implementation notes in bits and pieces, out of order, and lost some.

>> We will not split up the common tiles chapter for this manual, this is
>> the chapter for the nearly universal categories.

That is precisely why I asked whether I should create a separate
chapter for the non-universal categories. I would appreciate it if I
could get answers to the questions I ask, not just complaints.

>> I will look through your comments about unusable tiles or
>> functions you can not determine. This will
>> be very helpful, since we want the reader to understand the manual.

Glad to help.

Anybody else who can help, please, also. I believe that I can solve
most of those conundrums by converting those tiles to text and looking
up the method selectors they use. I will try that next and add
explanations or further mysteries as I find them.

>> The programming tool chapter needs to be part of another manual.

I like the idea below of having a Vol. 2. So I think we are in
agreement. But I wish to state why I want these materials, and why I
want a Vol. 2.

These are objects directly accessible in Etoys. They are the only
tools available for understanding much of the behavior of the more
common Etoys objects. I am willing to draw a line after explaining how
to access them and what they are, and before explaining how to use
them in development. That should go in a Squeak manual. I am not
willing to omit them entirely. There was a table of keyboard shortcuts
for accessing them in the manual when I started to work on it. I
assumed that that made the tools accessed with keyboard shortcuts in
scope. Nobody told me otherwise when I asked what the design was meant
to be.

We also need to discuss my notes on the Squeak implementation of Etoys
objects. They are currently in the holding area. They could go in a
separate manual of some sort, but I have been strongly influenced by
Smalltalk: The Language and Its Implementation in my thinking about
the design of reference manuals, so I want them in.

I want this material in, for precisely the reasons that motivated me
to discover it.

It is not enough to document Etoys with no reference to Squeak. Much
of Etoys is extremely obscure, and can only be understood via Squeak.

The tools for accessing Squeak are, obviously deliberately, built into
Etoys and provided on menus that we must document. We also have to
document the Etoys path from pure Etoys to Squeak programming, which
should begin in the third grade curriculum or perhaps even earlier,
based on successes in teaching a wide range of programming languages
in third grade, and occasionally earlier. I can provide citations if
needed, for Logo, LISP/SCHEME, APL, Smalltalk, and others. We also
need to think about Computer Science concepts, such as OOP, parse
trees and parallel programming, that we can begin to demonstrate and
explain in third grade or sooner. Tile scripting gives a natural
window into parse trees, and the StandardViewer gives an extensive and
fairly deep view into OOP. Parallel programming is inherent in Etoys,
and exposed in the UI in a number of different ways.

The path from Etoys to Squeak includes translating tiles to text, a
function on the Scripting Editor menu.

It includes editing the text version of a tile to perform some other function.

It includes all of the introspection tools available on menus within Etoys.

It includes understanding how Morphs and other Etoys objects are
implemented, how they are represented as players wearing costumes, and
especially how scripting tiles are implemented.

It includes a dissection of each Project provided with Etoys, and of a
number of Etoys objects, notably games and simulations, that are not
implemented in Etoys.

I have an unanswered question that I would like help with. If I am
writing Squeak code in a text tile, how do I refer to other Etoys
objects? I have tried looking up their player and costume names, but
that doesn't seem to work as I expected it to. I will run some tests
and post a more detailed version of the question after I finish
another pass over the tiles, and settle into the programming chapter.

>> This
>> manual will stay in the shape we decided when we started it and then we
>> can
>> have part two, which focuses on the Etoys-squeak relation. Feel free to
>> create the new manual, or do you want me to do it?

Well, if we are talking about a volume two, certainly we can move some
material there. That wasn't in any plan I have heard of, but it's an
excellent suggestion.

No, I don't want to create it, nor do I want you to, right now. Maybe
in a week or two. First, I want to have a design discussion of both
volumes, and document our decisions in the Notes or ToDo sections.
I'll propose an outline for Vol. 2 after I think about it for a bit.
So far we are considering moving

Programming tools within Squeak but outside scripting

Squeak implementation of Morphs and other Etoys objects, of players
and costumes, and of tiles

The Etoys-Squeak programming interface using text tiles

We could move all of the existing Appendices other than Glossary and
Credits. That would be Preferences, EtoysFriendly, Siblings, Errors,
and Mime Types.


What else?

And what should the title or subtitle be?

What other questions should we ask?

>> Greetings,
>> Rita

Mit freundlichen Grüßen,

Houn Mokurai (Schweigsamer Donner der Dharma Wolke)

>> On Mon, 3 Dec 2012 12:51:19 -0500, Edward Mokurai Cherlin wrote:
>>> I looked at the Viewer categories for every object in the Object
>>> Catalog, and at the Squeak lists of categories and tiles, and
>>> documented every tile in every category I found as much as I could in
>>> the Common Tiles chapter of the Etoys Reference Manual. I have not
>>> updated the introduction to the chapter yet. It is incorrect in saying
>>> that some categories are explained only in the Objects chapter.
>>> Now I have some questions.
>>> 1) Should we split the Common Tiles chapter, as we split the Objects
>>> chapters, so that we have a chapter for the nearly universal
>>> categories that every Morph has (but not, for example, the Kedama
>>> objects), and another for all of the categories specific to individual
>>> objects and small groups of objects? In the draft chapter, the
>>> boundary is at section 4.18, on book navigation. Near the beginning of
>>> the chapter there is an image of the category menu for Morphs, and a
>>> list of categories for specific object types that do not appear on the
>>> list for Morphs.
>>> 2) There are a number of tiles whose effects I could not determine
>>> from the help text or through experiment, and some that appear to be
>>> so buggy as to be unusable. I have made notes in the draft on all of
>>> them, mostly in Formatted (monospace on colored background) text. Any
>>> assistance on interpreting these, or filing bug reports, would be
>>> welcome. At some point I mean to look at their Squeak implementations
>>> (via 'show code textually' on the Scripting Editor menu, and
>>> 'selectors containing it'  on the control-click menu for text
>>> selections) to see whether they are any more illuminating.
>>> 3) Some of the help text clearly needs to be rewritten to, you know,
>>> help.
>>> 4) I am about to write the chapter on Programming Tools, which will
>>> begin by describing every Squeak tool accessible from any Etoys menu,
>>> such as the System Browser, and tools for viewing Senders,
>>> Implementors, Selectors, and so on provided on the World menu and the
>>> open... and authoring... menus that it gives access to. I intend to
>>> describe the Morphic and Etoys-Scripting classes, also, to some
>>> extent, and then stop. I do mean to write more about the
>>> implementation of Etoys in Squeak, but in other books, which we can
>>> discuss. For example, I have thought about a chapter on writing Squeak
>>> in text-mode scripting tiles in an Etoys User Manual or Etoys By
>>> Example, so that we can discuss concretely teaching more advanced
>>> programming and Computer Science topics on the basis of Etoys.
>>> 5) Then I intend to go over the entire book again, with the benefit of
>>> what I have learned. Presumably I will have more questions at that
>>> point.

Edward Mokurai (默雷/निशब्दगर्ज/نشبدگرج) Cherlin
Silent Thunder is my name, and Children are my nation.
The Cosmos is my dwelling place, the Truth my destination.

More information about the etoys-dev mailing list