Philippe Marschall wrote:

2006/8/14, Keith Hodges keith_hodges@yahoo.co.uk:

...

Is there anyone who has the power to rename packages on squeaksource?

Packages or projects?

Philippe

Sorry I meant to say projects!

Keith

___________________________________________________________ Yahoo! Messenger - with free PC-PC calling and photo sharing. http://uk.messenger.yahoo.com

Great! Thanks. That should let me bootstrap the things I need.

Does anyone know of any general references to writing interpreters/ DSLs/Metaprogramming in SmallTalk?

-Rich-

On Aug 14, 2006, at 6:55 AM, Wilkes Joiner wrote:

Here is a blog entry of mine about using the Refactoring Browsers code to generate classes for me:

http://wilkes.blogspot.com/2005/12/simple-code-generation-in- smalltalk.html

The Behavior>>compile: method will add a new method onto a class.

For instance methods: MyClass compile: 'someAttribute ^ someAttribute'

For class methods: MyClass class compile: 'aClassMethod "Do some stuff"'

On 8/14/06, Rich Warren rwmlist@gmail.com wrote:

...

Hi,

I've seen several online articles about writing Domain Specific Languages in Ruby. All the articles mention that the idea of DSLs comes largely from Lisp and Smalltalk. I've found descriptions on writing DSLs in Lisp--but I can't seem to find any good references for Smalltalk.

Does anyone have any helpful pointers? If I'm going to follow the Ruby model, then I need to be able to execute arbitrary strings as code (which Compiler evaluate: and related functions seems to handle). I also need to be able to add new methods to classes/ instances at runtime--which I haven't found.

Any help would be greatly appreciated.

-Rich-

In my tests, I've noticed that Behavior>>compile: actually changes the image. Is there any way to make less-permanent changes (e.g. just changing a single instance)?

-Rich-

On Aug 14, 2006, at 6:55 AM, Wilkes Joiner wrote:

Here is a blog entry of mine about using the Refactoring Browsers code to generate classes for me:

http://wilkes.blogspot.com/2005/12/simple-code-generation-in- smalltalk.html

The Behavior>>compile: method will add a new method onto a class.

For instance methods: MyClass compile: 'someAttribute ^ someAttribute'

For class methods: MyClass class compile: 'aClassMethod "Do some stuff"'

On 8/14/06, Rich Warren rwmlist@gmail.com wrote:

...

Hi,

I've seen several online articles about writing Domain Specific Languages in Ruby. All the articles mention that the idea of DSLs comes largely from Lisp and Smalltalk. I've found descriptions on writing DSLs in Lisp--but I can't seem to find any good references for Smalltalk.

Does anyone have any helpful pointers? If I'm going to follow the Ruby model, then I need to be able to execute arbitrary strings as code (which Compiler evaluate: and related functions seems to handle). I also need to be able to add new methods to classes/ instances at runtime--which I haven't found.

Any help would be greatly appreciated.

-Rich-

It may not be necessary (probably isn't). It may not even be wise. But I'm still curious--how far can I stretch the boundaries?

The specific project I'm working on is an AI research project as part of my Ph.D. Ideally I would like to have a configuration text file that (with an easily-human-readable syntax) configures the system for each trial--one line per trial.

Why not just code it all in smalltalk? I want non-programmers to be able to look at the configuration file, and look at the data and easily understand the initial conditions for a specific run and how it correlates with the resulting data. Having the configuration file as a separate artifact will greatly help--but only if I can make it easy to read (basically code that doesn't look like code).

I'd like to create a mini-language for the config file whose syntax basically consists of objects, selectors and operators. I'm still feeling out the infrastructure's requirements--and I'm trying to decide whether to implement everything in Smalltalk or Ruby. I have good examples for implementing a DSL in Ruby. I think I can port most of the ideas easily enough to Smalltalk, but some of the more complicated examples do make changes to classes at runtime (I'm not sure I'll need that--but I'm also not sure I won't).

So far,they're still running fairly neck-and-neck. In most ways, they're both excellent approaches. Here's my thoughts:

Ruby:

I know Ruby better.

All my DSL examples are in Ruby.

For DSL's, Ruby's syntax seems slightly more flexible than Smalltalk (or maybe I just know how to abuse it more).

From my research so far, Ruby as better support for distributed objects (especially Rinda). This might be important if we need to move the code over to the cluster.

Ruby can more-easily create actual child processes, which might let me plow through the data faster on a dual-core machine (though, I believe this might lock it into only running on Unix boxes).

I have better Ruby reference books.

I have good instructions for creating charts/graphs directly in Ruby.

Smalltalk:

It would be a good excuse to get more proficient in Smalltalk.

I prefer working in the Smalltalk environments.

Creating a cross-platform GUI will be easier in Squeak.

While getting multiple processes is a pain (as far as I know, I'd need to run multiple instances of squeak), I can save and quit squeak while the application is running. When I launch squeak, it will start up again exactly where it left off. This may actually be the killer feature. I can run the experiments on my laptop overnight. Even if they don't finish by morning, I can shut things down and take the laptop with me to class--without losing any data.

I'm sure there are a lot of other cool reasons to pick Smalltalk that I just don't know about, because I'm still kind of low on the learning curve.

-Rich-

On Aug 16, 2006, at 10:26 PM, Michael Latta wrote:

There is another approach available in Smalltalk that is not available in many other languages. The syntax of Smalltalk as is allows for a pretty good DSL to be built out of simple classes and blocks with good selector naming. You really do not need to dynamically add code to the system to get a DSL when the syntax for Smalltalk is so flexible and has good readability. You can certainly do "modeling" and generate the code from some other representation. But, then you lose all the value of the Smalltalk tools. If the user wants to model orders just create an Order class and let them go to town with Orderish methods and blocks. Then they can use the best debugger on the planet (that actually works when you want to change the source, etc). You can even persist in-flight execution and many other things that other environments do not support, letting that DSL support more than just in-memory execution. Integrating database accesses and distributed communications is not a barrier.

Michael

-----Original Message----- From: squeak-dev-bounces@lists.squeakfoundation.org [mailto:squeak-dev-bounces@lists.squeakfoundation.org] On Behalf Of Rich Warren Sent: Wednesday, August 16, 2006 6:56 PM To: The general-purpose Squeak developers list Subject: Re: Info on Smalltalk DSLs or Metaprogramming...

In my tests, I've noticed that Behavior>>compile: actually changes the image. Is there any way to make less-permanent changes (e.g. just changing a single instance)?

-Rich-

On Aug 14, 2006, at 6:55 AM, Wilkes Joiner wrote:

...

Here is a blog entry of mine about using the Refactoring Browsers code to generate classes for me:

http://wilkes.blogspot.com/2005/12/simple-code-generation-in- smalltalk.html

The Behavior>>compile: method will add a new method onto a class.

For instance methods: MyClass compile: 'someAttribute ^ someAttribute'

For class methods: MyClass class compile: 'aClassMethod "Do some stuff"'

On 8/14/06, Rich Warren rwmlist@gmail.com wrote:

...

Hi,

I've seen several online articles about writing Domain Specific Languages in Ruby. All the articles mention that the idea of DSLs comes largely from Lisp and Smalltalk. I've found descriptions on writing DSLs in Lisp--but I can't seem to find any good references for Smalltalk.

Does anyone have any helpful pointers? If I'm going to follow the Ruby model, then I need to be able to execute arbitrary strings as code (which Compiler evaluate: and related functions seems to handle). I also need to be able to add new methods to classes/ instances at runtime--which I haven't found.

Any help would be greatly appreciated.

-Rich-

On Aug 17, 2006, at 12:52 AM, David T. Lewis wrote:

On Wed, Aug 16, 2006 at 11:36:33PM -1000, Rich Warren wrote:

...

Ruby can more-easily create actual child processes, which might let me plow through the data faster on a dual-core machine (though, I believe this might lock it into only running on Unix boxes).

Given that you are expecting to run on a unix box anyway, you can do this quite easily in Squeak, see OSProcess and CommandShell on SqueakMap. If you want to run multiple Squeak images on multiple CPUs, look at #forkSqueak.

Aha. Again, it's the low on the learning curve curse. I guess I shouldn't be surprised. Both use the same basic threading model. I should have suspected a similar OS process forking abilities.

But I would be very surprised if you need this in practice. You can manipulate really large amounts of data directly in Squeak, and you'll be amazed how fast it can be. Once you load your data into Squeak, everything is in memory, and Squeak itself is quite fast.

You're probably right, given that using both cores will give me a 2x boost, max (and that's being overly optimistic). So the speed boost you mention might largely compensate. Struggling to get it running on both cores feels like trying to eek out more speed by implementing it in highly profiled and optimized (and therefor non-portable) c code and assembly. I don't need to go down that road.

I do have a few machines on my home network whose idle cycles I could borrow. That's where something like Rinda becomes more attractive. And, if I work out the bugs in my home network, then I could run it on the school's 32-processor cluster. Doing that should give me an order of magnitude boost in speed--which could make a big difference, depending on how many simulations we want to run (I'm guessing at least in the mid- to high- 100s), and how long each simulation will take.

Regarding the DSL itself, I am currently planning on trying to implement it using just classes and methods. Using the config file approach, I'll read in a line at a time, and evaluate each line. But I'll check out SmaCC, just in case I need the extra power.

Thanks,

-Rich-

On Aug 17, 2006, at 7:37 AM, Michael Latta wrote:

You mention that you will be running multiple simulations. Running each simulation in a separate image is far more likely to produce good scalability. You can easily use various methods to move control objects from one image to another to coordinate the simulations and migrate data from one image to another at the beginning of a simulation. I would pursue that approach much more than trying to get 2 cores to run faster.

This is really the approach I was looking at. I'd have a master controller that maintained a pool of available simulations. Slave processes would request a simulation, process it, then asynchronously return the results. The master would be idle most of the time, so the slaves should be able to grab most of the available CPU power (especially if I can place them on separate machines or across a cluster).

I'm not sure how to do distributed processing in squeak though. I'd rather not deal with it at the socket level (though that would be possible). rST looks promising, but I'm a little concerned about its stability (the wiki page says "Testers are needed!" which makes me pause).

The difficulty in finding a good way to do distributed processing surprises me. I thought distributed processing was supposed to be one of Smalltalk's fortes. Which probably means I'm just missing something obvious again.

-Rich-

Hi rich

I would suggest to consider doing that in Smalltalk using the smalltalk syntax as a try and report the problems you get because the syntax of Smalltalk was made for kids and it is uniform and simple.

Can you give an example of what you want to express?

Trial name: 'FirstTrial' resultIn: 'Not so good'

Stef

On Aug 17, 2006, at 6:44 AM, Ramon Leon wrote:

...

All my DSL examples are in Ruby.

For DSL's, Ruby's syntax seems slightly more flexible than Smalltalk (or maybe I just know how to abuse it more).

Might I suggest that Smalltalk itself, isn't so much a language, as it is a notation for creating DSL's. Smalltalk for example, models predicate logic, with simple objects and blocks, no special keywords such as if/unless/do/while are necessary. Ruby can't do this, and requires special syntax in the language, due to its inability to pass multiple blocks and its lack of Smalltalk style keyword selectors. I'm curious where you see Ruby's syntax being more flexible?

Before I get too far into this, let me again point out that my sense that Ruby handles DSLs (as I am currently thinking about them) possibly better than Smalltalk may simply be because I am more familiar with Ruby syntax than Smalltalk. And because I have several good examples that give clear examples of different methods for building Ruby classes/methods/etc. to support DSLs.

So, please, please, please. If anyone knows of any good examples that show how to do these things in Smalltalk, please let me know. That might give me a better handle on how to approach this in Smalltalk, and might just win me over.

First off, I'm talking exclusively about using internal DSLs here. That is, I will be using the natural features of a general purpose language. I'm not talking about building a full-fledged parser/ interpreter. However, I do want to be able to read in and interpret arbitrary text files at runtime.

I think the approach should be similar in both the Ruby and Smalltalk case. Take a line of text. Evaluate it as code in a context so that the individual words in the line get interpreted as objects/messages/ methods/arguments/whatever.

If this is the case, then I can see a few places where Ruby would be simpler. For example, if you're executing text as code within an object, you don't need 'self' when referencing methods. As a result, most Ruby DSLs execute inside objects--I suspect Smalltalk DSLs don't do this.

To me, this seems to imply that in Smalltalk, the first word on each line will typically be a class, followed immediately by either a class method or a constructor. Ruby DSLs can do this as well, but they can also start immediately with a method call on the containing class. That, potentially, gives Ruby a considerable bit of extra flexibility.

Second, in Ruby methods that take arguments do not need to end in a colon. This can help keep the DSL syntax clean, particularly for single-argument methods. Ruby methods can also have default values set for the parameters (which I don't believe is available in Smalltalk), and if the final parameter is a hash, you can use the simplified hash syntax.

On the smalltalk side, I suspect cascading and the separate selector for each argument could produce highly readable DSL syntax--but I'd really like to see a few demo examples to get an idea of how it all fits together.

There may also be ways of doing things in Smalltalk syntax that could make DSLs easier--things that I don't know, or that I'm just not thinking about. For example, I don't see how avoiding if/unless/do/ while really gains anything (especially since 'if' is arguably more human readable than 'ifTrue:'). I also don't see a big gain in passing single blocks vs. multiple blocks. I doubt I'd use blocks in the DSL directly anyway (or 'if' for that matter)--since the block syntax is a bit ugly in both languages--and I can't imagine it being necessary.

Really, I'll probably be implementing something very simple--so it's probably a wash.

It looks like I'll need to set the following information:

Run name, ID, number of agents, target function, max error, visualization on/off, verbose on/off

In Ruby this could be done as follows (calls the new_run method and passes in a hash):

new_run name => 'my name', id => 0, agent_count => 200, target => 30sphere ,error => 1e-10, visualize => true

Since we are passing a hash into the new_run method, these arguments can be in any order. They can also be omitted (the target object presumably sets a default for anything not present).

The same thing in smalltalk would look like this (note, they can be in almost any order--'name:' is a constructor and must come first-- the others can be in any order and can be dropped):

TrialRun name: 'my name'; id: 0; agentCount: 200; target: 30sphere; error: 1e-10; visualize: true

or, for a prettier option (but one that sacrifices flexibility)

TrialRun name: 'my name' id: 0 agentCount: 200 target: 30sphere error: 1e-10 visualize: true verbose: false

None of them are really as readable as I would like, but any would do. The last one is the most readable, but if the number of optional flags started to grow--it would quickly become a real pain.

-Rich-

-----Original Message----- From: squeak-dev-bounces@lists.squeakfoundation.org [mailto:squeak-dev-bounces@lists.squeakfoundation.org] On Behalf Of Rich Warren Sent: Friday, August 18, 2006 4:35 AM To: The general-purpose Squeak developers list Subject: Re: Info on Smalltalk DSLs or Metaprogramming...

Of course, the best ideas always come after I hit the send button.

It dawned on me that I could always preprocess the incoming string on either platform. A relatively trivial amount of code means I could write the (now case insensitive) DSL as:

name: my name, id: 0, number of agents: 200, target function: 30sphere, maximum error: 1e-10, visualize

And have it converted into a simple format for either platform:

TrialRun new; name: 'my name'; id: 0; numberOfAgents: 200; targetFunction: #30sphere; error: 1e-10; visualize: true

Seems to me the difference between

name: my name, id: 0, number of agents: 200, target function: 30sphere, maximum error: 1e-10, visualize

And this

TrialRun name: 'my name'; id: 0; numberOfAgents: 200; targetFunction: #30sphere; error: 1e-10; visualize: true

Are so trivial, why bother with the parsing step at all, just use direct Smalltalk syntax, if kids can learn Smalltalk, so can users of a DSL. As far as samples of DSL's go, I use one daily in the Seaside framework for generating html http://www.seaside.st/Documentation/GeneratingHTML/, and another http://scriptaculous.seasidehosting.st/, for generating JavaScript. Both I think are good examples of embedded DSL's in Smalltalk in daily use.

Rich I would suggest you to read the paper on aconcagua and unit published at OOPSLA and ESUG last year by hernan Wilkinson. They should that extending in a clever way numbers they have a really natural way of expressing units and time. For example, imagine that 1 st, April is a valid Smalltalk expression returning a date.

Then I think that you should pay attention about the assumption tthat you have regarding the syntax your readers can understand. For example I'm skeptical that : is bad for argument. But you will tell us.

Stef

On 18 août 06, at 22:19, Rich Warren wrote:

On Aug 18, 2006, at 6:28 AM, Ramon Leon wrote:

...

...

Seems to me the difference between

name: my name, id: 0, number of agents: 200, target function: 30sphere, maximum error: 1e-10, visualize

And this

TrialRun name: 'my name'; id: 0; numberOfAgents: 200; targetFunction: #30sphere; error: 1e-10; visualize: true

Are so trivial, why bother with the parsing step at all, just use direct Smalltalk syntax, if kids can learn Smalltalk, so can users of a DSL. As far as samples of DSL's go, I use one daily in the Seaside framework for generating html http://www.seaside.st/Documentation/ GeneratingHTML/, and another http://scriptaculous.seasidehosting.st/, for generating JavaScript. Both I think are good examples of embedded DSL's in Smalltalk in daily use.

First, thank you so much for the samples. I'll look at them as soon as I have time.

As far as justifying the parsing step, my main motivation is to have a config file that non-programmers can easily read. I don't want them to have to learn anything (or as little as possible). I would like it to be simple to write or change by hand too--so they can script their own series of trials--but that's a secondary consideration. For the actual trial runs, I'll undoubtedly create a large config file automatically, in order to ensure a thorough coverage of the possible permutations.

But non-programmer readability is the reason I'd love to have multi- word selectors (instead of things_like_this or thingsLikeThis), and the reason I'd like to avoid strange punctuation (like => or the Smalltalk semicolons, or syntax to indicate that something is a string or symbol). And, finally, I'd like to get rid of any unnecessary words (new_run and TrialRun new)--unless I have different types of runs, it's just uninformative boilerplate.

Also, the parsed version could easily be case insensitive, allowing me to switch to something like this (if I thought it added clarity):

NAME: my name, ID: 0, NUMBER OF AGENTS: 200, TARGET FUNCTION: 30Sphere, MAXIMUM ERROR: 1e-10, visualize

Or if I was just varying one parameter, and wanted to highlight it, I could use all caps for just that selector.

But it's only worth it if it's simple to implement. Case insensitivity is trivial. As is stripping off leading (or trailing) boilerplate. Replacing 'number of agents' with 'numberOfAgents' is also trivial, as is switching from commas to semicolons.

The only slightly tricky part is automatically adding quotes to strings and # to symbols--so I may just leave that out.

-Rich-

In Ruby, "See" could be an object, "spot" a method and "run" a local variable.

As far as I know, you couldn't interpret the same thing directly in Smalltalk. You would need to write "See spot: run", which is where the colons become a problem.

Of course, there are other cases where the colon would come in handy.

Having thought about both languages a lot over the last few days, I'm pretty sure of the following:

1. Regardless of which language you use, there will be DSL elements

that appear awkward or clunky (provided you do no string processing).

2. Some things will always be easier to write in the other language.

-Rich-

Ruby might allow parens to be optional allowing run to be sent to spot, however, it'd look more like...

See.spot run

Hardly any better than

See spot: run

Besides, you could always setup spot as a member of see, then...

See spot run

Is perfectly valid Smalltalk, just like Ruby's...

See.spot.run

However you work it, I think the Smalltalk will come up with a more natural English looking syntax due to it using spaces where ruby would use periods and it using periods as a statement separator.

See spot run. Spot go home. Spot wag tail.

Is a perfectly valid Smalltalk statement, can Ruby do that?

Rich Warren schrieb:

Ruby's literal hashes are not great from a non-geek legibility viewpoint, but if you're making a DSL for coders, they're brilliant.

Aren't Smalltalk dictionaries equally legible?

{ 'one' -> 1. 'two' -> 2. 'foo' -> 42. } as: Dictionary

- Bert -

Am 22.08.2006 um 21:22 schrieb Rich Warren:

On Aug 22, 2006, at 2:36 AM, Bert Freudenberg wrote:

...

Rich Warren schrieb:

...

Ruby's literal hashes are not great from a non-geek legibility viewpoint, but if you're making a DSL for coders, they're brilliant.

Aren't Smalltalk dictionaries equally legible?

{ 'one' -> 1. 'two' -> 2. 'foo' -> 42. } as: Dictionary

• Bert -

I'd argue Ruby (can be) a little more streamlined. If it's the last parameter, you don't need any brackets. And it doesn't need the as: Dictionary call.

well, if you insist on getting rid of the brackets in your DSL, this is legal Smalltalk:

'one' -> 1, 'two' -> 2, 'foo' -> 42

Challenge: make that expression answer the dictionary as above

Solution: attached, but try yourself first ;)

- Bert -

Hello group,

I have been reading through the mail list archives and I thought I would share my thoughts as an outsider (at the moment) to the smalltalk community. I appoligize in advance for the size of this email. :)

Computers were not my initial profession, so I came in from a learn-as-you go situation. But I have been in IT over 10 years now and think I have a pretty good idea of a possible silver bullet when I see one. :) Smalltalk seems to be the perfect development environment and what's more; it deserves to be used more then the languages that are used right now.

Before I was an effienciency/static typing junky, but smalltalk has made me rethink the typing at least. :) After all, how many errors *has* that really caught for me compared to all the times code didn't compile because the compiler was confused about something that should work.

