- Pharo-dev - lists.pharo.org

[Pharo-project] [Preview] Help System with new model

by Torsten Bergmann

Hi Stef and Michael, your responses have shown me that I may have not clearly communicated what is possible and what my goals are. It has also shown me that you mainly talk about the help system as to provide "API help" or reference documentation, which is possible but was not my main goal. So lets explain it in more detail: We have two separate cases/kind of help: A. Help for the system in front of you ("SystemHelp") Documentation of a tool or a process (General Tool Help/Tutorials/F1 Help/Written Book) B. Help on how the system in front of you is implemented ("SystemReference") Documentation of classes and methods, examples as in any other Smalltalk/Dev system ("API Help"/Class comments/Method comments) Regading A - Help for the system in front of you ("SystemHelp"): ================================================================ Just evaluate HelpBrowser openOn: SystemHelp or just HelpBrowser open My initial goal was to do have "F1 Help" as in most other IDE's so a help browser opens to display a complete help book with a full written Tutorial on how the Monticello Browser works. Or how one is able to work with Metacello or what object oriented programming is all about, or how one is able to create a project on Squeaksource. We could even have an ASCII version of "Pharo by Example", ... This kind of help doesnt even have to be related to stuff that is in the image. You could provide books on gardening and read them in the image if you like. ;) This kind of help could have been external in files or on a webpage, - but I since my goal was that one can read/display it also within the image I JUST (AB)USE classes and class hierarchies to store the help book contents. This also allows to manage the books and contents with usual Smalltalk tools and (if required) also to provide dynamic content. But typically these classes just provide the help contents and it is intended that they have no behavior! I dont want this to be limited to tutorials or tool help. Think of a case where one writes a card playing game with Pharo and want to provide a help book to the commercial end user explaining the game. I know it is much more effort to write such documentation - but for the dev-image/pharo tools we may provide at least simple books to explain basic things like the project itself, license, how to get started with the tools, ... Since this kind of help is typically structured like a real book there is the "CustomHelp" class allowing you to map your books structure directly to subclasses. If you write such a "class mapped" book you want to keep the book/subbooks/pages together and not spread around the image. And I call this "System help" since it shows you help to explain the system that is in front of you (either Pharo or the commercial card game). When you run HelpBrowser open this "SystemHelp" (see the according class SystemHelp) just collects all direct subclasses of CustomHelp as root books. Nothing more. So if you want to have your book appear in this "system wide help" you: 1. either store your book contents in the CustomHelp hierarchy (this is the typical case where you map the book to subclasses, see class "HelpOnHelp" or "PharoHelp" for example) 2. or provide a direct/indirect CustomHelp subclass to just define the book to appear in the system help but get the contents from other sources (see class "PharoAPIHelp" which allows us to provide the whole class API in the Pharo book) Especially the second option allows you to mix dynamic content like API Help into these "system help books". Just open the chapter "API Reference" in the "Pharo" book when you have the package "Pharo-Project-Help" loaded. More on this later. Dont get me wrong, it is alway possible to open the Help browser on any object that is able to convert itself into a HelpTopic instance using #asHelpTopic HelpBrowser openOn: myObjectWhoCanBeConverted but it is necessary to have a subclass of CustomHelp it appears in the default "system wide help" (SystemHelp) when you open the browser using the menu or by "HelpBrowser open". So CustomHelp is the entry point here, nothing more! To summarize: - A. is intended for whole books and a system wide help system - A. requires the class "CustomHelp" - to define at least the "root books" appearing in this "System help" - to allow mapping a book structure directly to a class hierarchy (and keep this book with its subbooks together) Providing such a help was the original goal of the help system which is now fully possible. Still plain ASCII and without support for markup, images, ... yet - but usable. Regarding B - Help on how the system in front of you is implemented ("SystemReference"): ====================================================================================== Just evaluate HelpBrowser openOn: SystemReference Beside A. there is also "Documentation of classes and methods" as we have in any other programming languages or Smalltalk systems. Maybe also enhanced with provided examples. I think this is what you both want. But this is "help" oriented towards developers since you wont need that for the end user if you ship your commercial card playing game ;) This kind of "browsable developer help" is what you both seem to understand when you speak about the "Help system". To me this is nothing more than documentation on how the system is implemented. It is a reference of the system - we already have it in the image with class comments, method comments. I call this "API-Help" or "System reference" (see the class SystemReference) and is only a subpart of a help system that I want. Anyway - the general help system is able to work with it too since you can build books from any source. Dont be afraid: the developer typically uses the Smalltalk browser to define and look at the comments as before. There is no dependency on the help system here. But if the help system is loaded he is able to get a better summary using the help tools: HelpBrowser openOn: SystemReference or HelpBrowser openOn: Integer or HelpBrowser openOn: (SystemReference hierarchyFor: Integer) since the info is just extracted by a builder or an object that converts the contents into help topics with structure. So the place where the help contents for B. is defined (class comments, method comments, ...) is not bound to the help system and the builder decides what is extracted and from what source. See HelpBuilder subclasses for example. So when Stef wrote: "The point is to avoid duplicating code between a class and its help or between a testcase and the help". I can just answer: there is no duplication, nothing has changed here, you document your classes and methods as before and you dont need a subclass of CustomHelp or the help system to do that!!! But if me may want to enhance the informations that can be extracted by the builder here or spice up the "API help" browsing experience we can define pragmas that can later be used by the help builders (like the current ClassAPIHelpBuilder). If we want to drive this forward then we should discuss about having not only Pragmas for methods but also for classes. For instance in Java I'm able to add annotations to a class comment: @author: Tut Ench Amun @version: 1333-1324 BC that is later used by the JavaDoc system. AFAIK Pragmas in Pharo are currently limited to method level. If we would have this HelpBrowser openOn: Integer could show the author, version, whatever you like. You just have to define what you need and enhance the builder to extract it. To summarize: - the more general help system (A) is able to display contents from any source including help contents extracted from usual Smalltalk classes/methods (B) - there is no dependency between the documented classes/methods and the help system itself in any case - if we want to enhance this part we can define pragmas that can be used by a help builder to provider a better "system reference" experience Long story, but in general: please dont see the help system as a better "documentation" browser to document your classes. It's more. Michael wrote: >I just wonder if the definition of the help (the raw content) should also >be bound up with the definition of the overall structure? For A. if you write a full book as described in A. I would answer YES since it helps to see the books structure also in the class hierarchy browser For B. the structure is already separated since it is defined by the builder depending on your needs, compare: HelpBrowser openOn: (SystemReference forClass: Integer) HelpBrowser openOn: (SystemReference hierarchyFor: Integer) HelpBrowser openOn: (SystemReference hierarchyWithMethodsFor: Integer) >So that's why i think of it in terms of annotations. >Having the help be in its own help class, on the class side, without >any real behavior is a design smell to me. You didnt understand why I provide "CustomHelp". Having a subclass is only necessary when you map a book structure to a class hierarchy. It is intended that these books typically have no behavior since they are just used to store book contents. You can see it as a vehicle to bring text content into the image (similar to WAFileLibrary subclasses in Seaside to bring in resources like images, stylesheets). This has nothing to do with a design smell. You seem to be too much focused on API like help. And I always said that we can use annotations for B. here to keep it independent from the help system. If you want to reference documentation for your classes you dont need to use CustomHelp! If you read you will see that I said it is harder to describe the structure of a full book using pragmas when you want A. I would prefer the CustomHelp subclassing here since you find your books structure also in the class hierarchy. Stef wrote: >Yes but it can also be out of sync. This is more related to us all beeing lazy writing and maintaining docu ;) >I like literate programming just because the comments are in the code. You can continue to have that, I see no conflict here >Writing separate and maintaining doc is costly and I was thinking that >I wanted to reuse as much as possible as the existing information (class >comments, unit tests...). Yes, but there is little value in this since you can already access this using the usual Smalltalk tools. Its just a simple way to fill the help browser with contents, but we have it now. ;) Convinced for inclusion? Bye T. -- GRATIS fÃ¼r alle GMX-Mitglieder: Die maxdome Movie-FLAT! Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01

