About danny help :)

Hi danny

I would like to integrate your help system in pharo so we will have see how we can proceed.
I would like to add it in a modular way. Does anybody has a nice idea?
Now I would really like to see how we can produce some help automatically like by tagging and commenting
some cool SUnit tests.
At least we should have it in pharo-dev.

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

Am Dienstag, 2. März 2010 21:36:07 schrieb Stéphane Ducasse:

Hi!
Do you mean ProfStefBrowser (frontend fo ProfStef) or HelpSystem (initially
started by Torsten)?

I am not sure what you mean by modular. It has a Metacello configuration.

With regard to automatic help, in HelpSystem API help on packages and
individual classes can already be generated automatically, and some very basic
support for tagging methods is implemented. Right now it generates a page with
documentation for all methods in a class, with methods tagged with <help>
reordered to appear at the top of the text.

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. I think this would
complement the method comments quite nicely.

Danny

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

>>
>
>
> Hi!
> Do you mean ProfStefBrowser (frontend fo ProfStef) or HelpSystem (initially
> started by Torsten)?

sorry I meant the HelpSystem
I want ProfStefBrowser in Pharo but not the core :)
Yes this is good for my ego :)))

> I am not sure what you mean by modular. It has a Metacello configuration.

my point is if you imagine that we want a small system with good packages
where do we put the helpSystem.

> With regard to automatic help, in HelpSystem API help on packages and
> individual classes can already be generated automatically, and some very basic
> support for tagging methods is implemented. Right now it generates a page with
> documentation for all methods in a class, with methods tagged with <help>
> reordered to appear at the top of the text.

Ok excellent I was not aware of that. what about the tag for SUnit tests?
>
> 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. I think this would
> complement the method comments quite nicely.

Do you have an example?
>
> Danny
>
> _______________________________________________
> Pharo-project mailing list
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project


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

>
> > I am not sure what you mean by modular. It has a Metacello configuration.
>
> my point is if you imagine that we want a small system with good packages
> where do we put the helpSystem.
Hm, still not 100% sure what you mean. If you're asking how we can have
documentation usable with HelpSystem without having to actually load
HelpSystem, then see below.

>
> > 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. I think
> > this would complement the method comments quite nicely.
>
> Do you have an example?
>

In a package you put in the most important class a comment that looks somehow
like this:

<classcomment>
Here comes the comment for the class
</classcomment>
<packagecomment>
This is the documentation for MyPackage.

# Introduction
A bit of introduction.
# Another chapter
More text.
## Structure
You can have sub levels


And this would create a documentation tree like this (text after the colon is
displayed in the content window):

- MyPackage: This is the documentation for MyPackage.
        - Introduction: A bit of introduction
        - Another chapter: More text
                - Structure: You can have sub levels
        - API documentation
                - Class1 documentation
                        - Instance Methods
                        - Class Methods
                - Class1 documentation
                        - Instance Methods
                        - Class Methods
                ...

Now you have all the documentation for a package in the comments, but you can
view it in a nicely structured way.

Does this make sense?

Danny

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

On Mar 4, 2010, at 8:48 PM, Danny Chan wrote:

>>
>>> I am not sure what you mean by modular. It has a Metacello configuration.
>>
>> my point is if you imagine that we want a small system with good packages
>> where do we put the helpSystem.
> Hm, still not 100% sure what you mean. If you're asking how we can have
> documentation usable with HelpSystem without having to actually load
> HelpSystem, then see below.

I was thinking aloud.
I was thinking
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.


Why XML?
where do you define
        <packagecomment>



Yes
In addition I would like to have a tag for promoting test to be list in the help.
<documentation>

Would be nice.

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


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

> > <classcomment>
> > Here comes the comment for the class
> > </classcomment>
>
> Why XML?

No special reason, just made up something, so that both a normal class comment
and the big picture documentation for the package can coexist.


> In addition I would like to have a tag for promoting test to be list in the
>  help. <documentation>

Hm, I just thought about this: Why not have one pragma, call it <help:>, that
takes as an argument some kind of string encoded path, for example for a test
with a nice example something like this:

testInstanceCreation
        <help: 'Examples/Instance Creation'>

        "Here we show some different ways to create new instances"

        ...

And then in addition to API documentation that strictly follows the class
structure we have dynamically generated books that are structured along the
help pragmas.

Danny

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

On Mar 5, 2010, at 7:50 AM, Danny Chan wrote:

Yes!! I proposed that several times already.
Could be prefixed automatically by the package in which the method is defined.


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


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