Smalltalk even showed me that self generating code could be a good thing. When I first heard of, and thought about the possibilities of this years ago in Perl I cringed. But the reason I cringed was simple: Assembly, C/C++, Perl, Java, everyone else really have two distinct modes: Design mode (where your code is layed out and how) and runtime mode (what it actually looks like as a running system). Self modifying code in this situation is a scary thing because it pushes those two modes even further apart then they were to begin with (which is often pretty far). But smalltalk opened this door for me because it doesn't have that problem. The design and runtime modes are almost the same thing. If I impliment a "doesnotunderstand:" that builds any messages it recieves, let it run for a few days and then come back, the system will have made my methods for me. Then I can take that method out if I want. Amazing. But it's ok, since the source code and the running system are almost one and the same this practice doesn't cloud my view of what the running system looks like.

As I have been looking through the programming languages out there (have been between jobs, so I decided to brush up on my programming a bit) you can't help but see lisp. I know lisp people hate to hear it, but lisp seems like the best of research languages. It seems like every advance in languages came from lisp at one point or another. But it feels like smalltalk has taken the advances and made them usable by the normal man. And smalltalk did the right thing taking the real ideas, not a castrated version of the idea. The exception mechanism for example (see C++, Java, et al), smalltalk has method resumes, restarts, everything.