April 9, 2010

Re: [Pharo-project] Canvas transform bug when rendering text?

by StÃ©phane Ducasse

On Apr 9, 2010, at 11:28 AM, Lukas Renggli wrote: > I don't write code like this. It was a joke :) but I really like the visual effect > Rotating a window is just a good test to > see if works, because it calls all kind of different code. > > If you rotate a more complex window than a workspace, my system hangs > btw. So there must be other stuff broken there. oops with the fix too? > > Lukas > > On 9 April 2010 11:20, StÃ©phane Ducasse <stephane.ducasse(a)inria.fr> wrote: >> funny way to type code. >> >> Stef >> >> >> >> _______________________________________________ >> Pharo-project mailing list >> Pharo-project(a)lists.gforge.inria.fr >> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project >> > > > > -- > Lukas Renggli > www.lukas-renggli.ch > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

April 9, 2010

Re: [Pharo-project] Canvas transform bug when rendering text?

by Lukas Renggli

I don't write code like this. Rotating a window is just a good test to see if works, because it calls all kind of different code. If you rotate a more complex window than a workspace, my system hangs btw. So there must be other stuff broken there. Lukas On 9 April 2010 11:20, StÃ©phane Ducasse <stephane.ducasse(a)inria.fr> wrote: > funny way to type code. > > Stef > > > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > -- Lukas Renggli www.lukas-renggli.ch

