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