Networking Squeak
Networking Squeak, by Bijan Parsia of U. North Carolina at Chapel Hill, and Lex Spoon and Bolot Kerimbaev of Georgia Tech.
Current draft: networking.pdf
Bijan's Up-to-date, very rough draft: http://www.unc.edu/~bparsia/squeakbook/networking.html
Code and fixes for IRC: Missing File (/squeakbook/uploads/IRCHacks.2.cs)
Promised reviewers:
Kendall Clark, http://monkeyfist.com/
John Tobler, squeaker@diganet.com
Comments:
General
Well written and helpful. I'm looking forward to reading the rest of it. Sometimes somewhat talkative. I miss well chosen pointers to more info, perhaps this is already planned.
page 4
this recorded demo style works well for me. I would change the wordings somehow though. Instead of in different ways explicitly say that you want it to be impressive and nice, just show the examples, they are impressive and nice. But keep the "we are sitting together in front of a squeak system" tone of voice.
page 5
"parseString:" doesnt work, "parse:" does
openAsMorph didnt work
(on my image that is a 2.8a #2156)
page 7
A bit talkative for my taste. For instance now I know that a lot of your students didnt know how to use email at a particular time. I would cut some of this.
Mats Nygren
Thanks for the comments Mats. The rest should show up on Monday (I hope).
parseString and openAsMorph are convenience functions I've added. As soon as I get it together, I'll upload them.
(HtmlParse>>parseString: just takes makes a ReadStream on: aString and feeds it to HtmlParser>>parse:
HtmlDocument>>openAsMorph is a touch more complicated, but essentially is just a cutting out of all the extraneous bits of Scamper>>openAsMorph.
In general, this version won't be as "tight" as I hope to get it. But, I will add, that I take this book and this chapter as documenting the community as well as the software.
BTW, pointer's galore are on the way. I have so many that I just haven't had time to organize them. :)
Thanks again! Bijan.
Mark's Review of "Networking Squeak"
Of course, I'm VERY excited about this chapter! It's going to be great to have some real description of the powerful networking capabilities in Squeak. As you say in the chapter, networking in Squeak is a powerful reason to start Squeaking.
The biggest concerns that I have are:
- Who's your audience? At some times, it seemed like you were aiming at the people who just read Noel's chapter (which makes lots of sense to me). But other parts (e.g., p. 10 where you start discussing each class variable in PWS) felt like it was aimed at serious networking app developers. I don't have a problem with you saying that you want to go for both, but then you need to make transitions and explanations that help the audience figure out what's going on where.
- I continue to be confused about who's authoring this chapter :-). I know that Bijan is taking the lead, but I've heard both Lex and Bolot talking about contributing pieces. Throughout the chapter, there are lots of "I"'s, which make me think that it's just Bijan. Perhaps I's become We's?
- I'd like to see alot more than PWS discussed here. I know that you plan to add Comanche, but I'd also like to see more on the support for different protocols (FTP, HTTP, SMTP, POP) and mention Celeste and Scamper.
- The tone of the chapter shifts back-and-forth between being a description of the system and a story of how these pieces came to be. In my experience, it's hard to mix these. It really works to tell stories that enliven the description and explain how things came to be. But when there is alot of detail on the old version and the new version (as in the description of listenLoop on p. 11), it gets hard for people looking for a system description to figure out which is NOW and which is THEN. I know that YOU lived this history, and you have great stories, and other developers will enjoy the stories, too, but for novices, you either have to dump the stories or clearly identify them so that people can figure out what's relevant and what's not.
ISSUES:
- p. 1: "Scamper, the web browser" as opposed to "Scamper, the Movie, starring that lovable furball, Benji!" :-) Perhaps "Scamper, the web browser included with Squeak"?
- p. 1: I also happen to love bullet lists, too (as is evident from the current one I'm writing in). But a single bullet has to be fairly small and focussed. If you fill in everything that you have in [square brackets] in that bullet, it's going to be REALLY big! Perhaps too big?
- p. 2: "Cyberdog lovers will much to like about Squeak" – missing a verb and an explanation of what the heck Cyberdog is (for those poor non-Mac-ers out there.)
- p. 3: "blue plane" - If Alan explains this in his foreword, you can refer back, but if not either (a) explain the term or (b) cut it, please.
- p. 3: "I think..." The chapter is obviously your perspective – you can drop the "I think"'s and be confident in your statements.
- p. 3: "http" in bullet #2, "HTTP" in bullet #4. Decide what your format is, please.
- p. 3: "an teacher-of Squeak" – "a"?
- p. 3: I think it's quite cool to contrast Python with Squeak, but if you do, you should say a word or two about what Python is and WHY contrast it. Perhaps add a reference to the "Internet Programming with Python" book?
- p. 4 "ad hocly to aid's one SqueakWorking" – perhaps too many invented words in a single sentence?
- Before "Some simple SqueakWorking" might be a good place to provide a brief (half page?) tour of Socket, SMTP, POP, FTP, Scamper, and Celeste?
- Of course, I love the story about drawing on the windows in the footnote, but it's a heckuva big footnote. Either move it into the story (where I'm not sure it fits) or remove it?
- p. 4-5: You haven't told us how to inspect have you? For novices, perhaps just mention alt/cmd-I? Or include the message send "inspect"?
- p. 5: Showing "I" vs "i" might not be enough to make it clear that Shift is required to get the explorer.
- p. 5: The "Bijan added methods" are cool to add, but tell people up-front to fileIn a set of changes from the CD (and/or, upload them to the Squeakbook CoWeb and provide a URL?).
- p. 5: Spell-check: "occurnntly"?
- p. 6: "a rather thing" - small thing?
- p. 6: What's an "IDE"?
- p. 7: Nice story about starting to use PWS, but it's a whole page. Can you capture the key idea in a paragraph?
- p. 8: Similarly, our bonding story is one of my favorites (I tell it frequently), but it's one of those that may delight a developer (if separated off "Challenges in Debugging Client-Server Apps") but may confound a novice.
- p. 8: BTW, http://www.libertybasic.com is an all-Squeak-all-the-time site, too.
- p. 9: Bullets #1 and #2 are terrific – they highlight PWS as part of an open-source effort as well as a real tool that real people are using. Bullet #3 was a personal delight for me, but isn't really key to the story. (BTW, I didn't do it in a hurry – I did it without sleep. PWS was written in Nov. 97, and my third child was born Oct. 27...:-)
- p. 10: TeX is translating your ">>" into something decidedly odd.
- p. 10 footnote 13: "an" -> "and"
- p. 10: Decide the level of your discussion. Discussing each class variable (I agree with footnote 12 for hacking) is great documentation, but since most of the discussion is at a much higher level, it's an odd shift (from how to write an action, to how PWS actually works). Again, you certainly can have both if you really want (and have space, given the scope of what you're trying to cover!), but clearly delineate the differences ("Writing PWS Applications" to "Under the PWS Hood").
- p. 11: I find that a picture of the ActionTable and PWS and the actions helps in describing this.
- In general, the outlined pieces seem right on – I look forward to seeing them!
- p. 15 (skipping much of the just-outlined pieces): You probably need to describe what a Wiki is and what a Swiki is. It doesn't have to be much, but you jump into detail (p. 16, e.g., intercapped vs. asterisk-enclosed) that non-Wiki-familiar readers are going to be confounded by.
Right now, I (Bijan) have written everything up through PWS; Bolot has written the Comanche stuff (and owes me more!); and Lex has written the stuff (on the updated web page) on clients. Voice is a problem that I've discussed in email, with Lex sorta seeming to to go with me putting it all in a "unified" voice (or whatever the flow is), and Bolot not having said much. I vacillicate. I'll figure it out eventually :) I suspect clearly shifting voices will be a good thing.
So too with the tone. I do want to hit everyone ;) Er... in the nice way of course.
Right now (with Lex's stuff and without most of Comanche or the synergetic stuff and no pictures) we're at....33-35 pages.
Oops!
I'm just going to keep writing until I stop :) and figure out the cuts later. Heh...if you'd like another chapter... ;)
Or Hey! Since they're three of us...don't we get more space?!? :)
Of coures, the overflow will go very nicely on the website. I think the real key is figuring out how to put enough tantilizing stuff in the written chapter to send folks to the web version.
Cheers,
Bijan.
Oh, yes, I'm fixing the TeX troubles...the HTML version is actually much nicer (and Mark, you should check that out.)
This draft begs to be edited by somebody with adequate knowledge of proper English writing style.
Besides, the overall outline and contents should probably be defined by somebody else to avoid the author's random walks across distinct discourse levels.
This comment begs to be made by someone with adequate knowlege of propriety and intelligibility. Anonymous insulting comments which are 1) completely non specific (e.g., "proper English writing style"? Do you mean you wish a more formal tone? Note that's a very different complaint; if there are brute errors pointing some of them out would be better than merely winging about it; without evidence your assertion is mere Oh, "random walks across distinct discourse levels", too, is uselessly imprecise. Just because you can't follow a narrative thread doesn't mean that the rest of use will be able to discern what confuses you. (This isn't to say that the draft is perfect. There are several useful comments above yours.), and 2) incomprehensible. How on earth would "defining the outline and contenst by somebody else" going to "avoid" my alleged discourse randomness? I fail to see what it is about the outline for example that causes the "problem".
Of course, if what you really mean is "drop this chapter and author", please say so, and let us know which bits, if any, are salvagable.
Bijan "random walker across distinct discourse levels by means of inadquate knowledge of proper English writing style" Parsia.
Links to this Page