Perl is the classic case of a sense of loyalty taken too far. A man saves your life (and perl did save us. We were programming CGI in C before it came along and woke everyone up) but as time goes by he has asked to move in with you (perl decided cgi and sys admin wasn't enough, it wants to develop all your apps!) and one day you dont see him anywhere but cloths are all over the floor, perl and your wife are no where to be seen and there is some uncomfortable noise comming from upstairs. But he saved your life right?

Perl is a disgusting hack from top to bottom. It is a filesystem based language like the rest, but even having a source of more then one file is a hack. "Why do I need a 1; at the end of my file again? Oh right, someone somewhere might want their file to execute code when it gets included and in perl TIMTOWTDI! Since they might, we all must? What was that you said about 'simple things simple, hard things...'?".

Ruby is of course appealing because it has something like the smalltalk syntax. But in the end it is a script language and to get where it needs to be to be the best it needs to, well, be what smalltalk is right now.

What about Java? Well you can build anything you want with turds and glue. You can build a big boat, you can build a huge castle, but what do you have at the end? A big smelly pile of crap. That is what Java is in my mind. If the universe is "turtles all the way down", smalltalk is "objects all the way down" and Perl is "hacks all the way down" then Java is surely "inconsistancy all the way down". And just as perl has shown, a million monkeys typing on a million keyboard wont reproduce the works of Shakespeare, and it also wont turn a big pile of crap into a Ferrari. But it might be able to build something to get you to work if you can bear the smell.

So what went wrong? You have the right idea, why isn't everyone here already?

Reading through the list, a few things struck me:

First, Luckas and Andreas fighting over extending functionality vs. backward compatibiltiy. Well, I wouldn't presume to take sides in such an argument, but there are a couple of important points we must always keep in mind: backward compatibility is a noble cause. No one wants to work where they syntax of the language can change before you can even get your program that used the "old" syntax finished. But on the other hand, backward compatibility is an open paracute on your back.

In Estonia in the early 90's it was not uncommon to not have running water. Only about 50% of the population had a phone line. But in 2004 Estonia became the most technologically advanced nation in all of EU, maybe the world. It has the largest % of cell phone users, the government was completley paperless! How did they come so far so fast? Simple: no backward compatibility what-so-ever. No one screamming "Wait! I'm still using windows 3.1, we can't make that change!" No open paracute's on anyones back.

So what is the right answer between Luckas and Andreas? I don't know, but when we talk about backward compatibility, while we dont want to break things just to say we did, we also can't get in a situation that takes 15 years to dig out of. In some cases backward compatibility is the 100% right answer, but in my mind the backward compatibility side has 1 default mark against it. If it is indeed the right answer, then it should be able to overcome this easily, and perhaps this particular argument is just such a case.

Scripting. Do we need it? Well Java doesn't have it. C++ doesn't have it. And those are the two most popular languages afaik. But both of those have huge business backing them. The languages that do *not* have this kind of backing, but are sucessfull are all script languages, or can run in script mode.

How hard would it bee to just make an image that looks a little different then the default image, it expects arguments set up the way they are with typical #! setups? And any syntax chosen needs to look as close as possible to what smalltalk is now. No new strange constructs that are totally different inside the image, no meta-programming as a rule. It needs to look like it does in the browser.

Tim is right, this would be a step back. Smalltalk has a much better environment if you just use the image. But what is more important at this point: being right, or getting a bigger base for the language? I know which one I would pick. I know it's frustrating having the solution and having to stuff it down peoples throats, but if hair dryer companies can put those stupid labels on hair dryers, can't we give a scripting option?

And hey, when a squeakscript user says "By the way, have you guys got any kind of debugger?" Out pops the smalltalk salesman complete with a huge grin and a cheasy suit saying "Why sure! Just run this" and presto, when they see they can change code in the debugger and it just resumes from there, most of them are going to become converts. But first you have to drag them kicking and screaming somehow.

I'm sure the Howard Aiken quote is familiar to all smalltalkers: "Don't worry about people stealing your ideas. If your ideas are any good, you'll have to ram them down people's throats."

What smalltalk also needs is a killer app. Maybe seaside will be that killer app if the inferier language crowd doesn't steal it first.

But no matter how you get them here, it wouldnt matter one bit today because they wont stay. Why? Because smalltalk documentation is like a ghost town. When I found whysmalltalk.com (shows up #4 if you google "smalltalk tutorial") I was excited about all the examples and tutorials. After 90% of the links pointed nowhere I started doing searches on the net to find out if I was simply too late, maybe smalltalk was dead already. And your own squeak site isn't much better. Nothing screams "no one lives here anymore" like dead links. And the more dead links the loader the scream.

One thing I think I disagree with stéphane about (not sure I understand his point exactly) is the releases. If a squeak version is released in the forest and no one is there to see it, will anyone care? Fixing bugs are important if that's what you mean by release. New features to help support those killer aps are important. But if you don't have any documentation anywhere no one will stay. I stayed because I was determined to fix this gap in my knowledge and learn this language, dead or not.

And dont go down the road that "smalltalk is simple so the code documents itself". The code NEVER documents itself, that is a cop-out and a bold face lie. If you don't want to document then for God's sake, hand it off to someone who will. Not every single method ever of course, but anything the API user uses directly should be documented.

And it needs to be consistant too. I'm a "digger", if it is there I will find it. But most people aren't. If your solution is "well go to the class side, there is maybe some method there that documents the class" then you don't have a solution. "Documentation is always on the class side in the 'documentation' protocol (and here is how you find that)" would be much better.

You have a very friendly mail list, the best I've ever seen to be honest. But that doesn't overcome documentation. People are not trained to look on mailing lists for documentation. When thinking about users you have to think Homer Simpson. You can scream "look in the news groups" on every page and he will say "Thanks, what is the link to/program that shows the documentation?".

I hope someone somewhere finds something I said useful. :)

J J wrote:

Java is surely "inconsistancy all the way down".

ROFL

I'm sure the Howard Aiken quote is familiar to all smalltalkers: "Don't worry about people stealing your ideas. If your ideas are any good, you'll have to ram them down people's throats."

Yup, and we Smalltalkers usually are way to polite to do this ;-)

What smalltalk also needs is a killer app. Maybe seaside will be that killer app if the inferier language crowd doesn't steal it first.

Seaside is certainly the killer app in the website application area demonstrating a viable alternative to scripting.

Another one could be Sophie (OK, I'm one of the developers ;-) ).

I hope someone somewhere finds something I said useful. :)

Thank you, thank you, thank you :-)

Michael

Thanks. :) I will go out and look at Sophie. I don't recall hearing about it yet.

And I certainly plan on writing some code once I figure out what is needed. Network Management has traditionally been my space so I had planned on making an SNMP client library if one doesn't exist already. I see telnet already had some packages.

From: Michael Rueger m.rueger@acm.org Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org Subject: Re: Thoughts from an outsider Date: Wed, 30 Aug 2006 11:29:43 +0200

J J wrote:

...

Java is surely "inconsistancy all the way down".

ROFL

...

I'm sure the Howard Aiken quote is familiar to all smalltalkers: "Don't worry about people stealing your ideas. If your ideas are any good, you'll have to ram them down people's throats."

Yup, and we Smalltalkers usually are way to polite to do this ;-)

...

What smalltalk also needs is a killer app. Maybe seaside will be that killer app if the inferier language crowd doesn't steal it first.

Seaside is certainly the killer app in the website application area demonstrating a viable alternative to scripting.

Another one could be Sophie (OK, I'm one of the developers ;-) ).

...

I hope someone somewhere finds something I said useful. :)

Thank you, thank you, thank you :-)

Michael

And there are plenty ways of doing scripting in squeak. For instance the simpler way is to fire up a Squeak server and send it the content of a text file (network cat o nc can be used to do it in a snap) on a pre-defined port. This is totally unsafe, but pretty fast to do. My 5 cents (yes I am coming richer!)

On 30 Aug 2006 14:10:53 +0200, Lex Spoon lex@cc.gatech.edu wrote:

"J J" azreal1977@hotmail.com writes:

...

Scripting. Do we need it? Well Java doesn't have it. C++ doesn't have it. And those are the two most popular languages afaik. But both

[...]

For bigger programs, clearly yes. For small programs, though, it can be much more convenient to use a script file. A file-sized chunk of code is an excellent unit of code exchange. Good tools make this unit of code exchange nice to work with.

There are a lot of things that a script-running program can make easier. For example:

1. Compilation/Loading. You do not have to deal with when to run the

compiler and/or load the code into the running system. The script runner does whatever is needed to make your code run.

2. Dependencies. If your program needs external libraries, at worst

you put a declaration at the top of your file.

3. Integration with other tools. Any tool that can work with text

files can work with script files. CVS, SVN, and pretty much any decent version control system has a convenient way to handle text files. You can even embed script files into programs in other languages. Try these things with an image -- it's possible but takes some work.

-Lex

PS -- If your operating system is Squeak, then yes you can just "do it" to run your code. But for the sake of argument, let's suppose that you are using some backwards non-Squeak operating system that does not use Smalltalk for its system language.

STX has a simple script processing client app. as part of their package. rdoit I think it was called.

Keith

Try it, and you will find that there are a lot of details you have to worry about. Where is the image and VM you use for running the scripts? How do you access stdin and stdout? How do you define methods and classes? Where does the output go when there is a syntax error or runtime error in your script?

These are all simple issues, but there are a lot of them.

-Lex

___________________________________________________________ The all-new Yahoo! Mail goes wherever you go - free your email address from your Internet provider. http://uk.docs.yahoo.com/nowyoucan.html

"J J" azreal1977@hotmail.com writes:

What *does* the image do with arguments it gets on the command line? Would it be possible to add a -s switch to give control over to some kind of script class subsystem?

For the standard image, see:

http://minnow.cc.gatech.edu/squeak/425

Keep in mind, though, that you can certainly have a scripting-specific image, and such an image can do things however you like.

And I don't think the image would have to be scaled down much if at all. The image isn't that big right? And any modern OS will cache it after the first use anyway.

This is one of the last things I would worry about. There are loads of little practical problems with writing scripts, and these are more important than the startup overhead.

To start with:

1. How do you access stdout and stdin?

2. What happens if there is a syntax error or an uncaught exception?

-Lex

But no matter how you get them here, it wouldnt matter one bit today because they wont stay. Why? Because smalltalk documentation is like a ghost town. When I found whysmalltalk.com (shows up #4 if you google "smalltalk tutorial") I was excited about all the examples and tutorials. After 90% of the links pointed nowhere I started doing searches on the net to find out if I was simply too late, maybe smalltalk was dead already. And your own squeak site isn't much better. Nothing screams "no one lives here anymore" like dead links. And the more dead links the loader the scream.

And dont go down the road that "smalltalk is simple so the code documents itself". The code NEVER documents itself, that is a cop-out and a bold face lie. If you don't want to document then for God's sake, hand it off to someone who will. Not every single method ever of course, but anything the API user uses directly should be documented.

And it needs to be consistant too. I'm a "digger", if it is there I will find it. But most people aren't. If your solution is "well go to the class side, there is maybe some method there that documents the class" then you don't have a solution. "Documentation is always on the class side in the 'documentation' protocol (and here is how you find that)" would be much better.

You have a very friendly mail list, the best I've ever seen to be honest. But that doesn't overcome documentation. People are not trained to look on mailing lists for documentation. When thinking about users you have to think Homer Simpson. You can scream "look in the news groups" on every page and he will say "Thanks, what is the link to/program that shows the documentation?".

I hope someone somewhere finds something I said useful. :)

Great post, but one comment. I used to feel the same way, until I realized sample code is the best documentation there is, and alt + n on any method pulls up every reference to that method in the image providing me with plenty of examples of that method in use. The browsers and code have become THE documentation to me at this point and I rarely find I need, or want, anything more than that. I don't think it's a cop out or a lie to say the code is self documenting, it's simply a point of view one comes to hold after working in Smalltalk long enough.

I seem to be off the list at the moment or missing messages so I missed the first post apparently.

The fact is, no matter how obvious the language is there are patterns we use. Sure in some instanses the method can be obvious enough to be understood. But there are plenty of OO patterns that are not obvious if you have not seen them before and sometimes even if you have. You may be able to read from the code what it is doing, but you are going to be thinking "why in the world is he doing this?".

Also, if you work with a pretty complicated subsystem (i.e. uses lots of underlying objects to get work done) do you really find it a good solution to dig through class after class after class just to find out what an interface (i.e. what the subsystem end users use) method does? And even if you do, someone new to the language isn't.

And must every usage of a new subsystem be a trip through every method in that system? Can't I just get a list of what the useful methods are and how to use them?

I appreciate the simplicity of the language, but it is because of this reason one must guard against the false feeling of "self documenting code". You don't have to document every method ever, but ANY interface to the subsystem should be documented some how and any method over a certain number of lines should be documented.

Even if you coded right in pure english, I still wouldn't know *why* you did it the way you did, and therefor I wouldn't know *why* I shouldn't just change it.

From: "Hiren Thacker" hithacker@gmail.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: "The general-purpose Squeak developers list"squeak-dev@lists.squeakfoundation.org Subject: Re: Thoughts from an outsider Date: Wed, 30 Aug 2006 23:17:20 +0530

...

Great post, but one comment. I used to feel the same way, until I realized sample code is the best documentation there is, and alt + n on any method pulls up every reference to that method in the image providing me with plenty of examples of that method in use. The browsers and code have

become

...

THE documentation to me at this point and I rarely find I need, or want, anything more than that. I don't think it's a cop out or a lie to say the code is self documenting, it's simply a point of view one comes to hold after working in Smalltalk long enough.

I do agree completely, even though i m working in smalltalk from few months. And regardlessly Smalltalk code in Squeak image is really much more readable than most languages libraries.

