About using pragma for help like in setting

> Hi,
>
> OK, just read the IRC meeting notes and the last posts/threads on the help discussions.
> Unfortunately the discussion is scattered and I try to catch up/summarize here
> even for people who are new to the topic. Excuse the length of this post in advance.
> If the pragma help is interesting to you only then jump to section "D":
>
>
> A. Pharo once lacked a "help system", so I wrote one. It was and still is more oriented
>    towards "end user help" or "browsable manuals" with written text content in form of
>    nestable books. I had no need for the next JavaDoc in Smalltalk with just an API reference
>    - I wanted real help text which gives a big picture overview to people on various topics.
>
>    The design of HelpSystem is simple and should be easy to understand, we have a
>    HelpBrowser that displays (nestable) HelpTopics. To display something you have to
>    convert it into such a help topic instance.
>
>    Click on "Help" -> "HelpBrowser" in your Pharo image and have a look at the book
>    "Help on Help" to get more details or try a few examples.  
>
>
> B. I think you all agree that a "help system" without content is not very useful.
>    Different people have different ideas and what could be used as "help contents"
>    should be up to you.
>
>    The HelpSystem itself is not and should not be bound to where and how (format, etc.)
>    the content is stored. You can convert from any source and format into nested HelpTopics.
>
>    To demonstrate this I once provided an example [1] to query and display the IRC archive.
>    You will also find this example with IRC as one possible external source in the "Help on help"
>    book.
>
>    So the content could be defined in any format you like and the contents source could be
>    internal or external to the image. You should declare the help contents the way you like.
>
> C. When you want to provide help to a user you may find it nice to include and manage
>    the contents directly within the image. Nice - since you can deploy it with your app or
>    unload if it is not needed.
>
>    There are many solutions here - on squeak-dev it was discussed to use a specific class
>    comment format or store the contents in methods returning an XML string, etc.
>    I expected this discussion since I thought long enough about formats, storage and I
>    didnt want to limit anyone.
>
>    Therefore HelpSystem is open to any of these solutions - one can implement a custom
>    help builder (see class HelpBuilder) that does the necessary conversion into help topic
>    instances.
>
>    One of the many possible solution is to use "pragma annotated" classes that hold the
>    contents. Looks like this is getting more attention now again since pragmas are used
>    in various places now (like the settings framework).
>
>    And yes, I followed the pragma path already. But after initial experiments with pragmas
>    I found it much more convenient to map a tutorial/the help book structure directly to
>    the class hierarchy.
>
>    This "class to book" mapping is more natural, one can use the usual class browsers and
>    tools to manage the contents (including references, implementors, senders, ...)
>    and you can easily have extensible books/tutorials (which is complicated with pragmas)  
>
>    If you want to follow this "class to book" approach then HelpSystem provides a class
>    called "CustomHelp" that you can subclass and that has all the necessary support
>    (even for editing and saving by using a workspace) - so you can easily implement your
>    help books. Some projects use this already and there is even a Pharocast on how to
>    to this.
>
>    Through the class CustomHelp in the HelpSystem we have a commonality with SUnit -
>    where you have TestCase as a superclass and implement hook methods.
>
>    This class "CustomHelp" is the one "under fire" that leads to scathing criticism from
>    Lukas.
>
>    Maybe it is exactly this commonality with SUnit that makes some of you think HelpSystem
>    forces you to subclass "CustomHelp" or forces you to have a dependency on the help system
>    if you want to declare your help content.
>
>      => But yet again: nobody has to use the provided "class to book" mapping or subclass
>                        "CustomHelp" if you want to define your help contents!
>
>    Maybe I should not ship HelpSystem with this support class "CustomHelp" as the (currently sole)
>    default but I wanted to at least provide a way to get you started. Still it is an utility class
>    and also categorized as such.
>
>    I for myself have no problem with this additional class since when subclassed I know that
>    I have a dependency on it's package and I treat the help packages similar to test
>    in SUnit (only loaded when HelpSystem is there, etc.)
>
>    However the "CustomHelp" approach has pros and cons and you have to decide if it is the
>    right for you:
>
>     Maybe you like:     - easy mapping of classes to books
>                         - easy browsing/managing in standard code tools
>                         - familarity with SUnit (common superclass)
>                         - no "copy/paste" methods as in Metacellos ConfigurationOfXXX
>
>     Maybe you dislike:  - the dependency on the superclass CustomHelp and
>                         - therefore the dependency on the help package
>
>    Typical use case is that you display the help contents in the browser anyway and
>    therefore this dependency may not hurt you.
>
>    Looks like Lukas has a use-case where he requires his help contents only - but
>    not the help system itself. Similar to a loaded test without any SUnit support in the image...    
>
> D. As I already said I designed HelpSystem to stay independent from the way the contents is
>    defined. So I'm definitely open to a pragma based solution too. In the long term I would like to see
>    support for different "content definition styles" anyway.
>
>    Lukas can store his blog posts/help texts the way he likes and without any dependency on HelpSystem.
>
>    After the discussion in May we all agreed [2] that it is a good direction  to check out the
>    pragma/builder approach too and see how far we can go here. I provided an example how one
>    can easily add this "pragma approach" to to the HelpSystem ([3] and [4] for the code) but I left
>    out the builder part since I dont know what Lukas expects here.
>
>    So no real feedback/adoption so far ... at least it would help if I get an example
>    on how the contents should be defined in an annotated #buildHelpOn: method.
>
>    However, the pragma approach has pros and cons:
>
>      Maybe you like:   - no dependency on a common superclass or package dependency on a class in HelpSystem
>                        - may therefore seem "cleaner" depending on POV
>
>      Maybe you dislike:  - even with pragmas one has an implicit dependency on the builders interface
>                            which also has to be stable very early
>                          - by using pragmas (loose coupling) you have to deal with the problem that
>                            your parent topic may not be there/not be loaded since it can be defined
>                            somewhere else in the class hierarchy.
>
> E. After the initial release people asked on how to integrate typical "Smalltalk documentation"
>    to include browsable reference documentation (API doc) like class and method comments in the
>    HelpSystem too. This was easy to add since again I just had to write a custom help builder that does the
>    necessary conversion.
>
>    If you load the "Pharo-Project-Help" you can browse the complete reference on anything that
>    is already documented:
>
>
>      Gofer new
>           squeaksource: 'HelpSystem';
>           package: 'Pharo-Project-Help';
>           load.
>      HelpBrowser open.
>
>    In the help browser click on "Pharo" and "API Reference". This is more "reference documentation" and
>    only a "poor" way to easily fill up the help system ;)  
>
>    I would like to see people writing more tutorials/manuals about parts of the system so one could get the big
>    picture, but the idea of Stef [5] to get fully documented classes and methods is also nice. For the
>    reference docu:
>
>
>      Maybe you like:     - no dependency on anything, just comment your classes and methods
>                            as you may know from any other smalltalk system
>
>      Maybe you dislike:  - you dont need the help system, you can look at it in the standard browser
>                          - its only a basic API documentation system (compared to JavaDoc and others)
>
> -----------------------------------------------------------------------------------------------------------------
> And now some comments on IRC/posts I've seen:
>
> Lukas on IRC see [6]:
>> [3:14pm] renggli: HelpSystem is not useable for me and obviously not for anybody else (otherwise
>> it wouldn't be empty)
>
> Lukas, nobody forces you to follow the "define help contents via class to book mapping" approach.
> If you want a "define help content via pragmas" approach then help moving this issue forward or define
> your help contents the way you like and implement a custom help builder.
>
> For the other point: HelpSystem is not empty - look at an updated core 1.2 and it is already
> used in many external packages as Laurent already pointed out. [7]
>
>
> Lukas wrote on [8]:
>>> Couldn't you just add another loop to your script to "unload all help" just
>>> like unload all tests
>> Sure, but that means I have to package help text separately. This is
>> the contrary to what Java, Ruby, Python, Javascript, ... are doing;
>> keeping code and documention as close together as possible.
>
> No - you dont have to package documentation seperately. A class/method comment is still a
> class/method comment and its packaged with the code. There is no dependency on HelpSystem
> here - although the HelpBrowser can display it too.
>
> You still keep code and documentation close as in any other language.
>
> But if you write a "big picture" help manual or tutorial on how things interact it would
> be good to package it seperately. Either using CustomHelp, pragmas, or ...
>
>
> Lukas wrote on [8]:
>> I think, the fact that there is no single external package with help
>> system documentation proves this, no?
>
> There are quite a few. Maybe you should look more often on Squeaksource. Again I point to [7]    
>
>
> Stef wrote on [9]
>> Now I was thinking that torsten would reply to this mail but in 1.3 will take a decision because I want a really better help
>> and documentation inside the right class and package.
>
> I still think that we should in minimum have the "code" - "tests" - "help" package triade, where the code package
> includes the class and method documentation as any Smalltalker is used to. The test package should include unit tests
> covering the code. And the help package should give a high level overview on how to use the code or tests.
>
> If the dependency from "help" packages to "help system" due to the class CustomHelp is a problem then
> we can easily convert them once we have a good "pragma based" approach in place.
>
> Removing packages or classes that are not documented is too hard ... but we should use Lint rules to check the
> "completeness/basic quality" of package.
>
> Similar to checkstyle for Java in Eclipse - if there are problems in a package then you have a different icon for
> the package and you work until it's clean because it hurts your eyes (see [10] for a screenshot)
>
>
> Hope I could at least bring some light into the whole discussion and I would really like
> the see if also the pragma approach would move forward.
>
> Bye
> Torsten
>
>
> [1] http://forum.world.st/Preview-Help-System-with-new-model-now-also-for-Squeak-td1695386.html   
> [2] http://forum.world.st/Help-System-td2131748.html
> [3] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-May/026148.html
> [4] http://lists.gforge.inria.fr/pipermail/pharo-project/attachments/20100505/cc589ac2/attachment-0001.obj
> [5] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/036952.html
> [6] http://pastebin.com/Y7MFaddK
> [7] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/037507.html
> [8] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/037485.html
> [9] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/037499.html
> [10] http://www.ibm.com/developerworks/java/library/j-ap01117/checkstyle-eclipse.jpg
>
>
>
> --
> Neu: GMX De-Mail - Einfach wie E-Mail, sicher wie ein Brief!  
> Jetzt De-Mail-Adresse reservieren: http://portal.gmx.net/de/go/demail
>

>    After the discussion in May we all agreed [2] that it is a good direction  to check out the
>    pragma/builder approach too and see how far we can go here. I provided an example how one
>    can easily add this "pragma approach" to to the HelpSystem ([3] and [4] for the code) but I left
>    out the builder part since I dont know what Lukas expects here.
>
>    So no real feedback/adoption so far ... at least it would help if I get an example
>    on how the contents should be defined in an annotated #buildHelpOn: method.
>
>    However, the pragma approach has pros and cons:
>
>      Maybe you like:   - no dependency on a common superclass or package dependency on a class in HelpSystem
>                        - may therefore seem "cleaner" depending on POV
>
>      Maybe you dislike:  - even with pragmas one has an implicit dependency on the builders interface
>                            which also has to be stable very early
>                          - by using pragmas (loose coupling) you have to deal with the problem that
>                            your parent topic may not be there/not be loaded since it can be defined
>                            somewhere else in the class hierarchy.
>
> E. After the initial release people asked on how to integrate typical "Smalltalk documentation"
>    to include browsable reference documentation (API doc) like class and method comments in the
>    HelpSystem too. This was easy to add since again I just had to write a custom help builder that does the
>    necessary conversion.
>
>    If you load the "Pharo-Project-Help" you can browse the complete reference on anything that
>    is already documented:
>
>
>      Gofer new
>           squeaksource: 'HelpSystem';
>           package: 'Pharo-Project-Help';
>           load.
>      HelpBrowser open.
>
>    In the help browser click on "Pharo" and "API Reference". This is more "reference documentation" and
>    only a "poor" way to easily fill up the help system ;)  
>
>    I would like to see people writing more tutorials/manuals about parts of the system so one could get the big
>    picture, but the idea of Stef [5] to get fully documented classes and methods is also nice. For the
>    reference docu:
>
>
>      Maybe you like:     - no dependency on anything, just comment your classes and methods
>                            as you may know from any other smalltalk system
>
>      Maybe you dislike:  - you dont need the help system, you can look at it in the standard browser
>                          - its only a basic API documentation system (compared to JavaDoc and others)
>
> -----------------------------------------------------------------------------------------------------------------
> And now some comments on IRC/posts I've seen:
>
> Lukas on IRC see [6]:
>> [3:14pm] renggli: HelpSystem is not useable for me and obviously not for anybody else (otherwise
>> it wouldn't be empty)
>
> Lukas, nobody forces you to follow the "define help contents via class to book mapping" approach.
> If you want a "define help content via pragmas" approach then help moving this issue forward or define
> your help contents the way you like and implement a custom help builder.
>
> For the other point: HelpSystem is not empty - look at an updated core 1.2 and it is already
> used in many external packages as Laurent already pointed out. [7]
>
>
> Lukas wrote on [8]:
>>> Couldn't you just add another loop to your script to "unload all help" just
>>> like unload all tests
>> Sure, but that means I have to package help text separately. This is
>> the contrary to what Java, Ruby, Python, Javascript, ... are doing;
>> keeping code and documention as close together as possible.
>
> No - you dont have to package documentation seperately. A class/method comment is still a
> class/method comment and its packaged with the code. There is no dependency on HelpSystem
> here - although the HelpBrowser can display it too.
>
> You still keep code and documentation close as in any other language.
>
> But if you write a "big picture" help manual or tutorial on how things interact it would
> be good to package it seperately. Either using CustomHelp, pragmas, or ...
>
>
> Lukas wrote on [8]:
>> I think, the fact that there is no single external package with help
>> system documentation proves this, no?
>
> There are quite a few. Maybe you should look more often on Squeaksource. Again I point to [7]    
>
>
> Stef wrote on [9]
>> Now I was thinking that torsten would reply to this mail but in 1.3 will take a decision because I want a really better help
>> and documentation inside the right class and package.
>
> I still think that we should in minimum have the "code" - "tests" - "help" package triade, where the code package
> includes the class and method documentation as any Smalltalker is used to. The test package should include unit tests
> covering the code. And the help package should give a high level overview on how to use the code or tests.
>
> If the dependency from "help" packages to "help system" due to the class CustomHelp is a problem then
> we can easily convert them once we have a good "pragma based" approach in place.
>
> Removing packages or classes that are not documented is too hard ... but we should use Lint rules to check the
> "completeness/basic quality" of package.
>
> Similar to checkstyle for Java in Eclipse - if there are problems in a package then you have a different icon for
> the package and you work until it's clean because it hurts your eyes (see [10] for a screenshot)
>
>
> Hope I could at least bring some light into the whole discussion and I would really like
> the see if also the pragma approach would move forward.
>
> Bye
> Torsten
>
>
> [1] http://forum.world.st/Preview-Help-System-with-new-model-now-also-for-Squeak-td1695386.html   
> [2] http://forum.world.st/Help-System-td2131748.html
> [3] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-May/026148.html
> [4] http://lists.gforge.inria.fr/pipermail/pharo-project/attachments/20100505/cc589ac2/attachment-0001.obj
> [5] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/036952.html
> [6] http://pastebin.com/Y7MFaddK
> [7] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/037507.html
> [8] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/037485.html
> [9] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/037499.html
> [10] http://www.ibm.com/developerworks/java/library/j-ap01117/checkstyle-eclipse.jpg
>
>
>
> --
> Neu: GMX De-Mail - Einfach wie E-Mail, sicher wie ein Brief!  
> Jetzt De-Mail-Adresse reservieren: http://portal.gmx.net/de/go/demail
>