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

Re: [Pharo-project] Help System

by StÃ©phane Ducasse

Yes I remember it :) Kind of pattern :) Stef > >> P.S: I'm still in favour of well structured books in separate >> packages than mixed code/docu in one package since you >> may wish to unload docu for deployment/runtime scenarios. >> > Hi Torsten, all > Yes, we had exactly the same discussion (one year ago? I can't believe it) about > the settings package. An advantage of the builder approach is that > one can simply choose: > It is possible to let documentation methods (#helpOn: aBuilder ...) and code > mixed in a single package without introducing any dependency > or choose to have two packages, one for the documentation and the > second for the code. > Cheers > Alain > >> >> >> >> >> >> _______________________________________________ >> Pharo-project mailing list >> Pharo-project(a)lists.gforge.inria.fr >> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

May 5, 2010

Re: [Pharo-project] ConfigurationOfPharo and OmniBrowser

by Dale Henrichs

Alexandre, Using Metacello 1.0-beta.26 and PharoCore-1.1-11335-UNSTABLE (latest update), I get the same results: SHOUT uses the deprecated registerMenu API Refactoring Browser AST-Core-lr.66 is loaded first and the AST-Core-lr.67 is loaded but this probably isn't a problem, although moving the refactoring browser project in the baseline should eliminate the "double load" Nile-Clients-MarianoMartinezPeck.178 still has an issue with #isInMemory not understood, while doing NSAbstractDataStream class>>initialize So I don't think these are Metacello issues...just more work to port these projects to Pharo 1.1:) Dale ----- "Alexandre Bergel" <alexandre(a)bergel.eu> wrote: | > I'm actually working through this scenario right now. | | Hi Dale! | | Any progress? | | Cheers, | Alexandre | | | > Moving OB BEFORE AutomaticMethodCategorizer will load the proper | > version of OB ... with this load order the older version of OB | > shouldn't be loaded by AutomaticMethodCategorizer (this is the area | | > where I suspected a bug in 1.0-beta.26 that is fixed in 1.0-beta. | > 26.1). | > | > However, I have run into an issue with SHOUT using the deprecated | > API and then I ran into an MNU in another part of the system (doing | | > initialization) so I'm trying to determine if this is a problem for | | > Metacello or not ... when I have characterized the issues, I'll send | | > mail... | > | > Dale | > | > | > ----- "Alexandre Bergel" <alexandre(a)bergel.eu> wrote: | > | > | > Thanks Dale for the dedicated answer. I understood you | > correclty? If | > | | > | > I change baseline11: and I put | > | > | > | > project: 'AutomaticMethodCategorizer' | > | > with: | > | > [ spec | > | > className: | > | > 'ConfigurationOfAutomaticMethodCategorizer'; | > | > file: | > | > 'ConfigurationOfAutomaticMethodCategorizer'; | > | > repository: | > | 'http://www.squeaksource.com/MetacelloRepository' | > | > ]; | > | > | > | > | > | > AFTER | > | > | > | > project: 'OB Dev' | > | > with: | > | > [ spec | > | > className: | > | > 'ConfigurationOfOmniBrowser'; | > | > loads: #('Dev'); | > | > file: | > 'ConfigurationOfOmniBrowser'; | > | > repository: | > | 'http://www.squeaksource.com/MetacelloRepository' | > | > ]; | > | > | > | > | > | > then it should work ok ? | > | | > | I understand that if you do this, then the version 1.1.3 of | > | Omnibrowser will be loaded, then AutomaticMethodCategorizer will | | > load | > | | > | the old version of OB. | > | | > | I think that ConfigurationOfAutomaticMethodCategorizer needs to | be | > | updated. | > | I work on it now... | > | | > | Cheers, | > | Alexandre | > | | > | > | > | > | > | > | > | > This implies that ConfigurationOfAutomaticMethodCategorizer will | | > not | > | | > | > load correctly into Pharo 1.1, so the solution is to create a | new | > | > version ConfigurationOfAutomaticMethodCategorizer that will | load | > | > into Pharo 1.1 (i.e. referencing version 1.1.3 of | > | > ConfigurationOfOmniBrowser) and then update | ConfigurationOfPharo | > | > accordingly... | > | > | > | > yes...the problem is that you have to do that in all the confs | | > that | > | | > | > points to OB. | > | > | > | > ..... | > | > | > | > | > | > The nesting level for '1.1.3 [ConfigurationOfOmniBrowser]' and | | > '1.1 | > | | > | > [ConfigurationOfAutomaticMethodCategorizer]' are the same which | > | > means that they are both referenced in '1.1 | > [ConfigurationOfPharo]'. | > | | > | > That was enough to solve this particular problem, but in an | > | > Inspector, you can dive into the directives themselves and | > actually | > | | > | > get to the MetacelloSpec that was used to create the | directive... | > | > | > | > | > | > | > | > Here is what I don't understand. If you have that directive, and | | > you | > | | > | > have ALL that information, can't you guess that if you need to | | > load | > | | > | > the N version of a package and then the version M, where M > N, | | > then | > | | > | > you can skip to load N and just load M directly ? | > | > | > | > In this example, can you DO NOT load OmniBrowser-lr.458 as you | | > know | > | | > | > that after you will load OmniBrowser-lr.469 ? | > | > Or maybe directly about conf: Do not load 1.1 | > | > [ConfigurationOfOmniBrowser] if you know that then you will | need | > | | > | > to load 1.1.3 [ConfigurationOfOmniBrowser] | > | > | > | > Thanks a lot for the explanation dale! | > | > | > | > mariano | > | > | > | > _______________________________________________ | > | > Pharo-project mailing list | > | > Pharo-project(a)lists.gforge.inria.fr | > | > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo- | > project | > | | > | -- | > | _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: | > | Alexandre Bergel http://www.bergel.eu | > | ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;. | | -- | _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: | Alexandre Bergel http://www.bergel.eu | ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.

May 5, 2010

Re: [Pharo-project] Help System

by Alain Plantec

Le 05/05/2010 15:24, Torsten Bergmann a Ã©crit : > P.S: I'm still in favour of well structured books in separate > packages than mixed code/docu in one package since you > may wish to unload docu for deployment/runtime scenarios. > Hi Torsten, all Yes, we had exactly the same discussion (one year ago? I can't believe it) about the settings package. An advantage of the builder approach is that one can simply choose: It is possible to let documentation methods (#helpOn: aBuilder ...) and code mixed in a single package without introducing any dependency or choose to have two packages, one for the documentation and the second for the code. Cheers Alain > > > > > > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

May 5, 2010

Re: [Pharo-project] [squeak-dev] Overrides. Evil. Need to do something with it.

by Igor Stasenko

2010/5/5 StÃ©phane Rollandin <lecteur(a)zogotounga.net>: >> myMethod >> Â <doNotOverride> > >> What you think? > > It seems to me that this is half-way from proper defining of an API. > Why not be more explicit by specifying which API relies on that method, > like: > I don't think so. A method, which should not be overridden belongs to a class where its defined. And a class belongs to certain package. So, there is already enough information what API owns that method. And if you are talking about overriding an extension provided by another external package... i.e. when original method has category: *Foo-extensions and installed package tries to override with with own *Bar-extensions it should be prohibited at all, without giving any chances to load this package into a system. > myMethod > Â <API: myGreatApp> > > This would imply that it should not be overidden, but then if the user wants > to override it nonetheless he would know what API he is messing up with. > > Stef > -- Best regards, Igor Stasenko AKA sig.

May 5, 2010

Re: [Pharo-project] Help System

by Lukas Renggli

> "it is a design flaw" > "Being forced to have strong references ... " > "makes it impossible to just include some documentation" > "This doesn't encourage me at all" > "..." > > So many negative statements in one post, look like you had > a bad day today ;) Not really, I was just trying to load a package with help into an image without the HelpSystem loaded. *boom* I thought I could give some feedback before it got adapted more widely. We had exactly the same discussion with the menu and settings system a few months back. > Â a) If you want to provide API help (reference docu) > Â Â Â you DONT HAVE ANY reference or dependency since you can comment your > Â Â Â classes and methods in the usual Smalltalk way using class/method > Â Â Â comments. > Â Â Â No need for "HelpSystem-Core" to be around, NO REFERENCES, > Â Â Â and NO EXCUSE NOT TO document your code ;) Status quo, yes. I see documentation more exposed through the HelpSystem browser though, which i found a really nice way to browse documentation. > Â Â Â Would you call it a design flaw of SUnit to create tests > Â Â Â by subclassing the class "TestCase" so that it is known to > Â Â Â the system as test case and also shows up in the TestRunner? Yes, absolutely. Any other unit testing framework in the world does not force you to subclass from a common superclass when writing tests. > Â 4. By using pragmas (loose coupling) you have to deal > Â Â with the problem that by your parent topic may not be > Â Â there/not be loaded since it can be defined somewhere else > Â Â in the class hierarchy. I would not make the books extensible themselves, that complicates things and is rarely needed in practice. The exact same problem is solved in the settings system quite nicely. > So I was pragmatic and used Plain old Smalltalk classes and method > to define the books (POSCAM). It doesn't have to be pragmas (although I think it should). It could also just be a class side method #buildHelpOn: that is called when opening the browser and that gives each class the possibility to add some documentation. I am just saying that I am not going to create an extra package just for the sake of documentation. Documentation is really crucial and it needs to be super easy to create, otherwise it is simply not going to happen. Creating an extra package is complicated and doesn't give me any benefit as a developer, so very likely I am not going to do it. Lukas -- Lukas Renggli www.lukas-renggli.ch

