About danny help :)

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

On Mar 5, 2010, at 9:25 PM, Torsten Bergmann wrote:

> 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?  ;)

;)
I noticed it :)


You are the boss there. I was not aware of the design and I did not look at the code.
I was just reading tests and class comments and I would like to get some of them promoted to help :)

> 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".

we are not in rush.

yes this is important
>
> 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)

you lose me there. ;)

> 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.

ok I guess I got it.
But I'm pragmatic.
        - how to we fill up the help
        - when I here book I know the pain it is to write.
ok

No this is interesting to get ideas.
For the UML I would like to have a simple sccripting descriptoin so that we can define it.



_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project