April 9, 2010

Re: [Pharo-project] Canvas transform bug when rendering text?

by StÃ©phane Ducasse

funny way to type code. Stef

April 9, 2010

Re: [Pharo-project] Canvas transform bug when rendering text?

by Lukas Renggli

Pay attention there is a #haltOnce in the code. Also there is something wrong with the line endings in the change-set. The change solves the problem with the vertical text in eCompletion, so this is very cool. However it also breaks some window refreshing, see attached screenshot. Lukas On 9 April 2010 08:51, StÃ©phane Ducasse <stephane.ducasse(a)inria.fr> wrote: > thanks! > > PS: I will integrate some other fixes when back to the garage later today.... > Got stuck on the highway without gaz :) ... yesterday. >>>> >> >> David, Lukas, whomever else it may concern. >> >> Of course I turned out to be (partly) wrong when looking into it. >> Transform does indeed not work with alpha, but not because of bugs in WarpBlt as I assumed, but because FormCanvas always uses the Paint rule when rotating... >> Try the attached code, and you should get better results. (you probably want to use smoothing > 1 if displaying text with rotation other than a multiple of 90 degrees). >> >> This seems to be more of a generic problem though, looking at the number of places a= 32 ifTrue: [] check is made, I'll try to come up with a more consistent solution for a system-wide patch. (which amongst other things would also fix the black border appearing around a window while zooming back to old position when you drag and drop it outside main window) >> >> Cheers, >> Henry >> <FormCanvas-transformByclippingToduringsmoothing.st>_______________________________________________ >> 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 > -- Lukas Renggli www.lukas-renggli.ch

April 9, 2010

Re: [Pharo-project] Initial experience coming from Squeak

by StÃ©phane Ducasse

