Torsten I would like to give a try to document Soup with pragma and builder. So I will start to write some documentation and after we will need to stabilize and interface for the builder. But I imagine that we need to be able to - create a topic - create a subtopic something like that.
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... [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/cc... [5] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/036952.ht... [6] http://pastebin.com/Y7MFaddK [7] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/037507.ht... [8] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/037485.ht... [9] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/037499.ht... [10] http://www.ibm.com/developerworks/java/library/j-ap01117/checkstyle-eclipse....
-- Neu: GMX De-Mail - Einfach wie E-Mail, sicher wie ein Brief! Jetzt De-Mail-Adresse reservieren: http://portal.gmx.net/de/go/demail