-- Hiren J.Thacker(www.jroller.com/page/daredevihttp://www.jroller.com/page/daredevil l)

[sorry for very bad english :D]

I'm not trying to say you're a fool. It is great that this method works for you. But do you want smalltalk to be for people who tinker or do you want a larger user base? Larger user base buys you more bodies to write code so things get done faster, new killer apps get made. It also buys you more testers and potential bug fixers.

I just don't find "code is the documentation" acceptable at a professional level. Open software tried to say that in the beginning and they were shot down (any that wanted to make money anyway). If you want to play around, take your watch apart to see how it tells time, ok. But if my company has millions of dollars riding on your software there had better be some documentation.

Do really think it would be ok to deliver a product to a customer and say "well, the code is all there, dig around and you should be able to figure out how it works in no time"?

From: "Ramon Leon" ramon.leon@allresnet.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: "'The general-purpose Squeak developers list'"squeak-dev@lists.squeakfoundation.org Subject: RE: Thoughts from an outsider Date: Wed, 30 Aug 2006 11:35:42 -0700

...

The fact is, no matter how obvious the language is there are patterns we use. Sure in some instanses the method can be obvious enough to be understood. But there are plenty of OO patterns that are not obvious if you have not seen them before and sometimes even if you have. You may be able to read from the code what it is doing, but you are going to be thinking "why in the world is he doing this?".

Also, if you work with a pretty complicated subsystem (i.e. uses lots of underlying objects to get work done) do you really find it a good solution to dig through class after class after class just to find out what an interface (i.e. what the subsystem end users use) method does? And even if you do, someone new to the language isn't.

This is the difference between using a framework and using an API, Smalltalkers like frameworks, which by their very nature, require you to understand how they work. You make it sound like digging through classes is hard, it's just a couple keystrokes, browse here, browse, there, check out a few examples, bam, ok, makes sense now. I not only find digging through classes a good solution, I find it's the only one I've ever found that works. Documents lie, code doesn't. I consider understanding how something works, a prerequisite to using it well. And frankly, I can bounce around the code, in a far more organized and faster manner than I could through some document.

...

And must every usage of a new subsystem be a trip through every method in that system? Can't I just get a list of what the useful methods are and how to use them?

If you have a task to perform, you should be able to just browser class names to see who might do that, it's a simple task to quickly check a class for it's responsibilities. Well designed frameworks make this a breeze. As I said earlier, getting a list of the useful methods and how to use them, is only a hotkey or two away.

...

I appreciate the simplicity of the language, but it is because of this reason one must guard against the false feeling of "self documenting code". You don't have to document every method ever, but ANY interface to the subsystem should be documented some how and any method over a certain number of lines should be documented.

Even if you coded right in pure English, I still wouldn't know *why* you did it the way you did, and therefore I wouldn't know *why* I shouldn't just change it.

Self documenting code is not a false feeling, it's a point of view. Smalltalkers in general don't write long methods, so that's not an issue. I find class and method comments, totally sufficient for me to grok how a system works, a quick look at the hierarchy browser, couple of samples of those classes in use, and away I go. I usually find when something is done weird, there is a comment explaining why it was done that way right there in the code, as it should be.

I appreciate that some people want more documentation, that's a valid point of view, but let's not insist that those of us who think the many browsers, classes, categories, method categories, and class and method comments are sufficient documentation are somehow foolish, we're not. Some people need instructions on how to assemble things, others just look at the parts, tinker a bit, and figure it out, Smalltalk is wonderful for those in the latter camp. I'll take being able to look directly at the class over looking at a document any day of the week, it's the best documentation there is as far as I'm concerned.

From: "Ramon Leon" ramon.leon@allresnet.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: "'The general-purpose Squeak developers list'"squeak-dev@lists.squeakfoundation.org Subject: RE: Thoughts from an outsider Date: Wed, 30 Aug 2006 12:19:52 -0700

I don't measure success by the number of people using Smalltalk. Personally, I want Smalltalk to be for people who grok Smalltalk, not for people who want to make it more popular by making it more like everything else. Smalltalk rocks precisely because it's not like everything else, and that includes what is considered programmer documentation. Self documenting code is a style, one smalltalkers prefer, that and some unit tests, are the best documents there are.

I don't want smalltalk to be like everything else. But I do want language choice where I work, and that doesn't happen if the language doesn't have a very big user base. I don't think actually documenting your work will turn smalltalk instantly into Java.

...

I just don't find "code is the documentation" acceptable at a professional level. Open software tried to say that in the

Ok, maybe you don't, but many others do. There's lot's of stuff being done out there in Smalltalk land with little or no "formal" documentation. Documentation the way you define it, simply isn't necessary for success, maybe it's necessary for mass accpetance, but acceptance and success are different things. Smalltalk is already successful, and growing more so every day.

Well I certainly hope it gets more sucessful every day. It certainly deserves it IMO.

...

But if my company has millions of dollars riding on your software there had better be some documentation.

That's an opinion, not a fact, but there's plenty of code out there running on Squeak, and very little if any formal documentation. Success depends on people, not paperwork. You'd be trusting millions of dollars to a person, or a team of people, not some papers.

Yes, but that isn't the issue. The issue is what if you guys leave? If we have nice, up to date documentation of the system the team I have to get to replace you doesn't have to take as long figuring out the system.

...

Do really think it would be ok to deliver a product to a customer and say "well, the code is all there, dig around and you should be able to figure out how it works in no time"?

I thought we were talking about documenting code for programmers, not user documents for products. Was I mistaken?

No you weren't, but I see the two things as close to equivalant. If you wouldn't give software to end users with no documentation, how could you consider it ok if your end users happen to be programmers? I mean, in the case of a subsystem you are delivering an API, but I want to understand what it does without having to basically read the entire code.

I relize smalltalk code writers write small methods, and that is good for the system. But it takes me more time if I have to look up how a method works because the first method (or 3) wont actually be doing the work.

Yes, the version system right as part of the IDE is amazing and powerful. Perhaps the issue we are having is that you are thinking of someone wanting to change the subsystem, and I am (mostly) thinking of people using the subsystem. I have identified that "X" will do what I want, now I have it downloaded, what do I do with it? Unit tests can give me examples but that isn't very formal, you know? :)

(I relize I also mentioned lines of any code over a certain amount, but I can and have been flexable on that point with people I work with).

From: "Darius Clarke" socinian@gmail.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: "The general-purpose Squeak developers list"squeak-dev@lists.squeakfoundation.org Subject: Re: Thoughts from an outsider Date: Wed, 30 Aug 2006 13:04:19 -0700

My single counter point. The code almost never explains how or why something was deleted /out/ of the code because it was Bad.

Don't assume everything in past versions is everything the programmer wrote in that method. Much of what the programmer learned was something he tried/failed and threw away, but which a new user might try /again/ because it was NOT in the code already. All the convenient searching shortcuts begin to fail if you need to find out how code has changed over time as one tries to understand it or how not to redo something bad.

The code also rarely tells you that the code which you may "understand" actually has code smell, is a /bad/ example, or is an archaic style of programming. Java may be inconsistent, but so is the Squeak class library... all the way down.

Sometimes you can't see the forest for the trees.

Cheers, Darius [|] Powered and Empowered by Smalltalk

J J puso en su mail :

Do really think it would be ok to deliver a product to a customer and say "well, the code is all there, dig around and you should be able to figure out how it works in no time"?

When you find such customer ? If the system works, customer never wish know what code you are using, if not, well, one hundred nice write manuals do not save you :)

Edgar

__________________________________________________ Pregunt�. Respond�. Descubr�. Todo lo que quer�as saber, y lo que ni imaginabas, est� en Yahoo! Respuestas (Beta). �Probalo ya! http://www.yahoo.com.ar/respuestas

J J puso en su mail :

No, I meant they application consisted of the user having to figure out to send a MyApplication show. :) It was meant to be an extreme example of "just read the code".

Ok.

As person trying to teach Squeak and spread word in Spanish world, sure I understand you.

And do all what I could, writing some tutorials.

One problem is what Squeak changes so quickly what many becomes obsolete between versions.

Another one is Squeak is a software equivalent of Swiss Army knife.

You have the several spin-offs or forks, like Croquet, Tweak, Sophie, etc.

And so different needs as educational, web development, new object programming ideas, etc.

But all this opens the chance of write "Learn Squeak in ten days", sell many copies and become rich and famous :)

Edgar

__________________________________________________ Pregunt�. Respond�. Descubr�. Todo lo que quer�as saber, y lo que ni imaginabas, est� en Yahoo! Respuestas (Beta). �Probalo ya! http://www.yahoo.com.ar/respuestas

On 8/30/06, Hiren Thacker hithacker@gmail.com wrote:

actually many seniour Squeakers r thr always on #squeak at irc.freenode.net or asking on mailing-list also get very quick reply usually.So i think we can ask, to author or anyone who knows, about *why* you did it the way you did usually.

There are three possible responses when someone makes a complaint: you can address it, you can argue that it's invalid, or you can attack the complainer. I suppose I'm happy that everyone's doing the second rather than the third, but I'd rather we were doing the first.

J J is entirely correct. There needs to be more documentation. Smalltalk is extremely readable, and experienced developers can generally figure out fairly quickly how something works through the Message Finder, Senders Of/Implementers Of, etc., but that ignores the fact that I shouldn't have to do that. What takes me and everyone else an hour each of spelunking through the bowels of the class hierarchy would've taken the original designer about thirty minutes to summarize in a few paragraphs. Those paragraphs should focus on both what and why, and the interplay between those. Even if that documentation is slightly inaccurate, if it at least gives me an insight into the mind of the original developer, my code exploration can be faster, more focused, and more rewarding.

