Help System

Hi Lukas,

"it is a design flaw"
"Being forced to have strong references ... "
"makes it impossible to just include some documentation"
"This doesn't encourage me at all"
"..."

So many negative statements in one post, look like you had
a bad day today ;)

My comments below:

   a) If you want to provide API help (reference docu)
      you DONT HAVE ANY reference or dependency since you can comment your
      classes and methods in the usual Smalltalk way using class/method
      comments.
      No need for "HelpSystem-Core" to be around, NO REFERENCES,
      and NO EXCUSE NOT TO document your code ;)
 
   b) If you want to provide similar tutorials help (books/system help)
      that should appear in the "SystemHelp" then the answer
      is YES, HERE WE HAVE A DEPENDENCY since you subclass
      "CustomHelp" and reference "HelpTopic". But this is
      intended since after a few experiments with other solutions
      this was a very natural way to define the book contents.

      Would you call it a design flaw of SUnit to create tests
      by subclassing the class "TestCase" so that it is known to
      the system as test case and also shows up in the TestRunner?
      Does the dependency on SUnit make it impossible for you
      to write tests? Or does it even encourage you not to write
      tests? So please revise your statements.  

      And yes, in the scenario I'm up to you typically provide a
      separate help package that can be separately loaded/unloaded.

      It depends on your deployment scenario if you want to
      keep it in the image or not. So a separate package makes sense
      for these tutorials. Either you ship with tests and docu or
      just with the code.

      If you deploy and ship an end user app for instance you
      would just need "SQLite-Core" and may unload "SQLite-Tests"
      and "SQLite-Help".

      If someone works with code (for instance SQLite) he can

       - either use the known API help (either in the Class browser
         or the HelpBrowser, see a)

       - or load the additional package with mostyl more generalized
         tutorials/manuals/books, its up to you to provide such an
         additional help package ("SQLite-Help" for instance)


However - these two scenarios are provided by DEFAULT. You have
a different scenario since where (if I understand you correctly) you
want:

   c) Provide documentation that
        - is not defined in usual class/method comments
        - should be packaged with your code package instead of
          a separate one
        - should not be dependent on any class in the
          HelpSystem-Core package
        - may already be defined

Here I would suggest you to find an appropriate way to write and
store your documentation (for instance in methods with pragmas)
the way you want AND INDEPENDENT from the current help system.

If you want to have it shown later in the help system/help browser
too you need to provide at least an (extension) method #asHelpTopic
or use an own builder (see HelpBuilder and subclasses) to convert
your documentation style to the generalized help topic hierarchy
the browser is able to display.

When you talk about an extensibility of the help system similar
to preferences/menu building then you mainly talk about a
pragma solution here:

I already experimented with this in the early help system (see  
HelpSystem-Core-tbn.4) for instance and later switched
to the subclassesing solution (similar to SUnit) mainly for the
following reasons:

  1. it is more intentional to directly map the book structure to the
     class hierarchy

  2. You can use the usual ST tools to manage or refactor your books
     (the class hierarchy browse even shows you the topic hierarchy)

  3. It is hard to describe a complete book structure (with page
     order, nested books and the like) in pragmas
     If you have a good solution then I'm all ears here.

  4. By using pragmas (loose coupling) you have to deal
     with the problem that by your parent topic may not be
     there/not be loaded since it can be defined somewhere else
     in the class hierarchy.  
     By mapping to the class hierarchy you cant run into the problem
     since you need the superclass (parent topic definition) for the
     subclass (subtopic definition) to be loaded.

So I was pragmatic and used Plain old Smalltalk classes and method
to define the books (POSCAM).

But Help System does not limit you, currently we have a) and b)
to define and bring help into the help system/help browser.
If you have a good solution for defining complete books with structure
using pragmas then we can include it...

Meanwhile Lukas wrote:
>Yes, I imagine something along ...
>
>PPParser class>>helpOn: aBuilder
> <help>
>

Attached is a simple (rough)example that it is easy to extend the help
system the way you may want (with a builder similar to system settings
and your above example)

Just load it into an up to date core 1.1. image and evaluate:

  HelpBrowser openOn: PragmaHelp

Look at class Foo and Bar to see that there is no dependency
and PragmaHelp/PragmaHelpBuilder to see how it is done.

