Thanks Torsten for this detailed view. I think nothing stop for having the CustomHelp approach (for writing overviews) AND the pragmas approach (to extract documentation from code / tests). Indeed a complete help on a package will surely mix the two. Actually for the Help I write I have some Help books + PackageAPIHelpBuilder.
Another example is ProfStef: with last ConfigurationOfProfStef, all tutorials are automatically available in HelpSystem, thanks to HelpBuilder. You will also find in http://www.squeaksource.com/LaurentLSandbox.html the package API-Help wich build the help of all classes in Pharo (warning: slow, but has been helpful for me several times :) PS:I added the cool IRC example here: http://www.pharocasts.com/2010/09/document-with-helpsystem.html Laurent On Mon, Dec 13, 2010 at 2:34 AM, Torsten Bergmann <asta...@gmx.de> 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 > >