To take a specific example because I know about it, we routinely get questions on the Seaside list about the difference between the legacy renderer and the newer canvas renderer, because there is no real documentation about what problem canvas was trying to solve, how it goes about solving it, what the abstraction is that allows pluggable renderers, whether the user might want ever to write his own renderer, why canvas is still not the default renderer even though nearly all the libraries require it, or half a dozen other small points. You can answer the how and what by googling the mailing list (if you're lucky enough to use the right terms) or by plowing through the voluminous source code and test suites. Even if you do both, though, you still might miss very basic facts that are basically undocumented if you don't happen to hit just the right email message or look at just the right method in your search. (Either #text: or #with: must be the last message sent, for example, or unexpected things happen.) Meanwhile, if you want the why of canvas, you really need to find a single email from Avi from I-don't-know-how-long ago where he announces that a nascent WAHtmlCanvas will be included in an upcoming Seaside 2.5 alpha release and explains in terms that are perfectly clear to Seaside 2.3 hackers why the newer library will be better. The chance of a new user finding that email, let alone truly understanding and internalizing its meaning without already knowing Seaside, is very low.

This problem is obviously not unique to Seaside; thanks to the Seaside FAQ and walkthroughs, Seaside is actually in much better shape than some other packages. I'm harping on it because I'm familiar with it. The problem runs throughout many libraries both in the core of Squeak and in the full image.

Hiren proposes you simply email the list whenever you have a why. That's a waste of everyone's time. The developer has to explain more than once, while users who subscribe to the list have to either preemptively save and categorize important emails or else try to remember enough words from the email that they can google their way to it--and frequently, they give up and ask again anyway. New users, meanwhile, are too scared to ask questions on squeak-dev, which is where you'd have to ask if you really wanted the original coder to respond with a because instead of a more experienced user to respond with a how-to.

Communities that tell their users to RTFM find themselves alone very quickly. We're telling ours to RTFSC. There has got to be a compromise better than that.

--Benjamin

On 8/31/06, Benjamin Pollack benjamin.pollack@gmail.com wrote:

On 8/30/06, Hiren Thacker hithacker@gmail.com wrote:

...

Even if you coded right in pure English, I still wouldn't know *why* you did it the way you did, and therefore I wouldn't know *why* I shouldn't just change it.

actually many seniour Squeakers r thr always on #squeak at irc.freenode.netor asking on mailing-list also get very quick reply

...

usually.So i think we can ask, to author or anyone who knows, about *why* you did it the way you did usually.

Hiren proposes you simply email the list whenever you have a why. That's a waste of everyone's time. The developer has to explain more than once, while users who subscribe to the list have to either preemptively save and categorize important emails or else try to remember enough words from the email that they can google their way to it--and frequently, they give up and ask again anyway. New users, meanwhile, are too scared to ask questions on squeak-dev, which is where you'd have to ask if you really wanted the original coder to respond with a because instead of a more experienced user to respond with a how-to.

Benjamin, I think you are taking my english in wrong context.I think JJ was talking about "Design level Whys" if you read his that post, which i replied."Design level Whys" are not important for everyone using it.You should try to solve your doubts first by excersing own mind, its not necessary to ask for whenever u have a why.

Regards, Hiren Hiren

agree :)

BTW its Rich Warren who says

On Aug 30, 2006, at 8:35 AM, Ramon Leon wrote:

I agree that Smalltalk has excellent tools for sifting through the source code. However, this can be a barrier to entry for newcomers. We need a constant supply of new blood, otherwise Smalltalk will wither and die.

not Ramon Leon

On 9/2/06, J J azreal1977@hotmail.com wrote:

I was talking about all why's (and hows). If you ever hope to hand off your project to someone else those design level why's are going to have to be there. If you want the average person to use it those how's are going to have to be there and some why's as well because they may want to use your classes slightly different then you originally envisioned.

...

From: "Hiren Thacker" hithacker@gmail.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: "The general-purpose Squeak developers list"squeak-dev@lists.squeakfoundation.org Subject: Re: Thoughts from an outsider Date: Thu, 31 Aug 2006 02:03:54 +0530

On 8/31/06, Benjamin Pollack benjamin.pollack@gmail.com wrote:

...

On 8/30/06, Hiren Thacker hithacker@gmail.com wrote:

...

Even if you coded right in pure English, I still wouldn't know *why* you did it the way you did, and therefore I wouldn't know *why* I shouldn't just change it.

actually many seniour Squeakers r thr always on #squeak at irc.freenode.netor asking on mailing-list also get very quick reply

...

...

usually.So i think we can ask, to author or anyone who knows, about *why* you did it the way you did usually.

Hiren proposes you simply email the list whenever you have a why. That's

a

...

...

waste of everyone's time. The developer has to explain more than once, while users who subscribe to the list have to either preemptively save and categorize important emails or else try to remember enough words from

the

...

...

email that they can google their way to it--and frequently, they give up and ask again anyway. New users, meanwhile, are too scared to ask questions

on

...

...

squeak-dev, which is where you'd have to ask if you really wanted the original coder to respond with a because instead of a more experienced user to respond with a how-to.

Benjamin, I think you are taking my english in wrong context.I think JJ was talking about "Design level Whys" if you read his that post, which i replied."Design level Whys" are not important for everyone using it.You should try to

solve

...

your doubts first by excersing own mind, its not necessary to ask for whenever u have a why.

Regards, Hiren Hiren

...

Rich Warren puso en su mail :

I like my mac. I like my mac apps.

Well, Mac in the beginning was a lot different to other common green screens at the time.

Taking to masses only a part of Smalltalk (as was pointed in this same thread).

Now all use some of this concepts.

I wish Smalltalk could be part of that environment.

For Mac exist F-Script, if you still don't have, go for it. And you could have some more Smalltalk way to deal with the system.

For Squeak, you could program for having any look and function as you wish.

Jim Benson do his Zurgle a long time ago....maybe is time someone look at his job and resurrect ?

And it doesn't run on intel macs yet.).

Apple should use the same processor as X 360 Microsof game console. Opening the possibility to hackers to copy most of system for running in cheap clones is a mistake (IMHO) Most world people are too poor to buy a Mac and not for buy a decent clone

Edgar

__________________________________________________ Pregunt�. Respond�. Descubr�. Todo lo que quer�as saber, y lo que ni imaginabas, est� en Yahoo! Respuestas (Beta). �Probalo ya! http://www.yahoo.com.ar/respuestas

Todd Blanchard puso en su mail :

There is also the Objective-C bridge.

-Todd Blanchard

Todd:

What is the last info , some for read, some for try about the Objective-C bridge ?

Thanks

Edgar

__________________________________________________ Pregunt�. Respond�. Descubr�. Todo lo que quer�as saber, y lo que ni imaginabas, est� en Yahoo! Respuestas (Beta). �Probalo ya! http://www.yahoo.com.ar/respuestas

Php makes people feels programmers, squeak (and Smalltalk) just make you realize you're not really one ;) Cédrick

But that you could be!

I agree that Smalltalk has excellent tools for sifting through the source code. However, this can be a barrier to entry for newcomers. We need a constant supply of new blood, otherwise Smalltalk will wither and die.

Idea's don't die, Smalltalk's been around 30+ years, it's not going anywhere.

In general I'm ok just browsing the source code, but I do get upset when someone doesn't even bother to add a class comment. I mean, really. How long does it take to add two or three sentences? A few sentences, that's all I'm asking. A handful of words can save me so much time.

Ditto!

Sometimes, when I'm working with a new framework, it can be hard to find the door in. Once I find the door, I'm golden.

Ditto!

I think there are a couple of other barriers to Squeak in particular. I think the user interface is a huge one. Let's just say, the UI for 3.8 seems a bit...how should I say it...aesthetically challenged. 3.9 looks like it will be a big step forward, but it's still not great.

Easily fixed...

* load LookEnhancements * change SystemWindow borderWidth to 2 * On windows platforms load WindowsNativeFonts * Preferences windows roundedWindowCorners to false * Preferences menus roundedMenuCorners to false * load eCompletion * load Shout4 * hide unused flaps, delete annoying mouse and goofy trashcan * set a nice background graphic (I use mac blue panther graphic)

You're left with a nice professional looking environment with no trace of Squeaks default silliness, windows that look and act decent, including minimizing and maximizing when you double click the title bar, nice intellisense, auto completion and code coloring.

Also, I hate being isolated from the rest of my desktop. I'm a mac user. I like my mac. I like my mac apps. I wish Smalltalk could be part of that environment. Visual Works

I sympathize here, I both love and hate that squeak's its own little world. I've adjusted by dedicating one monitor to squeak, and one to windows, but I do wish someone would solve this problem. I don't mind squeak having it's own windowing system, it's nice to be able to work on a Mac, a pc, and a Linux box all in the same environment, but it'd be nicer if a morph floated over the native desktop.

Thanks for this list.

Call me stupid, but I can't figure out what to do to "change SystemWindow borderWidth to 2". Can you give me a hint?

Literally, I meant, go there and edit the code, from 4 to 2. The default borders are far too fat and make squeak look silly.

Also, is there a way to get rid of the shading of background windows - rather just shade the title bar or something?

Thanks, Steve

Not sure what you mean here.

Sometimes I forget what it's like to be a newbie, too, but sheesh! :-) (pardon me if you're not so new, Stephen, I haven't been reading squeak-dev extremely closely)

In case "edit the code" wasn't enough of a hint, here's how I figured it out:

• browse to SystemWindow
• with the 'inst var defs...' menu item, find all of the

places that the 'borderWidth' instance variable is set

• hmm, #borderInitialize looks promising, so browse to it
• see that the initial value is defined by #defaultBorderWidth
• override the implementation of #defaultBorderWidth, and you're done!
• open a browser to test it out

Rats! It didn't work. OK, let's debug...

• inspect the result of 'SystemWindow new' in a workspace.

Yep, borderWidth didn't change. Why not?

• highlight the expression again and choose the 'debug it' menu item
• step into the expression and see that the first message

sent is #hasPrototype. Sounds suspicious!

• select 'self' in the lower-left debugger pane, and choose

'inst var defs...' from the menu to see who defines 'prototype'

• there's a prototype message; let's clear the prototype with:

'SystemWindow prototype: nil'

Now it will surely work! But it doesn't. To make a medium-length story short, SystemWindow>>initialize stomps on the value that had been properly set by the superclass.

I suppose that this is because I didn't load LookEnhancements first; otherwise, the above would probably work. But I don't care enough to try. BTW, this is in a Croquet image that's basically 3.8 as far as Morphic is concerned.

Anyway, I guess I've shown that it's not completely trivial. Even if I had loaded LookEnhancements first, it seems likely that the prototype problem would have arisen. Hopefully someone learned something about Squeak debugging.

Cheers, Josh

Wow, I didn't realize I was so unclear, my bad. First, load LookEnhancements, then go to SystemWindow, there is an accessor on the class side called borderWidth, edit it, change it to 4.

From: "Ramon Leon" ramon.leon@allresnet.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: "'The general-purpose Squeak developers list'"squeak-dev@lists.squeakfoundation.org Subject: RE: Thoughts from an outsider Date: Thu, 31 Aug 2006 08:44:06 -0700

Idea's don't die, Smalltalk's been around 30+ years, it's not going anywhere.

But it needs to go somewhere. To the head of the pack where it can improve our profession. Software engineering is joked out by other engineering professions because of how bad so much of the engineered software behaves. I think smalltalk becoming one of the prominant languages goes a long way to address that.

Easily fixed...

• load LookEnhancements
• change SystemWindow borderWidth to 2
• On windows platforms load WindowsNativeFonts
• Preferences windows roundedWindowCorners to false
• Preferences menus roundedMenuCorners to false
• load eCompletion
• load Shout4
• hide unused flaps, delete annoying mouse and goofy trashcan
• set a nice background graphic (I use mac blue panther graphic)

You're left with a nice professional looking environment with no trace of Squeaks default silliness, windows that look and act decent, including minimizing and maximizing when you double click the title bar, nice intellisense, auto completion and code coloring.

Thanks for that. Is there a way to turn those changes into a squeakmap package like they did with the "seaside installer" and "pier" packages? Or would it be possible to turn into a theme somehow?

Also, after I did all those things the debugger doesn't highlight code right anymore. I can't tell exactly what code is running because the highlight is in the wrong place.

Has anyone else seen this?

Ok, great thanks. Where are people getting 3.9 from? Is it pretty stable? I mean lots of things don't seem to work on 3.8 anyway (e.g. the balloon3d fish tutorial) so it doesn't have to be perfect.

Also, any idea when it will be officially released?

Thanks again

From: "Andrew Tween" amtween@hotmail.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: "The general-purpose Squeak developers list"squeak-dev@lists.squeakfoundation.org Subject: Re: Thoughts from an outsider Date: Sat, 2 Sep 2006 12:39:17 +0100

Hi J J, ----- Original Message ----- From: "J J" azreal1977@hotmail.com To: squeak-dev@lists.squeakfoundation.org Sent: Saturday, September 02, 2006 11:56 AM Subject: RE: Thoughts from an outsider

..snip...

...

Also, after I did all those things the debugger doesn't highlight code

right

...

anymore. I can't tell exactly what code is running because the

highlight

...

is in the wrong place.

Has anyone else seen this?

Yes. It is a known bug in Shout. The latest version on SqueakSource fixes this, but hasn't been released onto SqueakMap yet. You can get it from here...

http://www.squeaksource.com/shout/Shout.3.15-tween.65.mcz

Note that this version is intended for the current 3.9, so if you are using 3.8, then it is best to stick to the old SqueakMap version. You can also 'fix' the debugger problem by disabling (i.e. unselecting) both of these Preferences

• syntaxHighlightingAsYouTypeAnsiAssignment, syntaxHighlightingAsYouTypeLeftArrowAssignment

Cheers, Andy

On Aug 31, 2006, at 2:35 AM, Rich Warren wrote:

Also, I hate being isolated from the rest of my desktop. I'm a mac user. I like my mac. I like my mac apps. I wish Smalltalk could be part of that environment. Visual Works gets a few points here. At least it looks like a native interface (Though, the UI doesn't behave in a consistently native manner--which can actually be more annoying sometimes. And it doesn't run on intel macs yet.).

FScript (mentioned already) & Ambrai Smalltalk http://www.ambrai.com/ are two nice smalltalk frameworks for interacting & constructing apps using the cocoa framework. Fscript is the scripting variant & Ambrai is closer to a full-featured smalltalk.

Eric

On 31-Aug-06, at 4:45 PM, Rich Warren wrote:

The biggest UI problem I have is the fact that Squeak's private window really mucks with my regular work flow. Typically I use Expose a lot--it lets me move effortlessly from window to window (I know, a lot of people don't like Expose--my wife can't stand it. But it really works for me). I can move between apps very quickly. I can also move between all the windows of a single application.

There would be a very big efficiency gain if I could manage my Squeak windows the same way I manage my other Mac windows.

There are at least two ways you could achieve this: a) wxSqueak b) Ariethfa Ffenestri

wxSqueak uses the wx-whatever libraries as the platform layer and so should work on any platform with wx support. Which isn't every platform, but quite a few. Ffenestri (it's Welsh for 'platform windows') provides a relatively simple and very low-level interface to ... platform windows. You can/ could open arbitrary host os windows and then draw in them with whatever means you like. When developing it we tested with several sets of connection to the image but it is essentially a case of you get a window object and you bitblt to it.

I think this can be generalized to all UI interactions. The more the UI for Squeak resembles the underlying UI of the host OS, the more efficient you can be. You can have a UI that is enhanced above and beyond the host OS--as long as it follows the same behaviors as the underlying OS, users can leverage their existing knowledge and skills while working in Squeak.

