- Pharo-dev - lists.pharo.org

[Pharo-project] [Preview] Help System with new model
by Torsten Bergmann April 9, 2010

April 9, 2010

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

1 0

[Pharo-project] [Preview] Help System with new model
by Torsten Bergmann April 9, 2010

April 9, 2010

Michael Roberts wrote: > I think it should be possible for help to appear in the global help > browser without having to define a subclass of CustomHelp. This would > make the entry barrier really low for people to be able to document > parts of the system using this help system. Yes, I had a pragma solution using <helpTopic: 'Title goes here'> in one of the first versions - but it gets complicated if you want to define structured help contents with nested books and with pages in a specific order. The implementation is easy ... I mean with pragmas it would be complicated for the "help writer" to define these nested book structures and to remember the correct pragmas. And you have to solve the following scenario: you may have a class A defining a help book using pragmas and a class B defining another help book which should be displayed under the book defined by A. Since you do not rely on a "help class hierarchy" and are decoupled using pragmas both classes can live under Object. Good. Everything works fine when A and B are in the image. But you can get a problem when class A is not loaded - since the parent book of B is not there. I would not see a problem in having the help hierarchy clearly defined as a subclass hierarchy of a predefined "CustomHelp" class. Providing CustomHelp subclasses is easy to understand for the "content writer" and system help is not spread around in the image. You can see the structure in the class hierarchy browser and in the help browser. Thats wonderfull. For all these reasons I would prefer a CustomHelp for the standard help. (Independent from that the help browser itself is still capable to use anything with an #asHelpTopic interface). Providing the CustomHelp class is the same as with TestCase - you know that when you subclass you will later find it in the UI tool (TestRunner/help browser) and you can peek in other TestCase subclasses to see what is possible. And yes, that means that minimal help support (in minimum 2 classes HelpTopic and CustomHelp) is already in the image similar to SUnit. Dont know if the name CustomHelp is good (maybe HelpBook/SystemHelpBook?). Stef wrote: >do you have a new version that we could integrate to 1.1? see http://www.squeaksource.com/HelpSystem The baseline works fine in 1.1.#11309, but I would remove a few methods after integration (for Squeak and Pharo 1.0 compatibility, see #initWindowInSqueak #isSqueak #isPharo11 and senders). That's easy. However, it is already working in 1.1. and integration would just mean to load it: - the minimum support is in the Core package HelpSystem-Core-tbn.35 - the according tests (HelpSystem-Tests-tbn.9) are green in 1.1 too. Thats anything you need to have help support, the browser ("Tools"->"Help Browser") and the full API help stuff (just run "HelpBrowser openOn: SystemReference" or any other sample I provided). One thing: if you just have the "HelpSystem-Core" loaded the standard help browser for the system would only display the help for the help system itself. If you want to additionally provide infos/content on the Pharo project you need other packages like "Pharo-Project-Help". We can enhance "Pharo-Project-Help" and use it either for the dev image or core image. We can also keep "Pharo-Project-Help" minimal for the pharo core image with basic infos on the project and create a "Pharo-Project-Dev-Help" or others for the pharo developer image. I see three options: (1) integrate it in 1.1. core as you wrote (2) no help in pharo core to keep it minimal and have the help system as one of the first packages loaded in the pharo dev image (3) wait until we can enhance it with Scamper code, markup, ... (which takes more time than I have now) Another option (4) which I dislike: If you find the help-core package (which currently includes the UI browser) to much for a pharo-core image we can also split the package so that: - the core model is in the image (only classes HelpTopic and CustomHelp are really necessary) so one can define and write help content - the help browser and builders are loadable/exchangable afterwards I would keep them together since you need minimal support to visually control what you wrote and why have help contents in the image when you cant browse it ;) If you would follow that path I can argue that we have to keep the settings framework but provide the settings browser only in the dev-image. Same issue. Thats why I would either follow (1) or (2), but that is just MHO. Bye T. -- GRATIS fÃ¼r alle GMX-Mitglieder: Die maxdome Movie-FLAT! Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01

3 3

[Pharo-project] Linux vm: assertions and strategy
by Schwab,Wilhelm K April 8, 2010

April 8, 2010

Laurent, all, If I may jump to conclusions a little, the 3.11-3 vm's changes break the loading of libraries, certainly to the point of being arkane. Beyond that, LinuxODBC is transparent to it, so I am left wondering how it is suppose to work at all?? The RC3 one-click image and vm produce very nice fonts on my Ubuntu laptop, but it retains the FFI/double defect, and from the naming of the plugins, must be based on a pre 3.11-3 vm. Is the plan to use 3.11-3 for the one-click? If so, we need to do something about external libraries; at a minimum, LinuxODBC should work, whether by fully understanding how to use environment variables, or (as I suspect) getting the dlopen() call to work again. Another option is to identify the FPU related fixes and apply them to the current one-click vm. Any preferences? Any success with 3.11-3 and LinuxODBC? I'd be happy to be wrong about this. Bill

2 6

Re: [Pharo-project] Phari collaborActive book
by Tudor Girba April 8, 2010

April 8, 2010

Hi Geert, I created the user. Will send the password separately. Cheers, Doru On 8 Apr 2010, at 09:33, Geert Claes wrote: > Hi Doru, > > I would like to put my hand up to help a bit with the collaborActive > book. Not sure yet how much I can contribute but I have good > intentions, do I ask you for login details? :) > > Cheers, > > Geert -- www.tudorgirba.com "Every thing has its own flow."

