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