Now that I don't think I can agree with entirely. Yes, for ordinary usage using host style is beneficial. For enhanced UI designs I'm going to assert (because I'm a big bossy noisy person with no mild opinions) that you really need to almost forget whatever your host OS does because they are *all* crap. Every one of them. All of them have some good points, and all of them have many more bad. Don't get me started on menubars. Really. If it were possible to write down the most suitable curses about menubars in the original pictograms, the baked clay would melt.

Anyway, try wxSqueak if you want a substantially platform-like experience and consider Ffenestri if you want to have a chance to make something compatible(ish) but to your own taste.

tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Satisfaction Guaranteed: We'll send you another copy if it fails.

Rich Warren puso en su mail :

The biggest UI problem I have is the fact that Squeak's private window really mucks with my regular work flow. Typically I use Expose a lot--it lets me move effortlessly from window to window (I know, a lot of people don't like Expose--my wife can't stand it. But it really works for me). I can move between apps very quickly. I can also move between all the windows of a single application.

There would be a very big efficiency gain if I could manage my Squeak windows the same way I manage my other Mac windows.

As I say, you could have any UI . Someone did a Expose like in Squeak, a long ago, but I don't remember who. Or use John Mac AppleScript hooks for raise real Mac UI elements or use Mac Services or use Unix under the hood power.

Edgar

__________________________________________________ Pregunt�. Respond�. Descubr�. Todo lo que quer�as saber, y lo que ni imaginabas, est� en Yahoo! Respuestas (Beta). �Probalo ya! http://www.yahoo.com.ar/respuestas

Rich Warren puso en su mail :

Remember, I'm talking about barriers to entry. Things that might make a newbie look at Squeak, but turn away. The user interface (as provided) is (for many people) a barrier to entry. Most of us get over it, but it's still a barrier

If things do not change , progress do not happen.

Myself argue against Traits, a long ago, as having Traits cause breaks with older Squeak and introduce several collateral things , unneeded for normal projects (IMHO)

My solution is continuing develop SqueakLight, a hand made image what now do what I wish.

But at the same time , I continue studying, and now try to help the process leaded by Pavel for in a future have a more modular Squeak what starting from a unix like console (kernel.image) , could grow to any "app" , loading what was needed from Web.

You should lobby for a "New Squeak UI" group. Take a look to clever work of wonder people working on Sophie, and help for things like Rome finish the travel and could be used by mortals in 3.9 (or 3.10)

Edgar

__________________________________________________ Pregunt�. Respond�. Descubr�. Todo lo que quer�as saber, y lo que ni imaginabas, est� en Yahoo! Respuestas (Beta). �Probalo ya! http://www.yahoo.com.ar/respuestas

On Sat, 02 Sep 2006 13:41:52 +0200, J J wrote:

I agree that traits wont come up normally. But as soon as you get into big complicated heiarchies traits are probably going to be a better fit. Not only that, I have seen a lot of people ask for protocols to be actual queriable objects. That seems to be about what traits are afaik.

... besides that software composition with traits no longer needs to follow the hierachical (subclassing) path ...

Many things smalltalk has are just better versions of what everyone else has. I think things like this are what everyone will be trying to steal tommorow when they finally arrive where smalltalk was years ago and see what the problems are.

Refreshing :)

/Klaus

Sorry for being away the last few days (work related). I didn't intend to throw grenade in and then just leave. :)

To start off I decided to address this point first:

On Aug 30, 2006, at 8:35 AM, Ramon Leon wrote:

I agree that Smalltalk has excellent tools for sifting through the source code. However, this can be a barrier to entry for newcomers. We need a constant supply of new blood, otherwise Smalltalk will wither and die.

Or maybe just tread water when it should be leading the pack. These two possibilities are pretty much equivalant in my mind.

Also, I hate being isolated from the rest of my desktop. I'm a mac user. I like my mac. I like my mac apps. I wish Smalltalk could be part of that environment. Visual Works gets a few points here. At least it looks like a native interface (Though, the UI doesn't behave in a consistently native manner--which can actually be more annoying sometimes. And it doesn't run on intel macs yet.).

You points on the environment look are certainly valid (though I don't mind it personally). As far as isolation from the rest of the desktop, let's look at how everyone else does it.

In Java, C++, Ruby, Python, et. al. how does one build an application? 1. Determine what your application consists of (or what you think it does) 2. Identify what code has already been written in this area (and hopefully us squeakmap like app to download/install it) 3. Forevermore remember to import/#include/re/whatever to get the code you want visable to your system 4. Develop the code (glue together the components, try new components, etc) 5. Package it up and deliver it to the customer.

Now many times you wont identify what you need in step 2, you will see some *possibilities*. You may have to try out several of them to see what will work. When you change one implimentation for another you have to remember to go and remove all the references to the previous component.

How does smalltalk do it? The same as above, just remove step 3. The cost is that step 5 gets more complicated.

Stated another way; the approach used by other languages is start writing one or more files that may use one or more files to build up your application. The smalltalk approach is to build the application from *within* the application you are writing. For every new app you write the image *is* effectively this new app until you deploy it. At which point it becomes the next app you will wright and so on.

Smalltalk is the only one to get it right IMO. When someone sets out to build a car, airplane, building or whatever they build the peices they need and make schematics to describe the different components. Once a built component is used in a product it is gone and must be rebuilt for the next product. Not so with digital media. Once we have the component we have it from then on, no more component assembly required. Manufacturing companies have spent lots of money developing special assembly lines to get as close as they can to what we have for free.

Conventional programming languages have this also, but the components are laying somewhere in a huge garage, you have to go dig all over for them. In smalltalk you just say "Hammer hitNail" and it is magically in your hand, unless you never went and got one in the first place. But once you get it you have it.

When you build the smalltalk application you get all your classes working right, save the image, then do step 5: remove everything you are not using. This seems right to me, it is consistant with the concept of garbage collection: it is faster over all to do cleanup all at once instead of every time you change something (e.g. removing import statements for components that turned out not to work for you). And it can all be done programatically, as opposed to the by hand method required with other approaches. So if something doesn't get taken out that you thought should have you can go find out why. More bug protection.

Now, after you deploy the application you start your image up and guess what, the application you just deployed is still there. So now when you make a new application it is really simple to refactor the common parts together. I did this with some of my programs in Borland C++ builder. It worked, but it was much more complicated then just making a few new classes and doing a little refactory.

In fact, *every* application that you or anyone else has written is available in your image. Including applications for debugging, playing MPEG's and everything else. But that is ok because these applications will help you build the next application you are working on (well, some will help more then others. :) and it can be automatically removed before you deploy.

If the image feels isolated from the rest of the desktop it is because you have never been able to do this before. :)

From: Rich Warren rwmlist@gmail.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org Subject: Re: Thoughts from an outsider Date: Sat, 2 Sep 2006 21:25:18 -1000

I'm not sure what this has to do with isolation from the rest of the desktop. Let me be clear, I wasn't talking about developing/coding issues, I was talking about using the UI.

While I'm coding, I inevitably need to check my e-mail, browse web pages, whatever (as research, of course--I'm not just playing around). I want to use those (and other tools) on my mac. Having the Squeak UI isolated from my OS UI makes rapid shuffling between browser windows and native OS tools more difficult than is absolutely necessary (at least for the way I typically work).

Also, having a separate UI means I need to learn two UIs. I have to constantly shift between the UIs. I have to maintain separate mental lists of efficiency tips for each UI. I have to remember which keystrokes go with which environment. Again, more work than is strictly necessary.

-Rich-

Well what I meant was working in a smalltalk environment is like developing your next app from within the app you are building. So I think you would feel the same isolation if you could develop from inside of your web browser for example.

But as far as wishing the tools that exist in the image behaved like your normal GUI, can something be done with themes? Is anyone looking into making themes or something like that be set up in such a way that I could set them to "Mac" and now my image behaves like a mac or "WinXP" and now it behaves like XP?

From: Rich Warren rwmlist@gmail.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org Subject: Re: Thoughts from an outsider Date: Mon, 4 Sep 2006 19:44:44 -1000

Just to bring this full circle. Now that I've been using Squeak for a while, I've grown used to it's UI. I find that using QuickSilver, I can still pop out of a full-screen Squeak session with just a few keystrokes, check the email message that relates to the problem at hand, do a little web research on the topic, then slip right back into Squeak. But this involved bending my normal workflow around Squeak (where, ideally, Squeak would just slip transparently into my regular workflow). Even if Visualworks was running on intel macs, I would probably keep coding in Squeak. However, the UI was a real barrier to entry, and it can drive off new users (which was my original point).

-Rich-

Well then, I reassert my previous question: Is it possible for someone to do something with themes? Is there a way to have "WinXP" theme, "Mac" theme, "Smalltalk-80" and "Squeak" themes that change everything to behave how one would expect in those environments? And maybe by default the theme is selected based on the platform?

On Sep 5, 2006, at 5:21 AM, tim Rowledge wrote:

On 4-Sep-06, at 10:44 PM, Rich Warren wrote:

...

Just to bring this full circle. Now that I've been using Squeak for a while, I've grown used to it's UI. I find that using QuickSilver, I can still pop out of a full-screen Squeak session with just a few keystrokes,

I don't understand why you would choose to use Squeak fullscreen if you want to feel connected with your OS; it seems like a strategy almost guaranteed to make the worst of squeaks' use of a single window. I don't think I've used fullscreen form since 1989 - and before then it was simply impossible to do otherwise because my OS simply didn't have other windows!

Space for more windows. Space for organizing windows. There's never enough space.

I've gotten lazy on my mac desktop. I can have dozens of windows open and because of the way I work (a combination of Quicksilver and Expose) I can dance between them with ease.

When working in Squeak, I like to have as similar a setup as possible. I often have two or three browsers open (all on different parts of code). I will have at least one workspace and a transcript-- at a minimum. Other windows rapidly accumulate.

It's not as easy to shuffle between windows, so I like to lay them out so they are as visible as possible (or so it's easy to bring the desired window to the foreground with a single mouse click).

Quicksilver and Expose make this a partial solution. I can still jump from Squeak to my desktop and back with ease. What I can't do is place a small browser window over a near-full screen safari window, so I could reference information from a web page while I code without having to move anything.

-Rich-

(Just to be clear to everyone who has already commented on possible solutions for this, I'm not ignoring you, I'm just trying to answer the question at hand.)

On 30-Aug-06, at 1:34 PM, Ramon Leon wrote:

...

Communities that tell their users to RTFM find themselves alone very quickly. We're telling ours to RTFSC. There has got to be a compromise better than that.

--Benjamin

I never said documentation was bad, I was simply responding to the invalid accusation that the Smalltalk style of self documenting code is wrong, or that we're copping out or lying made by JJ below...

...

And dont go down the road that "smalltalk is simple so the code documents itself". The code NEVER documents itself, that is a cop-out and a bold face lie.

Well I have bit of experience in Smalltalk and I find myself substantially in agreement with JJ here. Sure, senders and implementors are fabulous tools to have but they offer nothing to help understand what is likely to happen with exceptions and very little for Tweak signals etc. No amount of staring at source code will tell you what the author might have *wanted* the code to do, nor what misbegotten changes somebody made after misunderstanding the intent of the code at a later point. Source code tells you what *actually* happens, not what is *meant* to happen. Anybody that tries to tell you that the code does exactly what it it supposed to is almost certainly lying.

Comments in methods ought to offer some help in decoding the expectations for the method as a whole, or for parts of the method. Class comments ought to offer a somewhat higher level view of what the class is supposed to do and the limitations it is known to have. Other forms of comments and documentation are needed to give later authors some hope of being able to use, maintain and improve the system. You need tutorial type documentation to offer newcomers to a part of the system a chance of getting some sense of the system before they can even begin to understand the actual code.

Adele Goldberg expressed it once as "if the code isn't documented, it doesn't exist" since without reasonable doc there is no way to count the code as usable in the long term. I tend to add the corollary clause "and if it doesn't exist, what did we pay you for?"

Another old friend of mine has also coined the rather nice idea of "program the document, don't document the program" to cover a concept of merging doc and code in the tools so that you can write spec, explanation, commentary, examples and limitations mixed in with executable code. It's not hugely different to some aspects of the late Jef Raskin's idea of The Humane Interface (see http:// www.raskincenter.org) and it wouldn't be too awful implemented as a nice document editor that has a style for 'source code' that actually means source code rather than just using a fixed pitch font. Hmm, now where might we find a document editor with intimate associations with a compiler?

tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim A)bort, R)etry or S)elf-destruct?

Damien Pollet schrieb:

On 8/31/06, tim Rowledge tim@rowledge.org wrote:

...

Another old friend of mine has also coined the rather nice idea of "program the document, don't document the program" to cover a concept of merging doc and code in the tools so that you can write spec, explanation, commentary, examples and limitations mixed in with executable code.

Sure, literate programming is a nice idea but even if there is the wonderful example of TeX to support it I'm not sure it's agile enough in it's current form to be smalltalker-compliant :-)

A long time ago, when I re-implemented a big chunk of TeX in VisualWorks to create a WYSIWYG TeX editor (WysiTeX), we tried to do something like literate programming in Smalltalk. My idea was that a Smalltalk literate program could not possibly have the form of a linear book, since Smalltalk programs are essentially not linear, so we tried to create a hyperlinked documentation (using a collaborative hypertext editor also written in VisualWorks). I was not really satisfied with the result - it did not have the close linkage to the code, and I don't think that an outsider would have been able to grok our code with the help of this doc bettern than without it.

