Stef wrote:
Hi danny
I would like to integrate your help system in pharo so we will have see how we can proceed. ... Yes this is good for my ego :)))
Hey, hey ... and it is not good for my ego if you keep saying it is danny's help system! Ever looked at the project and code? ;) While I appreciate that Danny wants to contribute to the project I think his changes are not aligned with the original goals, design and ideas. First and most important: I want a simple model for the help system, which I first provided as HelpTopic HelpBook HelpPage after Danny's changes the baseline now looks like this: HelpTopic DynamicHelpPage ClassAPIHelp MethodListHelp PackageAPIHelpBook HelpBook HelpPage I have several problems with these three introduced classes: - They do not stand the "is a" inheritance test since a book (PackageAPIHelpBook) now "is a" page (DynamicHelpPage) - To make it even worse the class DynamicHelpPage adds three new instance variables (using blocks) totally ignoring the ivars inherited from HelpTopic (leaving unused slots in the instances). - the three new classes are more intended towards extracting/building the three types of dynamic help informations (package, class, method), So the behavior is more oriented towards "building" a book or page - but this is what the (yet unfished) builders are used for. Therefore the classes are also misplaced. - there is no single test provided Sorry Danny - but your changes look more like a quick way on getting a dynamic help "hacked in" than a clean design towards a stable Pharo help system! However - I'm in the midst of refactoring all this and hope to provide an even simpler model than the one I originally used. Please be a little bit patient before we all jump into this "feature adding thing". Stef/Danny wrote:
I would like to add it in a modular way. Does anybody has a nice idea? I am not sure what you mean by modular. It has a Metacello configuration.
Yes, it has a Metacello configuration which currently separates the test from the Core model/UI. My further work will provide an exchangable and more enhanced UI and no dependency on the Help system itself (at least for in image docu). I'm currently testing some ideas.
my point is if you imagine that we want a small system with good packages where do we put the helpSystem.
I intend to use pragmas to decouple this. So you could comment your code without having the help system installed. We have to make a clean distinction for the help system for: - in image documentation on classes/methods/packages/test cases that can also be accessed by the usual tools like browsers - big-picture like help (books, tutorials) I know you are all eager to play with the first in the help system but I think the second has more value and need for a help system.
A nice idea on squeak-dev was to add support for a simple structured markup language like Markdown in class comments. We could use this to write "big- picture" documentation directly in a class comment.
Yes ... but a class comment is as the name implies just a comment for a class. You typically dont write a "big-picture" documentation in a class comment. If you write a documentation on how to use Streams, Collections or Exception Handling ... which is the class you would use for the comment? Dont get me wrong: I like well described classes but the Help system should mainly address the "big-picture" documentation for tools, frameworks, the system, ... Adding other types like the dynamic API help are easy to integrate/generate. Another goal is to use the HelpSystem to document a (commercial) software you have written in Pharo or reuse the content for a documentation appearing on a website. Danny wrote:
In a package you put in the most important class a comment that looks somehow like this:
How do you measure the importance of a class ... ? ;) Stef wrote:
we can load HelpSystem and use it but since we want to have core we should get it in Pharo but still make sure that everything in Core is adapted to give info to Pharo.
Two simple goals: - help is always optional and core could be without it - infos provided should not be dependent on the help system itself (for comments)
In addition I would like to have a tag for promoting test to be list in the help. <documentation>
Would be nice.
Yes, there are many things that would be nice like generating books/pages from tests or examples or even dynamically build UML diagrams. We can have that in future. But first we need a simple and good model we can built on and I'm working on it. Maybe I released too early ... Thanks T. -- GMX DSL: Internet, Telefon und Entertainment für nur 19,99 EUR/mtl.! http://portal.gmx.net/de/go/dsl02