Hi fernando I will integrate your changes + lukas and a couple of toher later today. Stef On Apr 9, 2010, at 9:45 AM, Fernando olivero wrote: > > On Apr 9, 2010, at 8:26 AM, Lukas Renggli wrote: > >>> * Single/multi-line popups - when you're extracting a method via "refactor >>> source," you get a huge multi-line popup window, which eats crs, so after >>> you enter the name and hit return, you are still in the popup and must take >>> your hands off the keyboard to click "ok." >> >> It also annoys me sometimes too, but a few months back somebody was >> requesting exactly the opposite. The one-line input field does not >> work well if the method has more than one argument. I guess I need to >> build a dedicated editor for method names? >> > > You could specialize the EntryFieldMorph Stef integrated in 1.1. > It's a single line entry field, that when accepted with Character cr or escaped, announces it via Announcements. > > I've been wanting to implement a specialized SelectorWithArgumentsEntryField also, that heavlily uses the refactoring engine when the user enters input. Its in my todo list, but still couldn't find the right time. > > Fernando > > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

April 9, 2010

Re: [Pharo-project] Initial experience coming from Squeak

by Fernando olivero

On Apr 9, 2010, at 8:26 AM, Lukas Renggli wrote: >> * Single/multi-line popups - when you're extracting a method via "refactor >> source," you get a huge multi-line popup window, which eats crs, so after >> you enter the name and hit return, you are still in the popup and must take >> your hands off the keyboard to click "ok." > > It also annoys me sometimes too, but a few months back somebody was > requesting exactly the opposite. The one-line input field does not > work well if the method has more than one argument. I guess I need to > build a dedicated editor for method names? > You could specialize the EntryFieldMorph Stef integrated in 1.1. It's a single line entry field, that when accepted with Character cr or escaped, announces it via Announcements. I've been wanting to implement a specialized SelectorWithArgumentsEntryField also, that heavlily uses the refactoring engine when the user enters input. Its in my todo list, but still couldn't find the right time. Fernando

April 9, 2010

Re: [Pharo-project] Initial experience coming from Squeak

by StÃ©phane Ducasse

On Apr 9, 2010, at 5:57 AM, Sean P. DeNigris wrote: > > I love the clean look with all the great developer features pre-installed > (shout, OCompletion, etc.). It's been a pleasure to work with. > > And, a few things stood out that didn't seem to work as well. I'm sharing > them here because I wonder what your opinions are. Also, what is the policy > about contributing "good ideas" i.e. new/altered features that are not bug > fixes? Is it best to discuss them on the list like this, or submit a > changeset right off the bat per > http://code.google.com/p/pharo/wiki/HowToContribute? Yes! We are open to a lot of suggestions. For example in 1.1 the way you define method category is waaaaaayyyyyyy better. Check it you will see (even if there is a small bug). > > Suggestions: > * Why shift for meta? On a Macbook (with one button), it's awkward to press > shift+alt+click, and also disorienting to go back and forth from Squeak > which is just alt+click. Is there a reason to not keep the convention? I do not remember. What we did was to stop the halos popping up plague. You can get halos but only when you want. > * what is with the workflow of the default browser? When you click on a > protocol, the method template appears in the bottom pane, all highlighted > and ready to be replaced. But because hovering over the pane doesn't give > it the keyboard focus (like Squeak), you have to click in it, which > unselects the template, which you then have to reselect manuallyâ¦ Certainly > not a big deal, but weird. I though of a few possible fixes: People already reported that to me informally A bug fix would be good. Can you open or check if there is bug entry? > - automatically give the bottom pane the keyboard focus when working in > the protocol column (which doesn't seem to need it (I like this one - fewest > steps for the user) > - don't have the template pre-selected, so that clicking in the pane below > the template selects it (easiest fix, requires one more user click) > > * bizarre window changing - the (on Mac) Cmd+(hold arrow) to rotate through > the open windows is pretty cool, but when you tap the arrow key (instead of > holding it), it just goes back and forth between two windows, which I can't > see a use for. It seems it would be more useful to have the behavior to be: > if you hold down the Cmd key and repeatedly tap the arrow hit, the windows > rotate one after the other until you get through them all and recycle and > v.v. for the opposite direction arrow. sound like a good idea. suggestion: repost a mail with that title. open a bug entry. make noise so that ui aware people get a look :) > * new windows e.g. workspaces appear wherever they feel like (is it a > standard location?). It seems to flow better if they appeared where the > user is already looking i.e. where the active hand is. Good point. Same process. chekc the realstateAgent class > * Single/multi-line popups - when you're extracting a method via "refactor > source," you get a huge multi-line popup window, which eats crs, so after > you enter the name and hit return, you are still in the popup and must take > your hands off the keyboard to click "ok." Now, fair enough, this might > actually be a good thing in other circumstances, but - when you reference an > unknown class, you get an "unknown variable" popup, choose "define new > class," click through the category selection, you get a one-line popup to > edit a paragraph-long class definition, lol! So: > - "refactor source->extract method" should be a single-line popup > - and, "define new class->edit class definition" should be a multi-liner. It sucks!!!! I will integrate lukas changes. > > Thanks for an awesome environment, and I will continue to contribute any way > I can :) > > Sean P. DeNigris > -- > View this message in context: http://n4.nabble.com/Initial-experience-coming-from-Squeak-tp1799044p179904… > Sent from the Pharo Smalltalk mailing list archive at Nabble.com. > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

