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 _______________________________________________ Pharo-project mailing list [email protected] http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