May 5, 2010

[Pharo-project] Pharo sprint in Brussels

by Johan Brichau

Hi! We are organizing a Pharo sprint in Brussels on June 11 & 12th. An entry has been added to the page http://code.google.com/p/pharo/wiki/PharoSprints Please, add your name if you wish to participate. Some more info on practical issues to follow soon... ---------------------------- Johan Brichau johan.brichau(a)uclouvain.be

May 5, 2010

Re: [Pharo-project] Overrides. Evil. Need to do something with it.

by Simon Denier

On 5 mai 2010, at 15:41, Igor Stasenko wrote: > Hello, > > there is a certain critial places in system, which should not be > overridden by external packages. > Otherwise, it becomes a mess and usually leads to malfunction in key > system parts: compiler, special objects etc. > > I'd like to propose to introduce a special marker pragma for methods, > which should _never_ be overridden by external package. > > myMethod > <doNotOverride> > > an MC code loader should honor this pragma, and do not attempt to > override this method when installing a package > or at least ask user that there is a risk of getting serious problems, > if you override this method. I think that the MC loader should ALWAYS warn user when an extension attempts an override, and let him choose (especially as the system does not allow to revert an override for now). Unfortunately the feature has been broken for long. Damien C proposed a solution a long time ago but it didn't work for me. Perhaps the bug is more subtle. -- Simon

