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-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
>
