December 2010 - Pharo-dev - lists.pharo.org

Re: [Pharo-project] About using pragma for help like in setting

by laurent laffont

On Mon, Dec 13, 2010 at 9:56 AM, StÃ©phane Ducasse <stephane.ducasse(a)inria.fr > wrote: > I read all the Help on Help and could not find what I wanted to know. > What do you want to know / looking for ? Laurent > I read also the code same here. > > Stef > > > On Dec 12, 2010, at 10:33 AM, laurent laffont wrote: > > > > > I think, the fact that there is no single external package with help > > system documentation proves this, no? > > > > > > Actually there's at least Help on HelpSystem ;) ProfStef, WebTester, > Metacello, Mocketry, Mondrian. I've started one for Pier but on Seaside > mailing-list nobody have answered :( > > > > So yes there's some help, it's slow. > > > > I agree 100% on what you said about dependencies, documentation close to > code, tagging/pragma approach, .... but it seems to me that whatever system > we adopt, growing documentation will be slow . > > > > So we need to push to write doc. even if the current or futures systems > are not perfect. > > > > Laurent. > > > > > > > > Lukas > > > > -- > > Lukas Renggli > > www.lukas-renggli.ch > > > > > > >

Dec. 13, 2010

Re: [Pharo-project] Issue 3406 in pharo: Standard images from downloads page do not implement Object #clone

by pharo＠googlecode.com

Comment #4 on issue 3406 by rydier: Standard images from downloads page do not implement Object #clone http://code.google.com/p/pharo/issues/detail?id=3406 The most up-to-date sound package is probably in http://www.squeaksource.com/PharoSound It works in 1.1 at the moment, amongst other things, he clone issue is already resolved there. Some relocated Preferences needs to be resolved for 1.2 though.

Dec. 13, 2010

Re: [Pharo-project] About using pragma for help like in setting

by StÃ©phane Ducasse

lukas can you give a try on that? > After the discussion in May we all agreed [2] that it is a good direction to check out the > pragma/builder approach too and see how far we can go here. I provided an example how one > can easily add this "pragma approach" to to the HelpSystem ([3] and [4] for the code) but I left > out the builder part since I dont know what Lukas expects here. > > So no real feedback/adoption so far ... at least it would help if I get an example > on how the contents should be defined in an annotated #buildHelpOn: method. Stef

Dec. 13, 2010

Re: [Pharo-project] About using pragma for help like in setting

by StÃ©phane Ducasse

I will try to digest that long mail. Now what I want is that people can type thisMethodForZork: aBuilder <help> aBuilder title: 'About Zork' text: 'here is the help for the Zork' "adapted to the API of Help" or thisMethodForZork <help> or <help:1> or <help: 'About Zork' :1> ^ 'here is the help for the Zork' and that if the help is loaded we can see it in help. Stef On Dec 13, 2010, at 2:34 AM, Torsten Bergmann wrote: > Hi, > > OK, just read the IRC meeting notes and the last posts/threads on the help discussions. > Unfortunately the discussion is scattered and I try to catch up/summarize here > even for people who are new to the topic. Excuse the length of this post in advance. > If the pragma help is interesting to you only then jump to section "D": > > > A. Pharo once lacked a "help system", so I wrote one. It was and still is more oriented > towards "end user help" or "browsable manuals" with written text content in form of > nestable books. I had no need for the next JavaDoc in Smalltalk with just an API reference > - I wanted real help text which gives a big picture overview to people on various topics. > > The design of HelpSystem is simple and should be easy to understand, we have a > HelpBrowser that displays (nestable) HelpTopics. To display something you have to > convert it into such a help topic instance. > > Click on "Help" -> "HelpBrowser" in your Pharo image and have a look at the book > "Help on Help" to get more details or try a few examples. > > > B. I think you all agree that a "help system" without content is not very useful. > Different people have different ideas and what could be used as "help contents" > should be up to you. > > The HelpSystem itself is not and should not be bound to where and how (format, etc.) > the content is stored. You can convert from any source and format into nested HelpTopics. > > To demonstrate this I once provided an example [1] to query and display the IRC archive. > You will also find this example with IRC as one possible external source in the "Help on help" > book. > > So the content could be defined in any format you like and the contents source could be > internal or external to the image. You should declare the help contents the way you like. > > C. When you want to provide help to a user you may find it nice to include and manage > the contents directly within the image. Nice - since you can deploy it with your app or > unload if it is not needed. > > There are many solutions here - on squeak-dev it was discussed to use a specific class > comment format or store the contents in methods returning an XML string, etc. > I expected this discussion since I thought long enough about formats, storage and I > didnt want to limit anyone. > > Therefore HelpSystem is open to any of these solutions - one can implement a custom > help builder (see class HelpBuilder) that does the necessary conversion into help topic > instances. > > One of the many possible solution is to use "pragma annotated" classes that hold the > contents. Looks like this is getting more attention now again since pragmas are used > in various places now (like the settings framework). > > And yes, I followed the pragma path already. But after initial experiments with pragmas > I found it much more convenient to map a tutorial/the help book structure directly to > the class hierarchy. > > This "class to book" mapping is more natural, one can use the usual class browsers and > tools to manage the contents (including references, implementors, senders, ...) > and you can easily have extensible books/tutorials (which is complicated with pragmas) > > If you want to follow this "class to book" approach then HelpSystem provides a class > called "CustomHelp" that you can subclass and that has all the necessary support > (even for editing and saving by using a workspace) - so you can easily implement your > help books. Some projects use this already and there is even a Pharocast on how to > to this. > > Through the class CustomHelp in the HelpSystem we have a commonality with SUnit - > where you have TestCase as a superclass and implement hook methods. > > This class "CustomHelp" is the one "under fire" that leads to scathing criticism from > Lukas. > > Maybe it is exactly this commonality with SUnit that makes some of you think HelpSystem > forces you to subclass "CustomHelp" or forces you to have a dependency on the help system > if you want to declare your help content. > > => But yet again: nobody has to use the provided "class to book" mapping or subclass > "CustomHelp" if you want to define your help contents! > > Maybe I should not ship HelpSystem with this support class "CustomHelp" as the (currently sole) > default but I wanted to at least provide a way to get you started. Still it is an utility class > and also categorized as such. > > I for myself have no problem with this additional class since when subclassed I know that > I have a dependency on it's package and I treat the help packages similar to test > in SUnit (only loaded when HelpSystem is there, etc.) > > However the "CustomHelp" approach has pros and cons and you have to decide if it is the > right for you: > > Maybe you like: - easy mapping of classes to books > - easy browsing/managing in standard code tools > - familarity with SUnit (common superclass) > - no "copy/paste" methods as in Metacellos ConfigurationOfXXX > > Maybe you dislike: - the dependency on the superclass CustomHelp and > - therefore the dependency on the help package > > Typical use case is that you display the help contents in the browser anyway and > therefore this dependency may not hurt you. > > Looks like Lukas has a use-case where he requires his help contents only - but > not the help system itself. Similar to a loaded test without any SUnit support in the image... > > D. As I already said I designed HelpSystem to stay independent from the way the contents is > defined. So I'm definitely open to a pragma based solution too. In the long term I would like to see > support for different "content definition styles" anyway. > > Lukas can store his blog posts/help texts the way he likes and without any dependency on HelpSystem. > > After the discussion in May we all agreed [2] that it is a good direction to check out the > pragma/builder approach too and see how far we can go here. I provided an example how one > can easily add this "pragma approach" to to the HelpSystem ([3] and [4] for the code) but I left > out the builder part since I dont know what Lukas expects here. > > So no real feedback/adoption so far ... at least it would help if I get an example > on how the contents should be defined in an annotated #buildHelpOn: method. > > However, the pragma approach has pros and cons: > > Maybe you like: - no dependency on a common superclass or package dependency on a class in HelpSystem > - may therefore seem "cleaner" depending on POV > > Maybe you dislike: - even with pragmas one has an implicit dependency on the builders interface > which also has to be stable very early > - by using pragmas (loose coupling) you have to deal with the problem that > your parent topic may not be there/not be loaded since it can be defined > somewhere else in the class hierarchy. > > E. After the initial release people asked on how to integrate typical "Smalltalk documentation" > to include browsable reference documentation (API doc) like class and method comments in the > HelpSystem too. This was easy to add since again I just had to write a custom help builder that does the > necessary conversion. > > If you load the "Pharo-Project-Help" you can browse the complete reference on anything that > is already documented: > > > Gofer new > squeaksource: 'HelpSystem'; > package: 'Pharo-Project-Help'; > load. > HelpBrowser open. > > In the help browser click on "Pharo" and "API Reference". This is more "reference documentation" and > only a "poor" way to easily fill up the help system ;) > > I would like to see people writing more tutorials/manuals about parts of the system so one could get the big > picture, but the idea of Stef [5] to get fully documented classes and methods is also nice. For the > reference docu: > > > Maybe you like: - no dependency on anything, just comment your classes and methods > as you may know from any other smalltalk system > > Maybe you dislike: - you dont need the help system, you can look at it in the standard browser > - its only a basic API documentation system (compared to JavaDoc and others) > > ----------------------------------------------------------------------------------------------------------------- > And now some comments on IRC/posts I've seen: > > Lukas on IRC see [6]: >> [3:14pm] renggli: HelpSystem is not useable for me and obviously not for anybody else (otherwise >> it wouldn't be empty) > > Lukas, nobody forces you to follow the "define help contents via class to book mapping" approach. > If you want a "define help content via pragmas" approach then help moving this issue forward or define > your help contents the way you like and implement a custom help builder. > > For the other point: HelpSystem is not empty - look at an updated core 1.2 and it is already > used in many external packages as Laurent already pointed out. [7] > > > Lukas wrote on [8]: >>> Couldn't you just add another loop to your script to "unload all help" just >>> like unload all tests >> Sure, but that means I have to package help text separately. This is >> the contrary to what Java, Ruby, Python, Javascript, ... are doing; >> keeping code and documention as close together as possible. > > No - you dont have to package documentation seperately. A class/method comment is still a > class/method comment and its packaged with the code. There is no dependency on HelpSystem > here - although the HelpBrowser can display it too. > > You still keep code and documentation close as in any other language. > > But if you write a "big picture" help manual or tutorial on how things interact it would > be good to package it seperately. Either using CustomHelp, pragmas, or ... > > > Lukas wrote on [8]: >> I think, the fact that there is no single external package with help >> system documentation proves this, no? > > There are quite a few. Maybe you should look more often on Squeaksource. Again I point to [7] > > > Stef wrote on [9] >> Now I was thinking that torsten would reply to this mail but in 1.3 will take a decision because I want a really better help >> and documentation inside the right class and package. > > I still think that we should in minimum have the "code" - "tests" - "help" package triade, where the code package > includes the class and method documentation as any Smalltalker is used to. The test package should include unit tests > covering the code. And the help package should give a high level overview on how to use the code or tests. > > If the dependency from "help" packages to "help system" due to the class CustomHelp is a problem then > we can easily convert them once we have a good "pragma based" approach in place. > > Removing packages or classes that are not documented is too hard ... but we should use Lint rules to check the > "completeness/basic quality" of package. > > Similar to checkstyle for Java in Eclipse - if there are problems in a package then you have a different icon for > the package and you work until it's clean because it hurts your eyes (see [10] for a screenshot) > > > Hope I could at least bring some light into the whole discussion and I would really like > the see if also the pragma approach would move forward. > > Bye > Torsten > > > [1] http://forum.world.st/Preview-Help-System-with-new-model-now-also-for-Squea… > [2] http://forum.world.st/Help-System-td2131748.html > [3] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-May/026148.html > [4] http://lists.gforge.inria.fr/pipermail/pharo-project/attachments/20100505/c… > [5] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/036952.h… > [6] http://pastebin.com/Y7MFaddK > [7] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/037507.h… > [8] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/037485.h… > [9] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/037499.h… > [10] http://www.ibm.com/developerworks/java/library/j-ap01117/checkstyle-eclipse… > > > > -- > Neu: GMX De-Mail - Einfach wie E-Mail, sicher wie ein Brief! > Jetzt De-Mail-Adresse reservieren: http://portal.gmx.net/de/go/demail >

Dec. 13, 2010

Re: [Pharo-project] Issue 3406 in pharo: Standard images from downloads page do not implement Object #clone

by pharo＠googlecode.com

Updates: Cc: guillermopolito Comment #3 on issue 3406 by marianopeck: Standard images from downloads page do not implement Object #clone http://code.google.com/p/pharo/issues/detail?id=3406 We need to update this for the Pharo 1.2 dev I guess.

Dec. 13, 2010

Re: [Pharo-project] About using pragma for help like in setting

by StÃ©phane Ducasse

I read all the Help on Help and could not find what I wanted to know. I read also the code same here. Stef On Dec 12, 2010, at 10:33 AM, laurent laffont wrote: > > I think, the fact that there is no single external package with help > system documentation proves this, no? > > > Actually there's at least Help on HelpSystem ;) ProfStef, WebTester, Metacello, Mocketry, Mondrian. I've started one for Pier but on Seaside mailing-list nobody have answered :( > > So yes there's some help, it's slow. > > I agree 100% on what you said about dependencies, documentation close to code, tagging/pragma approach, .... but it seems to me that whatever system we adopt, growing documentation will be slow . > > So we need to push to write doc. even if the current or futures systems are not perfect. > > Laurent. > > > > Lukas > > -- > Lukas Renggli > www.lukas-renggli.ch > >

Dec. 13, 2010

Re: [Pharo-project] Is executing a file platform dependent?

by StÃ©phane Ducasse

Guys we should create a nice documentation for the OSProcess please please spend some time on the collabactive book because we need more documentation. Stef On Dec 12, 2010, at 6:34 PM, Schwab,Wilhelm K wrote: > OSProcess, which I am learning to like more as I learn more about it, is not well supported on Windows. Dave recently advised me to use ProcessWrapper on Windows; if he is saying that, then it must be the better path for now. > > I have done FFI on both Windows and Linux. I have not (yet anyway) done any one task in a cross-platform way. So far, I have not seen anything horrible that would prevent it. I have zero interest (at least so far) in moving my numerical analysis adventures back toward Windows (they started there and moved to Linux where I am quite happy). I have a .so interface to Acces IO A/D hardware and a DLL interface to Ascension Technology's 3D tracking software. Ultimately, I hope to be able to use both of them on either platform (the software exists on both), but have not yet made the connections. > > I transparently use OutputDebugString() on Linux and syslog() on Linux, but that does a test on platform and calls completely different code, so it does not count here. > > Sorry I can't be of more help. I urge you to wade into it and ask for help as you get stuck. For creating libraries, you might want to have a look at Code::Blocks; I don't push it very hard, but I have no complaints. The "default" is to install MinGW on Windows (last time I looked at least) and it uses gcc on Linux. > > Bill > > > ________________________________________ > From: pharo-project-bounces(a)lists.gforge.inria.fr [pharo-project-bounces(a)lists.gforge.inria.fr] On Behalf Of Lukas Renggli [renggli(a)gmail.com] > Sent: Sunday, December 12, 2010 11:43 AM > To: Pharo-project(a)lists.gforge.inria.fr > Subject: Re: [Pharo-project] Is executing a file platform dependent? > > With OS Process you can run scripts. That should work identical on Mac > and Unix systems; probably also Windows, but I haven't tried. > > With FFI and Alien you can call C libraries. I have not much > experience with those, but normally it should be possible to use them > on all platforms. > > Lukas > > On 12 December 2010 17:31, Max Leske <maxleske(a)gmail.com> wrote: >> Hi guys >> >> I was wondering if it is true that executing a file from within Pharo is platform dependent. I don't actually need to execute a file; it's more a theoretical question and I have no idea what the mechanisms are that would be used. To give you a clearer picture: Imagine you have C, sh, and perl files. What I'm thinking about is that I would have some data in the image that I would want to process with the code in one of those files. I would then wait for the result and process the result in the image. >> >> So my questions are: is there a platform independent way to execute C, sh or perl files from Pharo? Does the VM handle the platform dependencies? Are there any other issues with the idea I described? >> >> Don't go out of your way to find answers, please. But I'd be happy to hear your thoughts. >> >> Cheers, >> Max >> > > > > -- > Lukas Renggli > www.lukas-renggli.ch > >

Dec. 13, 2010

Re: [Pharo-project] good news of the year

by StÃ©phane Ducasse

On Dec 12, 2010, at 11:09 AM, Geert Claes wrote: > > This is excellent! It is wonderful for INRIA to invest in Pharo! Congrats > Igor and enjoy your time in Lille ... you must try a Belgian beer called > Duvel, best beer in the world :) > > I see the TO-DO list is already pretty long, it would be great if there is > time for a better SqueakSource/Monticello 2 For SqueakSource, ESUG is paying the iliad guys to show that their technology is cool and they will rewrite from scratch. We are negociating since a couple of months with inria to have a web-dav server so that we can host all the monticello related host. Stef > -- > View this message in context: http://forum.world.st/good-news-of-the-year-tp3083142p3084152.html > Sent from the Pharo Smalltalk mailing list archive at Nabble.com. >

Dec. 13, 2010

Re: [Pharo-project] Loading *some of* a MC snapshot into the image

by StÃ©phane Ducasse

use the old merge dialog check the preference On Dec 12, 2010, at 3:38 PM, Damien Pollet wrote: > On Sun, Dec 12, 2010 at 09:42, Lukas Renggli <renggli(a)gmail.com> wrote: >> 1. From the merge dialog you individually pick and install the changes >> that work. In the old merge dialog this works nicely. > > Actually I tried to do something like that, but the menu items were > all disabled in the merge tool. > So I guess I have the new merge dialog, yay :D > > >> Lukas >> >> On 12 December 2010 04:37, Damien Pollet <damien.pollet(a)gmail.com> wrote: >>> I have a snapshot compiled against an old version of PetitParser. >>> Unfortunately one of my classes now has a conflicting inst var with >>> the most recent PetitParser, so my code does not load, MC explodes >>> instead of giving me a chance to fix the problem on the fly. Of >>> course, there are quite a few changes I'd like to rescue in that >>> snapshot. Please don't tell me I have to copy-paste them allâ¦ >>> >>> -- >>> Damien Pollet >>> type less, do more [ | ] http://people.untyped.org/damien.pollet >>> >>> >> >> >> >> -- >> Lukas Renggli >> www.lukas-renggli.ch >> >> > > > > -- > Damien Pollet > type less, do more [ | ] http://people.untyped.org/damien.pollet >

Dec. 13, 2010

Re: [Pharo-project] Ring - model infrastructure for Pharo

by StÃ©phane Ducasse

Yes Now this is the choice of veronica to know how many classes she wants because in addition to class/instance there is also compiledMethod methodDefinition.... Stef On Dec 12, 2010, at 1:47 PM, Igor Stasenko wrote: > On 12 December 2010 08:41, StÃ©phane Ducasse <stephane.ducasse(a)inria.fr> wrote: >> >> On Dec 11, 2010, at 8:35 PM, Igor Stasenko wrote: >> >>> CompiledMethod>>#methodNode >>> is a conversion method >>> and as any conversion i would prefer it be prefixed with 'as' , i.e. >>> #asMethodNode >>> >>> #stringVersion is used only in MessageTrace in my image. >>> >>> Concerning #stringVersion: >>> i really don't have an idea what this stuff doing there? >>> Why a method reference allows putting an arbitrary data (strings) >>> there by various tools? >> >> :) >> >> because it was handy and cool to have a holder of anything from the tools point of view. >> And this is why we will clean that :) >> >>> >>> Then maybe better call it 'annotation' , and correspondingly #defaultAnnotation, >>> so we will know that this field used for annotations by different tools? >> >> >> >>> >>> About #isMeta and friends: >>> they serve nothing , but introducing a lot of ad-hoc logic with code >>> branches all over the places. >>> We should learn how to use message dispatching better :) >> >> this is not always that simple. >> >>> IMO, the 'theClass' ivar should be capable answering this message, >>> along with #name, which gives the name of a class. >>> Method reference in its 'theClass' ivar instead of symbol, should hold >>> either real class object (or metaclass object), >> >> No because you can be analysing an off-image >> code or not yet installed code. So you cannot rely on the fact that the real class is reachable. >> > i see no problem with offline representation. > You still won't need 'isMeta' in method definition, because you have a > following model: > > instance side method ref -> some class proxy > class side method ref -> some metaclass proxy > > sure you can leave #isMeta in method reference which simply redirects > the request to its 'theClass' variable: > > isMeta > ^ theClass isMeta > > voila. > > A CompiledMethod makes no difference between class/metaclass, its only > holds a reference to the > behavior it installed in: > > method := (Object class>>#initialize). > > method methodClass ---> Object class > method methodClass isMeta ---> true > (Object class>>#initialize) methodClass name ---> 'Object class' > > So, since method references representing the CompiledMethod, they > should not care as well. > >>> or a proxy (in same way as method reference is a proxy by itself). >>> >>> >>> -- >>> Best regards, >>> Igor Stasenko AKA sig. >>> >> >> >> > > > > -- > Best regards, > Igor Stasenko AKA sig. >

Dec. 13, 2010