HelpSystem is flexible, you can also have external help sources
as I've shown with the IRC example.
It just depends on how you want to describe and structure your
documentation...

Bye
Torsten
     
P.S: I'm still in favour of well structured books in separate
     packages than mixed code/docu in one package since you
     may wish to unload docu for deployment/runtime scenarios.    
     




--
GRATIS für alle GMX-Mitglieder: Die maxdome Movie-FLAT!
Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01

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

On May 5, 2010, at 3:24 PM, Torsten Bergmann wrote:

PhD stress :)
>>
>
....

> Attached is a simple (rough)example that it is easy to extend the help
> system the way you may want (with a builder similar to system settings
> and your above example)

Good this is what I want. I want to leverage the tests we have.
Since we can remove tests anyway.



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

> "it is a design flaw"
> "Being forced to have strong references ... "
> "makes it impossible to just include some documentation"
> "This doesn't encourage me at all"
> "..."
>
> So many negative statements in one post, look like you had
> a bad day today ;)

Not really, I was just trying to load a package with help into an
image without the HelpSystem loaded. *boom*

I thought I could give some feedback before it got adapted more
widely. We had exactly the same discussion with the menu and settings
system a few months back.

>   a) If you want to provide API help (reference docu)
>      you DONT HAVE ANY reference or dependency since you can comment your
>      classes and methods in the usual Smalltalk way using class/method
>      comments.
>      No need for "HelpSystem-Core" to be around, NO REFERENCES,
>      and NO EXCUSE NOT TO document your code ;)

Status quo, yes. I see documentation more exposed through the
HelpSystem browser though, which i found a really nice way to browse
documentation.

>      Would you call it a design flaw of SUnit to create tests
>      by subclassing the class "TestCase" so that it is known to
>      the system as test case and also shows up in the TestRunner?

Yes, absolutely. Any other unit testing framework in the world does
not force you to subclass from a common superclass when writing tests.

>  4. By using pragmas (loose coupling) you have to deal
>     with the problem that by your parent topic may not be
>     there/not be loaded since it can be defined somewhere else
>     in the class hierarchy.

I would not make the books extensible themselves, that complicates
things and is rarely needed in practice. The exact same problem is
solved in the settings system quite nicely.

> So I was pragmatic and used Plain old Smalltalk classes and method
> to define the books (POSCAM).

It doesn't have to be pragmas (although I think it should). It could
also just be a class side method #buildHelpOn: that is called when
opening the browser and that gives each class the possibility to add
some documentation.

I am just saying that I am not going to create an extra package just
for the sake of documentation. Documentation is really crucial and it
needs to be super easy to create, otherwise it is simply not going to
happen. Creating an extra package is complicated and doesn't give me
any benefit as a developer, so very likely I am not going to do it.

Lukas

--
Lukas Renggli
www.lukas-renggli.ch

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

Le 05/05/2010 15:24, Torsten Bergmann a écrit :
> P.S: I'm still in favour of well structured books in separate
>       packages than mixed code/docu in one package since you
>       may wish to unload docu for deployment/runtime scenarios.
>    
Hi Torsten, all
Yes, we had exactly the same discussion (one year ago? I can't believe
it) about
the settings package. An advantage of the builder approach is that
one can simply choose:
It is possible to let documentation methods (#helpOn: aBuilder ...) and code
mixed in a single package without introducing any dependency
or choose to have two packages, one for the documentation and the
second for the code.
Cheers
Alain


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

Yes I remember it :)
Kind of pattern :)
Stef

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

I agree with Lukas, although I have already expressed these sentiments
in previous threads when I raised my own design concern.  For me the
point is that the standard old class comment / method comments is not
expressive enough to be integrated into such a help system. There is a
desire to annotate help above what can be done with the old method (a)
via a richer API but use a system that does not depend on the subclass
approach (b). Now for Pharo it does not really matter because we put
the base classes in, but as Lukas says it does not load in other
images that require this code. and my feeling is that the subclass
approach still puts the documentation too far from the code that you
are documenting.  This is what I found a pain trying to integrate some
help in the network package. i just ended up not doing it. I don't
want to have to put it in another package.  Anyway i am not going to
go over old ground. i just wanted to say +1.

cheers,
Mike

On Wed, May 5, 2010 at 7:19 PM, Stéphane Ducasse
<[hidden email]> wrote:
_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project