2 1

[Pharo-project] CollabActive book :)
by StÃ©phane Ducasse April 8, 2010

April 8, 2010

Hi Pharoers We put in place (big big thanks doru, anton, lukas and gemstone for that) a pier book http://book.pharo-project.org/ The idea is that we can collect/edit.... information about pharo on this collaborative book. Now we would like that **you**/**us** control the quality of the contents. The book will be open: **you**= anybody from the pharo community can be editor (you should ask probably doru because I have to really make sure that I do not mess it up) but not everybody can change text, everybody will be able to add notes following the http://book.seaside.st principle. As an editor you can register to the rss stream and includes the comments. Now the idea is that after a while the ready to get publish parts may be used for Pharo by example 2 since we can generate automatically latex from the web. Now I would love to have chapter on - how to compile my vm on Mac OSX - how to compile my vm on linux - how to compile my vm on Windows - Understanding Announcement - Settings - Building UI with Polymorph.... - Help - ... So if you want to be an editor you are more than welcome! Just ask Stef

9 28

[Pharo-project] How to manage todo?
by StÃ©phane Ducasse April 8, 2010

April 8, 2010

Hi guys We have bug entries and now I have one question. Do we want to mix or not todo within them? I deleted all the old tasks from the inria web site. Now we could use it. Do you have experience managing todo (which may be orthogonal to issue and bug trcking)? Stef

8 15

[Pharo-project] Menu navigation
by Sean P. DeNigris April 8, 2010

April 8, 2010

It seems that the world menu navigation is not as usable as that of Squeak. For example, to go to full screen mode: Squeak: click -> move down -> click -> move down -> click Pharo: click -> move down -> move right -> click -> move down -> click What is the advantage of this way? Sean -- View this message in context: http://n4.nabble.com/Menu-navigation-tp1754368p1754368.html Sent from the Pharo Smalltalk mailing list archive at Nabble.com.

4 10

[Pharo-project] Expacted Resource (RAM) requirements to run Pharo
by Rudi Ludwig April 8, 2010

April 8, 2010

Hello, so I got interested in Smalltalk (again) installed Pharo and ran the ProfStef tutorial. I'm not a programmer, just interested :-) To be more precise, I followed the link on the Pharo homepage Download directory and installed from squeakvm.org/unix : Squeak-3.11.3.2135-solaris2.10_i386.tar.gz in - /usr/local/Squeak-3.11.3.2135-solaris2.10_i386 and from Pharo: Pharo-1.0-10515-rc3dev10.03.1 in my home directory. OS: OpenSolaris b127. Now while that worked --I can start Squeak (/usr/local/../bin/squeak.sh) chose the Pharo Image form the file browser that opens and go. Just following the integrated tutorial (ProfStef) and having maybe one more ClassBrowser open, at some point consumed 780 MB RAM (RSS). Question: Is that the expacted behavior (resource requirement) or is there something wrong with the steps I choose to run Pharo, although apparently they worked? There is a "PharoDebug.log" 180+kB large from that session, I can provide on request. (Didn't want to send it to whole list directly). Rudi

