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