wiki style help

> Hi,
>
> Nice idea, I like the "wiki help description" for three reasons:
>
>   - its pragma based AND allows for definition of structured books
>     (so Lukas should be satisfied since he can define content
>      without dependency on help system)
>
>   - it allows us to reuse existing swiki contents
>     (if the full syntax is supported we can query existing
>      swikis!)
>
> So it is a nice idea and would be a good addition.
>
>
> I reworked Alains code to better fit the pluggable architecture
> of the HelpSystem framework (now using a builder):
>
> Use an updated 1.2 core image, code is attached
>
>    1. File in "Foo.st" (which defines a simple help description)
>          =>  no dependency on any help system
>
>    2. First I added a registration mechanism (pragma<systemHelp>
>       so one can add own help types to the system help
>       (the one that appears when you open the default help browser)
>
>          =>  load "AddToSystemHelpFix.1.cs"
>          =>  at least this fix should go into Core 1.2, so
>             no ugly hacks are necessary to appear in the
>             default help browser
>
>       I added a now fixed issue for core 1.2 on:
>         http://code.google.com/p/pharo/issues/detail?id=3511
>
>    3. I reworked Alains code so it uses a WikiStyleHelpBuilder
>       (similar to the other builders) and a WikiStyleHelp as
>       a new help type
>
>          =>  see WikiStyleHelp.5.cs
>          =>  if we agree on this we can integrated it into core too,
>             currently it is in an own class category/package
>          =>  "HelpBrowser openOn: WikiStyleHelp"
>             will show all contents defined using the wiki style syntax,
>             so only the one defined in class Foo appears
>          =>  "HelpBrowser open"
>             will show all help in the system (including the ones
>             defined in Foo)
>          =>  since it uses the new registration mechanism (see 2. above)
>             all these topics will also appear in the help browser
>             that is accessible from the menu
>
> I would vote for adding this to core 1.2 too. It's additional,
> nothing should break. What do you all think...
>
> And thanks Alain for the idea and initial code!!!
>
> Have fun
> T.
>
>
>
>
>
>
>

> Hi all,
> very cool, thanks Torsten.
> Now, I think it's better to wait 1.3 because 1.2
> is almost ready ...
> and I would use $! instead of $= as section
> marker to keep Pier compatibility.
> Cheers
> Alain
> Le 07/01/2011 14:16, Torsten Bergmann a écrit :
>> Hi,
>>
>> Nice idea, I like the "wiki help description" for three reasons:
>>
>>  - its pragma based AND allows for definition of structured books
>>    (so Lukas should be satisfied since he can define content
>>     without dependency on help system)
>>
>>  - it allows us to reuse existing swiki contents
>>    (if the full syntax is supported we can query existing
>>     swikis!)
>>
>> So it is a nice idea and would be a good addition.
>>
>>
>> I reworked Alains code to better fit the pluggable architecture
>> of the HelpSystem framework (now using a builder):
>>
>> Use an updated 1.2 core image, code is attached
>>
>>   1. File in "Foo.st" (which defines a simple help description)
>>         =>  no dependency on any help system
>>
>>   2. First I added a registration mechanism (pragma<systemHelp>
>>      so one can add own help types to the system help
>>      (the one that appears when you open the default help browser)
>>
>>         =>  load "AddToSystemHelpFix.1.cs"
>>         =>  at least this fix should go into Core 1.2, so
>>            no ugly hacks are necessary to appear in the
>>            default help browser
>>
>>      I added a now fixed issue for core 1.2 on:
>>        http://code.google.com/p/pharo/issues/detail?id=3511
>>
>>   3. I reworked Alains code so it uses a WikiStyleHelpBuilder
>>      (similar to the other builders) and a WikiStyleHelp as
>>      a new help type
>>
>>         =>  see WikiStyleHelp.5.cs
>>         =>  if we agree on this we can integrated it into core too,
>>            currently it is in an own class category/package
>>         =>  "HelpBrowser openOn: WikiStyleHelp"
>>            will show all contents defined using the wiki style syntax,
>>            so only the one defined in class Foo appears
>>         =>  "HelpBrowser open"
>>            will show all help in the system (including the ones
>>            defined in Foo)
>>         =>  since it uses the new registration mechanism (see 2. above)
>>            all these topics will also appear in the help browser
>>            that is accessible from the menu
>>
>> I would vote for adding this to core 1.2 too. It's additional,
>> nothing should break. What do you all think...
>>
>> And thanks Alain for the idea and initial code!!!
>>
>> Have fun
>> T.
>>
>>
>>
>>
>>
>>
>>
>
>

> Ok I suggest to integrate that in 1.2 because this is important.
>
> Now let me open a big can of worms but we truly need it.
> When you write documentation (I did several experiments with Soup) the documentation in class comment is cool because you to not have to have
> " and " and '' ' ' '' '" everytimes you manipulate a string or a comment.
> Now you do not want to have huge class comments I would prefer to have a couple of methods and it does not work: you put back the crappy unnestable "
> ugly boring.... better not putting comments.
>
> So I would really like to have
> */ this is a nice nestable comment
>
> "hkjkhhkjh "
> 'hkjjkh'
> 1 + 2
>
> */yet another comment: increbile this is a nested ones: yes you know
> Smalltalkers are discovering the world/*
>
> /*
>
> As you see stealing the C comment syntax is a plus because everybody knows it.
> I remember a discussion on VW about possible syntax to support that.
> Before replying to this point thing hard because we need that support.
>
> Stef
>
>
> On Jan 8, 2011, at 10:15 AM, Alain Plantec wrote:
>
>> Hi all,
>> very cool, thanks Torsten.
>> Now, I think it's better to wait 1.3 because 1.2
>> is almost ready ...
>> and I would use $! instead of $= as section
>> marker to keep Pier compatibility.
>> Cheers
>> Alain
>> Le 07/01/2011 14:16, Torsten Bergmann a écrit :
>>> Hi,
>>>
>>> Nice idea, I like the "wiki help description" for three reasons:
>>>
>>>   - its pragma based AND allows for definition of structured books
>>>     (so Lukas should be satisfied since he can define content
>>>      without dependency on help system)
>>>
>>>   - it allows us to reuse existing swiki contents
>>>     (if the full syntax is supported we can query existing
>>>      swikis!)
>>>
>>> So it is a nice idea and would be a good addition.
>>>
>>>
>>> I reworked Alains code to better fit the pluggable architecture
>>> of the HelpSystem framework (now using a builder):
>>>
>>> Use an updated 1.2 core image, code is attached
>>>
>>>    1. File in "Foo.st" (which defines a simple help description)
>>>          =>   no dependency on any help system
>>>
>>>    2. First I added a registration mechanism (pragma<systemHelp>
>>>       so one can add own help types to the system help
>>>       (the one that appears when you open the default help browser)
>>>
>>>          =>   load "AddToSystemHelpFix.1.cs"
>>>          =>   at least this fix should go into Core 1.2, so
>>>             no ugly hacks are necessary to appear in the
>>>             default help browser
>>>
>>>       I added a now fixed issue for core 1.2 on:
>>>         http://code.google.com/p/pharo/issues/detail?id=3511
>>>
>>>    3. I reworked Alains code so it uses a WikiStyleHelpBuilder
>>>       (similar to the other builders) and a WikiStyleHelp as
>>>       a new help type
>>>
>>>          =>   see WikiStyleHelp.5.cs
>>>          =>   if we agree on this we can integrated it into core too,
>>>             currently it is in an own class category/package
>>>          =>   "HelpBrowser openOn: WikiStyleHelp"
>>>             will show all contents defined using the wiki style syntax,
>>>             so only the one defined in class Foo appears
>>>          =>   "HelpBrowser open"
>>>             will show all help in the system (including the ones
>>>             defined in Foo)
>>>          =>   since it uses the new registration mechanism (see 2. above)
>>>             all these topics will also appear in the help browser
>>>             that is accessible from the menu
>>>
>>> I would vote for adding this to core 1.2 too. It's additional,
>>> nothing should break. What do you all think...
>>>
>>> And thanks Alain for the idea and initial code!!!
>>>
>>> Have fun
>>> T.
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>
>