That said, I still feel that something like that would be needed. Since working with Objectory a number of years ago, I became enamoured with the idea of traceability - having explicit links between analysis, design and code. Objectory was a little too waterfallish, an agile tool would probably have to look a bit different, but still I think that a really good development environment should be able to keep all this information in one place, allowing me to create and follow links, to store document files, drawings, diagrams as well as runtime, building and test code in one place, with version history all over the place, too.

I know that such a system would not help me much in writing better method comments (that's still a matter of discipline which I'm a bit lacking) but it would probably allow me to create overview documents which allow others to get into the code much more easily.

Cheers, Hans-Martin

Literate programming (the program as a textbook) looks very interesting, but it didn't work for me because it is based on a fundamental misunderstanding: A textbook teaches a stable and well understood subject. A program is neither. (But it will be interesting to study simon's ref. to darcs.)

In the early eighties, a colleague and I did a substantial development job using literate programming. The program itself was a success, but literate programming was a flop.

We started from a very powerful multimedia authoring tool. We added three new media: Smalltalk class and method definitions + workspaces.

We could print the document with its embedded code; we could compile the document and even run tests that were specified in the document. The project was to develop the OS-like core of a family of applications. It is still alive more than 20 years later.

Literate programming worked beautifully for many months. We wrote a textbook describing our program, including descriptions of why we did things in a special way and why some tempting optimizations were very dangerous. We were doing pair programming and found that we were very motivated to write down what we were doing while we were doing it. The next day was too late.

But after more than a hundred pages of literate programming, we found that we needed to do some refactoring. But that would require a rewrite of several chapters in our book. We just couldn't do it. The program changes were fairly small, the book changes substantial. Even the main chapters had to be rearranged. We ended up with adding appendixes with overrides on previously written stuff. A total mess. (We even wrote an OOPSLA paper reporting it: T. Reenskaug and A. L. Skaar. An environment for literate smalltalk programming. ACM SIGPLAN Notices, 24(10):337--345, October 1989.)

Don Knuth dreamt about a program that was like a textbook. He even wrote one. But in general, the analogy doesn't hold. A textbook is written over a well known theme. The substance is stable, the presentation is new. A program is not stable in this sense; its substance is a moving target. So the textbook metaphor simply does not apply. Has anybody tried to modify Knuth's original program?

Cheers --Trygve

At 10:19 31.08.2006, Klaus wrote:

Hi Hans-Martin,

I am very interested in having code as (integrated) part of a document. The following describes minimally what I want from a document+with+code, a "... two-phased approach that continuously synchronizes between a data modeling view and a view on an object-oriented implementation". There we see

• a domain analysis view, represented by a data modeling diagram
• implementation objects, related to OO programs at code-time
• population objects, derived from the former, containing actual data for

running

Found at

• http://prog.vub.ac.be/progsite/Person.php?rdid=25070

I wouldn't care if this where called literate programming or so, as long as round-trip engineering allowed me to put comments anywhere I want :)

/Klaus

On Thu, 31 Aug 2006 07:41:16 +0200, Hans-Martin Mosner hmm@heeg.de wrote:

...

A long time ago, when I re-implemented a big chunk of TeX in VisualWorks to create a WYSIWYG TeX editor (WysiTeX), we tried to do something like literate programming in Smalltalk. My idea was that a Smalltalk literate program could not possibly have the form of a linear book, since Smalltalk programs are essentially not linear, so we tried to create a hyperlinked documentation (using a collaborative hypertext editor also written in VisualWorks). I was not really satisfied with the result - it did not have the close linkage to the code, and I don't think that an outsider would have been able to grok our code with the help of this doc bettern than without it.

That said, I still feel that something like that would be needed. Since working with Objectory a number of years ago, I became enamoured with the idea of traceability - having explicit links between analysis, design and code. Objectory was a little too waterfallish, an agile tool would probably have to look a bit different, but still I think that a really good development environment should be able to keep all this information in one place, allowing me to create and follow links, to store document files, drawings, diagrams as well as runtime, building and test code in one place, with version history all over the place, too.

I know that such a system would not help me much in writing better method comments (that's still a matter of discipline which I'm a bit lacking) but it would probably allow me to create overview documents which allow others to get into the code much more easily.

Cheers, Hans-Martin

At 14:45 02.09.2006, Klaus wrote:

If you set "classic documentation" := "your doc book approach" then I cannot see any difference to what's up nowadays: the doc is always the first *or* the next component which is outdated.

/Klaus

Of course not. I am talking about literate programming as proposed by Don Knuth. Classic documentation is different.

Cheers --Trygve

On 9/2/06, J J azreal1977@hotmail.com wrote:

Perhaps a javadoc type tool could be written that generates documentation from the code itself?

<SNIP>

Something like Dandelion? http://www.mars.dti.ne.jp/~umejava/smalltalk/stClasses/dandelion/

Chris

Am 02.09.2006 um 12:30 schrieb J J:

I must say, this sounds promissing I think. I don't know how you guys are finding this stuff. :)

Well, some of us are around for ages and can still remember stuff ;)

The last update seems to be from 2004, is this a project without an owner atm?

Masashi Umezawa is still around AFAIK, but like most Japanese developers he is not active on squeak-dev. You might want to drop him a mail.

...

http://www.mars.dti.ne.jp/~umejava/smalltalk/stClasses/dandelion/

- Bert -

Well I hope you had a great trip! Those things you suggest sound good to me. And thanks for your contributions. :)

From: "Masashi UMEZAWA" masashi.umezawa@gmail.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: "The general-purpose Squeak developers list"squeak-dev@lists.squeakfoundation.org Subject: Re: Thoughts from an outsider Date: Wed, 6 Sep 2006 16:54:10 +0900

Hi,

Sorry for the late reply. I was disconnected from the net for a while. (long trip to Prague (ESUG)).

I think Dandelion is in a sort of stable state. Although I have a few things that I would like to add, the priority is not so high for me. (But if there are real demands, I would do the action).

What I'm thinking are:

• The new release should be a MCZ based SAR file
• Support of analysis of MCZ packages
• Embed auto generated class graphs in html output
• Add code metrics analysis and CSV output

2006/9/3, Bert Freudenberg bert@freudenbergs.de:

...

Am 02.09.2006 um 12:30 schrieb J J:

...

I must say, this sounds promissing I think. I don't know how you guys are finding this stuff. :)

Well, some of us are around for ages and can still remember stuff ;)

...

The last update seems to be from 2004, is this a project without an owner atm?

Masashi Umezawa is still around AFAIK, but like most Japanese developers he is not active on squeak-dev. You might want to drop him a mail.

...

...

http://www.mars.dti.ne.jp/~umejava/smalltalk/stClasses/dandelion/

-- [:masashi | ^umezawa]

Am 02.09.2006 um 14:00 schrieb Michael Rueger:

J J wrote:

...

Perhaps a javadoc type tool could be written that generates documentation from the code itself? I'm not sure I understood your first example perfectly, but it sounded like a javadoc type system might have solved the problem. That is; yes if I have to go

We have had this sitting around basically unused for way too long:

http://source.impara.de/squeakdoc

It generates DocBook XML that then can be either used in a wiki like system as the one we set up at http://squeakdoc.impara.de/external/

and/or converted to e.g. HTML.

Hmm, just realizing the only doc we have is in German... Will translate the main things...soon?...

Actually, the Squeak Doc documentation itself (in Books - Test Category) is in english.

- Bert -

Let me point out two recent literate programming successes -

1. darcs. The (haskell) code and (latex) manual are intermingled and maintained as a single unit to very good effect. See the manual at http://darcs.net .

2. ruby. http://www.ruby-doc.org/core and http://www.ruby-doc.org/stdlib present current, accessible API docs and also higher level docs with very little fuss. These are generated from extensive code comments, READMEs, etc. (Many other languages do this but less effectively.)

Cheers, -Simon

PS I really like this thread.

On 4-Sep-06, at 7:06 PM, Ramon Leon wrote:

If you can generate the docs from the code, of what additional value is the doc?

Modulo the quality of the comments in the code that are being used, it's the presentation that can make the difference. A form of browser that can gather linked comments from methods and classes and present them in a neatly intelligible form is surely an improvement over scattered snippets?

But don't forget that crucial first clause above about the quality of the source material.

tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Useful random insult:- Always loses battles of wits because he's unarmed.

Ramon Leon ramonleon@cox.net writes:

...

Modulo the quality of the comments in the code that are being used, it's the presentation that can make the difference. A form of browser that can gather linked comments from methods and classes and present them in a neatly intelligible form is surely an improvement over scattered snippets?

Is not the standard Smalltalk browser such a browser? How would some other browser, using the same data, be able to somehow present the information better than the Smalltalk browser? If such a great feature existed, wouldn't we simply add it to the existing Smalltalk browser?

It is, Ramon. The Smalltalk browser, specialized to its task, is way better than a generic web browser. Furthermore, the Smalltalk browser is *integrated*, meaning you can flip seamlessly between browsing, executing, coding, and debugging. The Squeak debugger can put you into the Squeak browser, and the Squeak browser can execute things for you (and IMHO it could profitably do more of that....)

Ruby and Java, having no such browser, must use a generic tool (HTML) and their integration cannot be as nice. Smalltalk is way ahead of its time with its code browsing.

Incidentally, I would not be complacent -- there is always room to add new or better browsing views to Squeak. It would be worth looking through the output from the various FooDoc programs and checking that Squeak includes analogous views for all of them that matter.

Also, it is well worth looking at the hyper-linking within the browser. It would be better if the context menus of Squeak were actually context-sensitive to what has been highlighted, so that you can offer good browsing choices. Instead of "inst var defs" and then select the variable, it should be possible to highlight the variable and then "defs of THIS inst var" is on the context menu.

To get ideas about this, just check out Eclipse....

-Lex

Hi,

From the author's point of view, Dandelion is basically a tool for generating

inter-operable meta models in various formats. HTML output was actually just an sample, though I added some frills.

For just browsing Smalltalk code, I think SystemBrowser is better.

The advantage of Dandelion is abstraction. For example, it stores analyzed code info in a repository. The analyzed data is independent of the current code and it can be retrieved later for further analysis.

2006/9/5, Ramon Leon ramonleon@cox.net:

...

2. ruby. http://www.ruby-doc.org/core and http://www.ruby-doc.org/stdlib

present current, accessible API docs and also higher level docs with very little fuss. These are generated from extensive code comments, READMEs, etc. (Many other languages do this but less effectively.)

I can't help but point out how much Ruby's doc's are just imitations of a Smalltalk class browser. How exactly is this better than class and method comments in Smalltalk directly? How is dandelion better than a real browser either? If you can generate the docs from the code, of what additional value is the doc?

And what about UML diagrams? Isn't that just duplication too? I mean all it is is a different view of what the code says right?

Look, despite my strong feelings about so called "self documenting code" I am laying off. If you want to work that way fine, but shouldn't you extend my "side" the same honor of not trying to impose your way on people who want some kind of documentation that is meaningful for us?

From: "Ramon Leon" ramon.leon@allresnet.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: "'The general-purpose Squeak developers list'"squeak-dev@lists.squeakfoundation.org Subject: RE: literate programming examples (Re: Thoughts from an outsider) Date: Wed, 6 Sep 2006 08:02:22 -0700

...

The advantage of Dandelion is abstraction. For example, it stores analyzed code info in a repository. The analyzed data is independent of the current code and it can be retrieved later for further analysis. [:masashi | ^umezawa]

That's not abstraction, that's duplication.

Hi,

The nice thing about duplication is that the duplicated info is independent of the current code. The analyzed data can be used for historical analysis (how the code grows- for example).

That's not abstraction, that's duplication.

On Aug 30, 2006, at 15:38 , tim Rowledge wrote:

...

...

And dont go down the road that "smalltalk is simple so the code documents itself". The code NEVER documents itself, that is a cop-out and a bold face lie.

Well I have bit of experience in Smalltalk and I find myself substantially in agreement with JJ here. Sure, senders and implementors are fabulous tools to have but they offer nothing to help understand what is likely to happen with exceptions and very little for Tweak signals etc.

That is because the code at that point is not "straightforward", that is, it doesn't directly reflect what is going on because it is actually implementing a different architectural style (in some sense a different language) using what is available in OO/Smalltalk.

