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