> 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. The point is to avoid duplicating code between a class and its help or between a testcase and the help. > Providing CustomHelp subclasses is easy to understand for the > "content writer" and system help is not spread around in the image. Yes but it can also be out of sync. I like literate programming just because the comments are in the code. > 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?). I'm not worried by having two classes extra in the system or core since help will not been referenced from everywhere. This kind of packages are easy to unload. I was more concerned about the idea that we can use the system to annotate what should be promoted as help. 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...). Stef _______________________________________________ Pharo-project mailing list [email protected] http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