No amount of staring at source code will tell you what the author might have *wanted* the code to do, nor what misbegotten changes somebody made after misunderstanding the intent of the code at a later point. Source code tells you what *actually* happens, not what is *meant* to happen. Anybody that tries to tell you that the code does exactly what it it supposed to is almost certainly lying.

I have found that a combination of TDD-style unit tests and "intention revealing" programming style works really, really well at documenting what I *meeant* to happen. Which is kind of funny because it doesn't require any new technology, just technique.

However, it turns out that there are things this combination doesn't cover, and those tend to be the above case of indirectly programming in a different style/language using our current mechanisms. So it appears to be a good indicator of when you need to start twiddling with the language itself.

Adele Goldberg expressed it once as "if the code isn't documented, it doesn't exist" since without reasonable doc there is no way to count the code as usable in the long term. I tend to add the corollary clause "and if it doesn't exist, what did we pay you for?"

Funky. At the last OOPSLA there was a very similar definition of "legacy code": code that doesn't have tests. I thought that was really great. If it doesn't have tests, I can't understand it, and can't evolve it safely. I would also claim that, despite the fact that I like the fuzziness of natural language, unit tests are better to have than comments, because whereas comments tend to always be out of sync with the actual code, we have a simple way of ensuring that the unit tests and the code do not diverge.

Another old friend of mine has also coined the rather nice idea of "program the document, don't document the program"

Essentially very similar to TDD...write the spec/tests/doc, then code it up. The nice thing about tests is that they can tell you when you're done.

That said, it would be interesting if it is possible and/or useful to integrate these notions, maybe similar to what was done in the PIE system: first write documents describing fuzzily what you want, the possibly replace/augment with tests. Only when either one or both are available add code to make it do what the doc/tests say. I guess you could even have some sort of automatic linkup such that it only makes sense to add code in response to one of these documentation/test nodes.

Marcel

Thanks Tim. I think the heat here is because if my comments are taken personally it looks like I am calling volunteers lazy. That is not the case. Someone is lazy when they are not willing to do what they are responsible for (i.e. what they are paid to do or what the life/happiness of people they are responsible for depend on them to do). If someone doesn't want to document code that they wrote and gave away for free, that doesn't make them lazy or negative in any way.

But the documentation needs to get done. So if the author doesn't want to thats ok, it's not bad. But we can start a documentation project, get people who do want to do it and get this done. But the worst thing is when people trying to do this project don't get the help they need because everyone thinks it isn't necassary because "the code documents itself".

From: tim Rowledge tim@rowledge.org Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org Subject: Re: Thoughts from an outsider Date: Wed, 30 Aug 2006 15:38:40 -0700

On 30-Aug-06, at 1:34 PM, Ramon Leon wrote:

...

...

Communities that tell their users to RTFM find themselves alone very quickly. We're telling ours to RTFSC. There has got to be a compromise better than that.

--Benjamin

I never said documentation was bad, I was simply responding to the invalid accusation that the Smalltalk style of self documenting code is wrong, or that we're copping out or lying made by JJ below...

...

And dont go down the road that "smalltalk is simple so the code documents itself". The code NEVER documents itself, that is a cop-out and a bold face lie.

Well I have bit of experience in Smalltalk and I find myself substantially in agreement with JJ here. Sure, senders and implementors are fabulous tools to have but they offer nothing to help understand what is likely to happen with exceptions and very little for Tweak signals etc. No amount of staring at source code will tell you what the author might have *wanted* the code to do, nor what misbegotten changes somebody made after misunderstanding the intent of the code at a later point. Source code tells you what *actually* happens, not what is *meant* to happen. Anybody that tries to tell you that the code does exactly what it it supposed to is almost certainly lying.

Comments in methods ought to offer some help in decoding the expectations for the method as a whole, or for parts of the method. Class comments ought to offer a somewhat higher level view of what the class is supposed to do and the limitations it is known to have. Other forms of comments and documentation are needed to give later authors some hope of being able to use, maintain and improve the system. You need tutorial type documentation to offer newcomers to a part of the system a chance of getting some sense of the system before they can even begin to understand the actual code.

Adele Goldberg expressed it once as "if the code isn't documented, it doesn't exist" since without reasonable doc there is no way to count the code as usable in the long term. I tend to add the corollary clause "and if it doesn't exist, what did we pay you for?"

Another old friend of mine has also coined the rather nice idea of "program the document, don't document the program" to cover a concept of merging doc and code in the tools so that you can write spec, explanation, commentary, examples and limitations mixed in with executable code. It's not hugely different to some aspects of the late Jef Raskin's idea of The Humane Interface (see http:// www.raskincenter.org) and it wouldn't be too awful implemented as a nice document editor that has a style for 'source code' that actually means source code rather than just using a fixed pitch font. Hmm, now where might we find a document editor with intimate associations with a compiler?

tim

tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim A)bort, R)etry or S)elf-destruct?

It isn't the "Smalltalk style". In the early days of open source taking

I disagree, I think it is the Smalltalk style, maybe I'm wrong, but that's my opinion.

off on the internet everyone thought their code was "self documenting". And

that

includes C and Perl programmers!

You take what I said too personally. I'm not calling *you*, or Luckas or any of the great developers here liars. I am attacking this ridiculous concept of "self documenting code". It became popular with the free software crowd

That you are attacking anything, is what bothered me. You've used strong insulting language from the start, not against me personally, I take none of this personally, but against the self documenting style. You may not prefer this style, but many do, as we've developed a mistrust of documents not directly linked to code.

I did use strong language against the concept, but not as strong as some other people much more important then myself in much more public forums. I

You place great value on documents, OK, great, but not everyone does, no need to use such strong language. You can approach the subject of more documentation without being insulting to those who disagree with you. Rather than arguing "for" documentation, you seem to be arguing "against" less documentation, rather like a creationist arguing "against" evolution rather than "for" creationism.

figured some people would take it personal and get offended (I actually thought a lot more would) and I wouldn't want that, but sometimes it takes strong

wording

to make someone notice that something is wrong.

Anyway, sorry for offending you. I am very greatful for all the work you and everyone else has done.

Again, I'm not offended, my skin is much thicker than this, I'm simply disagreeing with how you approached the subject.

J J wrote:

This cancerous, destructive idea of "self documenting code" is a big barrior to people new to the language, and I would be willing to bet that is the main reason it isn't taking off faster.

+100

I can tell you I have done various projects in various languages to get a feel for it, and never before have I felt like I could do so much so fast, and yet not been able to do very much at all. Why? Because the state of documentation right now is almost impenetrable. Anything I do, I feel like it is probably already there in some system that I don't know about and have no way to find out about.

The main documentation right now, as far as I can tell, seems to be the mailing list.

"self documenting code" as a source of documentation is simply not valid. I am pretty surprised that such an obvious statement has so much resistance.

If source code is the documentation then the bar for becomming productive in the language is the amount of time it takes you to absorb the entire Smalltalk class heirarchy from the browser. And if you download a new system, then you have to read through every line of source code from that system. And that isn't enough, simply reading the code isn't enough. You have to wrap your brain around *why* it does what it does. Otherwise any change you do is probably not going to be helpful.

Any system that has not been documented may as well have not been written at all, and I said that on the seaside list years ago.

I myself looked at seaside right from the beginning and was never able to get my head around it. Actually it is not that difficult, but because of lack of documentation, I lost 2 years of possible using seaside. And on numerous occasions I have dropped using squeak for exactly the same reason. I might have spent 5 more years in the squeak camp if there were any documentation for morphic, but as yet I still cant get anything basic working to the standard that I would like.

Keith

___________________________________________________________ Try the all-new Yahoo! Mail. "The New Version is radically easier to use" – The Wall Street Journal http://uk.docs.yahoo.com/nowyoucan.html

From: stéphane ducasse ducasse@iam.unibe.ch Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org Subject: Re: Thoughts from an outsider Date: Tue, 5 Sep 2006 16:25:26 +0200

...

I myself looked at seaside right from the beginning and was never able to get my head around it. Actually it is not that difficult, but because of lack of documentation, I lost 2 years of possible using seaside. And on numerous occasions I have dropped using squeak for exactly the same reason. I might have spent 5 more years in the squeak camp if there were any documentation for morphic, but as yet I still cant get anything basic working to the standard that I would like.

But you can also help writing class comments or writing tests on what you learn. There is no magic and "you should write documentation" it does not work. I would love to have better documentation for Squeak but

Well, I was wondering if you guys had any kind of documentation team or project, but I guess if there was someone would have spoken up by now.

So is anyone interested in starting such a team? I will contribute what I can in my spare time. I know no one *wants* to write documentation, but it will be a good way to learn the systems.

So what we will need will is: 1) A main web site to host it on (can we use squeak.org for this? how does one get started adding documentation there?) 2) Some kind of reference manaul like this: http://caml.inria.fr/pub/docs/manual-ocaml/index.html (does something close exist already? I have been through many 'getting started guide's but most actually said 'not complete' before you got into the more compliated subjects like meta programming and meta classes) 3) A list of projects to document. I don't even know what is out there that people need to get work done. It seems to be so all over the place at the moment. 4) We are going to need some people that just sit on the various mailing lists and sumarize what is going on. If I am writing the documentation on Pier or Seaside, those things are moving targets. If I try to sit on the list and make changes for every announcement I wont ever release anything. So we need a person or persons to sit on the list and provide me or who ever is doing the documentation with a weekly or monthly, or whatever works, summary of what changes have happened so we can control it more.

And maybe someone else can think of more things. As a first cut I don't want to try to make UML diagrams or anything like that. Just getting some nice reference manuals out there in a central place that new people can find it will be a good first cut.

I relize there is a possibility to write a book on all this and maybe get rich, but I would rather write the book for free, make smalltalk more well known/lucrative and then write 10 books to get rich off of. :)

From: "Lic. Edgar J. De Cleene" edgardec2001@yahoo.com.ar Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: squeakdev squeak-dev@lists.squeakfoundation.org Subject: Re: Documentation project (was: Thoughts from an outsider) Date: Tue, 05 Sep 2006 16:41:47 -0300

See what Simon have on http://joyful.com/JoyfulSystems.

Also exists http://www.xs4all.nl/~maartens/ , look for Squeak

The principal site, something unorganized , is http://minnow.cc.gatech.edu/squeak/

Also exists a great number of specialized sites with his own "community"

When you have "Squeak for dummies" or "Learn Squeak in ten days" book what lets you meet the beautiful ladies Fame and Fortune, send notice to this list. :=)

---

Preguntá. Respondé. Descubrí. Todo lo que querías saber, y lo que ni imaginabas, está en Yahoo! Respuestas (Beta). ¡Probalo ya! http://www.yahoo.com.ar/respuestas

From: tim Rowledge tim@rowledge.org Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org Subject: Re: Documentation project (was: Thoughts from an outsider) Date: Tue, 5 Sep 2006 13:20:18 -0700

The key problem with any sort of traditional doc for a system like Squeak is that by the time you have written the outline it is so out of date that you have no chance of ever catching up. This is why I'd like to see some sort of image based doc-tool; at least it would have some hope of being up to date. I *don't* think that merely aggregating class and method comments is anywhere near enough. Nor do I know exactly what *would* be enough, sadly. I am pretty sure that it needs to combine a way of presenting the raison d'être of the code, the reasoning behind the design, the known limits and tradeoffs and invariants expected and the tests, examples, demos and even the method and class commentary.

I know that is true for some of the projects, but all of squeak? It seems to me like squeak, while moving, is stable.

And I think smalltalk should do to everyone else what they have done to smalltalk for so long. We should steal vigorously from them. :) There are lots of great documents out there on many other languages. I plan to use those documents as a template of what works and what people expect. So that way I don't have to come up with the outline from scratch, and that traditionally is what takes me the most time. :)

tim

tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Strange OpCodes: HSJ: Hop, Skip and Jump

J J puso en su mail :

People new to smalltalk would be the best for this probably, since this lets us make a very big contribution fairly quickly.

If you could find a Spanish speaking person , (a child is better), we have some begginners info and site in: http://ar.groups.yahoo.com/group/squeakRos/ (Group) http://wiki.gnulinex.org/squeakros (Swiki in Spain) http://ar.geocities.com/edgardec2001/Welcome.html (Beginners tutorials , most in Spanish) ftp://elpelotero@201-212-99-13.cab.prima.net.ar/ password: elpelotero (on approximate 09:00 to 20:00 GMT, dig and take what you like, at your own risk)

__________________________________________________ Pregunt�. Respond�. Descubr�. Todo lo que quer�as saber, y lo que ni imaginabas, est� en Yahoo! Respuestas (Beta). �Probalo ya! http://www.yahoo.com.ar/respuestas