2 1

[Pharo-project] A small idea how to get closer to hardware with small efforts :)
by Igor Stasenko April 8, 2010

April 8, 2010

Hello again, it is about running a native code , stored in compiled methods. All we need is: a) allow code execution for object memory. On most platforms this is trivial - just pass additional flags to virtual memory allocation functions. b) add a single primitive 'call a native code' c) use a special compiled method trailer, which will store the native code inside itself Then we could place any native code inside a compiled method and use a single primitive to run this code. This is quite simple thing, given that both pharo and squeak adopted method trailers, so a primitive, before running the code, needs few checks: - a method's trailer format is valid (we could reserve a terminal byte value for that) - a native code, placed inside a method trailer is targeted for same platform as currently running on if not, then primitive will simply fail, and interpreter will run the method's bytecode, which , depending on a situation, can check if it can recompile the code (if platform doesn't match) or use a workaround. The only limitation of such approach, that native code, placed in compiled method should be relocate-agnostic, i.e. never use absolute jumps, only relative ones and so on. Also, we could force, that code using a specific calling convention, so it will be easy to fetch values from stack and other useful stuff from interpreter/object memory (like passing an interpreterProxy pointer). This could be a good answer in generating a trampoline code for FFI/Alien on the fly. What you think? -- Best regards, Igor Stasenko AKA sig.

4 8

[Pharo-project] Show Actions of a SystemWindow: bug?
by Carla F. Griggio April 8, 2010

April 8, 2010

Hello! I was fooling around with the latest rc3 image and I tried to use the "show actions" option in the menu of a SystemWindow and got this: *MessageNotUnderstood: ToolSet class>>openMessageList:name:autoSelect:* ToolSet class(Object)>>doesNotUnderstand: #openMessageList:name:autoSelect: SystemWindow(Morph)>>showActions [] in ToggleMenuItemMorph(MenuItemMorph)>>invokeWithEvent: BlockClosure>>ensure: CursorWithMask(Cursor)>>showWhile: ToggleMenuItemMorph(MenuItemMorph)>>invokeWithEvent: ToggleMenuItemMorph(MenuItemMorph)>>mouseUp: ToggleMenuItemMorph(MenuItemMorph)>>handleMouseUp: MouseButtonEvent>>sentTo: ... This is the code in SystemWindow>>showActions: showActions "Put up a message list browser of all the code that this morph would run for mouseUp, mouseDown, mouseMove, mouseEnter, mouseLeave, and mouseLinger. tk 9/13/97" | list cls selector adder | list := SortedCollection new. adder := [:mrClass :mrSel | list add: (MethodReference new setStandardClass: mrClass methodSymbol: mrSel)]. "the eventHandler" self eventHandler ifNotNil: [list := self eventHandler methodRefList. (self eventHandler handlesMouseDown: nil) ifFalse: [adder value: HandMorph value: #grabMorph:]]. "If not those, then non-default raw events" #(#keyStroke: #mouseDown: #mouseEnter: #mouseLeave: #mouseMove: #mouseUp: > #doButtonAction ) do: [:sel | cls := self class whichClassIncludesSelector: sel. cls ifNotNil: ["want more than default behavior" cls == Morph ifFalse: [adder value: cls value: sel]]]. "The mechanism on a Button" (self respondsTo: #actionSelector) ifTrue: ["A button" selector := self actionSelector. cls := self target class whichClassIncludesSelector: selector. cls ifNotNil: ["want more than default behavior" cls == Morph ifFalse: [adder value: cls value: selector]]]. *ToolSet openMessageList: list name: 'Actions of ' , self printString > autoSelect: false* Shouldn't the last line be MessageSet openMessageList: list name: 'Actions of ' , self printString autoSelect: nil ? I tried it and it seemed to work OK, although I never tried that option before so I don't know what was it's original behaviour. Cheers! Carla.

3 6