May 5, 2010

[Pharo-project] Overrides. Evil. Need to do something with it.

by Igor Stasenko

Hello, there is a certain critial places in system, which should not be overridden by external packages. Otherwise, it becomes a mess and usually leads to malfunction in key system parts: compiler, special objects etc. I'd like to propose to introduce a special marker pragma for methods, which should _never_ be overridden by external package. myMethod <doNotOverride> an MC code loader should honor this pragma, and do not attempt to override this method when installing a package or at least ask user that there is a risk of getting serious problems, if you override this method. What you think? -- Best regards, Igor Stasenko AKA sig.

May 5, 2010

Re: [Pharo-project] Help System

by StÃ©phane Ducasse

On May 5, 2010, at 3:24 PM, Torsten Bergmann wrote: > Hi Lukas, > > "it is a design flaw" > "Being forced to have strong references ... " > "makes it impossible to just include some documentation" > "This doesn't encourage me at all" > "..." > > So many negative statements in one post, look like you had > a bad day today ;) PhD stress :) >> > .... > Attached is a simple (rough)example that it is easy to extend the help > system the way you may want (with a builder similar to system settings > and your above example) Good this is what I want. I want to leverage the tests we have. Since we can remove tests anyway. > > Just load it into an up to date core 1.1. image and evaluate: > > HelpBrowser openOn: PragmaHelp > > Look at class Foo and Bar to see that there is no dependency > and PragmaHelp/PragmaHelpBuilder to see how it is done. > > HelpSystem is flexible, you can also have external help sources > as I've shown with the IRC example. > It just depends on how you want to describe and structure your > documentation... > > Bye > Torsten > > P.S: I'm still in favour of well structured books in separate > packages than mixed code/docu in one package since you > may wish to unload docu for deployment/runtime scenarios. > > > > > > -- > GRATIS fÃ¼r alle GMX-Mitglieder: Die maxdome Movie-FLAT! > Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01 > <HelpSystemWithPragmaHelp.1.cs>_______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