April 9, 2010

Re: [Pharo-project] Initial experience coming from Squeak

by Adrian Lienhard

Hi Sean, Thanks a lot for the valuable feedback! On Apr 9, 2010, at 05:57 , Sean P. DeNigris wrote: > > I love the clean look with all the great developer features pre-installed > (shout, OCompletion, etc.). It's been a pleasure to work with. > > And, a few things stood out that didn't seem to work as well. I'm sharing > them here because I wonder what your opinions are. Also, what is the policy > about contributing "good ideas" i.e. new/altered features that are not bug > fixes? Is it best to discuss them on the list like this, or submit a > changeset right off the bat per > http://code.google.com/p/pharo/wiki/HowToContribute? Normally I would do both. If you have code, commit it and create a ticket (not only for bugs but also for features). Then announce it in the mailing list. Since many people are busy, sometimes you don't get a response immediately, especially if it requires somebody loading the code and trying it out. In this case just send a reminder and explicitly ask people for feedback. For the list of suggestions you gave, you may want to wait for other feedback and then create single issues in the tracker for those that other people feel should be changed. Cheers, Adrian [...]

April 9, 2010

Re: [Pharo-project] Initial experience coming from Squeak

by StÃ©phane Ducasse

Thanks lukas Yes the code on the fly is terrible :) Fernando has been working on new version of textEditor and I will integrate them in 1.1 (with some bugs left) stef >> * Single/multi-line popups - when you're extracting a method via "refactor >> source," you get a huge multi-line popup window, which eats crs, so after >> you enter the name and hit return, you are still in the popup and must take >> your hands off the keyboard to click "ok." > > It also annoys me sometimes too, but a few months back somebody was > requesting exactly the opposite. The one-line input field does not > work well if the method has more than one argument. I guess I need to > build a dedicated editor for method names? > >> Now, fair enough, this might >> actually be a good thing in other circumstances, but - when you reference an >> unknown class, you get an "unknown variable" popup, choose "define new >> class," click through the category selection, you get a one-line popup to >> edit a paragraph-long class definition, lol! So: >> - "refactor source->extract method" should be a single-line popup >> - and, "define new class->edit class definition" should be a multi-liner. > > I 100% agree on this, class definition from within the editor totally > sucks. Unfortunately this is part of the compiler, not the browser so > it requires a change to the parser. I propose the fix below, that also > avoids the extra question of asking for the category name. This is > unnecessary as it can be edited afterwards in the class definition > anyway. > > http://code.google.com/p/pharo/issues/detail?id=2286 > > Name: Compiler-LukasRenggli.208 > Author: lr > Time: 9 April 2010, 8:23:45 am > UUID: e0f99e58-08ce-46da-839d-88947b66d668 > Ancestors: Compiler-StephaneDucasse.207 > > - simplify and improve the user experience for class definition while > compiling a method > > Lukas > > -- > Lukas Renggli > www.lukas-renggli.ch > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

April 9, 2010