I will try to digest that long mail.
Now what I want is that people can type
thisMethodForZork: aBuilder
<help>
aBuilder title: 'About Zork'
text: 'here is the help for the Zork'
"adapted to the API of Help"
or
thisMethodForZork
<help> or <help:1> or <help: 'About Zork' :1>
^ 'here is the help for the Zork'
and that if the help is loaded we can see it in help.
Stef
On Dec 13, 2010, at 2:34 AM, Torsten Bergmann wrote:
> 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
>