May 5, 2010

[Pharo-project] Help System

by Torsten Bergmann

Hi Lukas, "it is a design flaw" "Being forced to have strong references ... " "makes it impossible to just include some documentation" "This doesn't encourage me at all" "..." So many negative statements in one post, look like you had a bad day today ;) My comments below: a) If you want to provide API help (reference docu) you DONT HAVE ANY reference or dependency since you can comment your classes and methods in the usual Smalltalk way using class/method comments. No need for "HelpSystem-Core" to be around, NO REFERENCES, and NO EXCUSE NOT TO document your code ;) b) If you want to provide similar tutorials help (books/system help) that should appear in the "SystemHelp" then the answer is YES, HERE WE HAVE A DEPENDENCY since you subclass "CustomHelp" and reference "HelpTopic". But this is intended since after a few experiments with other solutions this was a very natural way to define the book contents. Would you call it a design flaw of SUnit to create tests by subclassing the class "TestCase" so that it is known to the system as test case and also shows up in the TestRunner? Does the dependency on SUnit make it impossible for you to write tests? Or does it even encourage you not to write tests? So please revise your statements. And yes, in the scenario I'm up to you typically provide a separate help package that can be separately loaded/unloaded. It depends on your deployment scenario if you want to keep it in the image or not. So a separate package makes sense for these tutorials. Either you ship with tests and docu or just with the code. If you deploy and ship an end user app for instance you would just need "SQLite-Core" and may unload "SQLite-Tests" and "SQLite-Help". If someone works with code (for instance SQLite) he can - either use the known API help (either in the Class browser or the HelpBrowser, see a) - or load the additional package with mostyl more generalized tutorials/manuals/books, its up to you to provide such an additional help package ("SQLite-Help" for instance) However - these two scenarios are provided by DEFAULT. You have a different scenario since where (if I understand you correctly) you want: c) Provide documentation that - is not defined in usual class/method comments - should be packaged with your code package instead of a separate one - should not be dependent on any class in the HelpSystem-Core package - may already be defined Here I would suggest you to find an appropriate way to write and store your documentation (for instance in methods with pragmas) the way you want AND INDEPENDENT from the current help system. If you want to have it shown later in the help system/help browser too you need to provide at least an (extension) method #asHelpTopic or use an own builder (see HelpBuilder and subclasses) to convert your documentation style to the generalized help topic hierarchy the browser is able to display. When you talk about an extensibility of the help system similar to preferences/menu building then you mainly talk about a pragma solution here: I already experimented with this in the early help system (see HelpSystem-Core-tbn.4) for instance and later switched to the subclassesing solution (similar to SUnit) mainly for the following reasons: 1. it is more intentional to directly map the book structure to the class hierarchy 2. You can use the usual ST tools to manage or refactor your books (the class hierarchy browse even shows you the topic hierarchy) 3. It is hard to describe a complete book structure (with page order, nested books and the like) in pragmas If you have a good solution then I'm all ears here. 4. By using pragmas (loose coupling) you have to deal with the problem that by your parent topic may not be there/not be loaded since it can be defined somewhere else in the class hierarchy. By mapping to the class hierarchy you cant run into the problem since you need the superclass (parent topic definition) for the subclass (subtopic definition) to be loaded. So I was pragmatic and used Plain old Smalltalk classes and method to define the books (POSCAM). But Help System does not limit you, currently we have a) and b) to define and bring help into the help system/help browser. If you have a good solution for defining complete books with structure using pragmas then we can include it... Meanwhile Lukas wrote: >Yes, I imagine something along ... > >PPParser class>>helpOn: aBuilder > <help> > Attached is a simple (rough)example that it is easy to extend the help system the way you may want (with a builder similar to system settings and your above example) Just load it into an up to date core 1.1. image and evaluate: HelpBrowser openOn: PragmaHelp Look at class Foo and Bar to see that there is no dependency and PragmaHelp/PragmaHelpBuilder to see how it is done. HelpSystem is flexible, you can also have external help sources as I've shown with the IRC example. It just depends on how you want to describe and structure your documentation... Bye Torsten P.S: I'm still in favour of well structured books in separate packages than mixed code/docu in one package since you may wish to unload docu for deployment/runtime scenarios. -- GRATIS fÃ¼r alle GMX-Mitglieder: Die maxdome Movie-FLAT! Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01

May 5, 2010