[squeak-dev] Re: [Pharo-project] HelpSystem (was Documentation Team)

Stéphane Ducasse stephane.ducasse at inria.fr
Wed Apr 21 20:39:55 UTC 2010

Torsten may be you should trun your explanation mail into a book section on book.pharo-project.org because it was cool. 
> http://lists.gforge.inria.fr/pipermail/pharo-project/2010-April/024857.html
I think that HelpSystem will be an important piece of Pharo.
And I was planning to push it into 1.1 dev :) ASCII is ok for us. Let us be incremental.
I like the 
	HelpBrowser openOn: SystemReference

I think that this is the way to push people to write cool comment.
Check the one of URI in 1.1 :)

Now how can we turn pragma tagged method comments and Unit tests into 
entries in your HelpSystem.

HelpBuilder of course :)
	Now could we agree on a nice pragma for tagging methods
	and another one sunit tests that should be promoted into the SystemReference

I believe that we do not have the resources to write separate
documentation as VW does. So at least I would have love to have HelpSystem minus minus
where we could get book automatically created from the actual contents of the system.
Tagging is way more reachable than writing specific documentation.

Then I would love to see package level comments... this was this idea behind DrDoc and this is why I should kick my $%^&finger to finish RPackage


On Apr 21, 2010, at 7:56 PM, Torsten Bergmann wrote:

> To clearify a few things from my side on the discussion
> on squeak-dev:
>  1. HelpSystem is working, if ASCII is OK for now we can use
>     it Pharo/Squeak - otherwise I would see it as an early preview.
>     I have clear goals how it should look like in the
>     next iterations. For this more patience is necessary.
>  2. HelpSystem is independent from where and how the actual
>     information is stored (I think I demonstrated this with
>     the IRC example, the books and the API help).
>  3. I hope to keep HelpSystem in sync for major Squeak distributions
>     (Squeak, Pharo, Cuis, ...)
>     The last additions from Hannes already broke the code
>     in Pharo. Seems to be a Pharo issue this time
>     http://code.google.com/p/pharo/issues/detail?id=2342
>     But please dont commit when it is only working in 
>     Squeak since my development environment is Pharo.
>  4. Yes, the content is currently ASCII but the design is prepared
>     to add other types in future releases. 
>     A HelpTopic defines an ivar "contents" - currently referring
>     to a string. I may add another ivar "contentType" 
>     in the future to handle/distinguish additionaly types 
>     (HTML, SqueaksRichText, Morphs/BookMorph, ...)
>  5. HelpSystem should not be limited to Squeak. It should also
>     serve the case that when you write and deploy a commercial
>     app in Squeak you may use it to provide help to your
>     end user/customer
>  6. There are two types of help I see: 
>       A. SystemHelp:      Help books/Tutorials/Manuals
>       B. SystemReference: API Help, class comments
>     HelpSystem is supporting both.
>     I already wrote about the differences and details in 
>     http://lists.gforge.inria.fr/pipermail/pharo-project/2010-April/024857.html
>  7. I would really like to see support for HTML viewing 
>     in the image (HTMLViewMorph or so) - maybe based on Scamper
>     to get a better viewer (headings, tables, ...) than the
>     current plain text.
>     If people want to contribute they should start right with this
>     task. 
>     I know that Laurent already made Scamper loadable in Pharo,
>     dont know about the state in Squeak. 
>     There is also another HTML browser with markup and CSS now available 
>     open source as MIT (WithStyle), I already mentioned this.
>     http://www.cincomsmalltalk.com/userblogs/rowanb/blogView?showComments=true&printTitle=Im_back..._but_SWS_isnt&entry=3364012145
>  8. I know that we now have discussions on which syntax (Wiki,...)
>     to use for describing the contents. 
>     My answer is: it is important but I dont care (yet) since 
>     this discussion is useless until we have an HTML viewer (see 7.) 
>     and  even when there are different syntax styles you can provides
>     builders to transform them into HTML or other contentTypes
>     afterwards.
>     See the class HelpBuilder and subclasses. 
>  9. If you want to write a book for SystemHelp (see 6.A) then
>     the help system provides a class "CustomHelp" similar
>     to TestCase in SUnit. This class is used to directly 
>     map book structures to the class hierarchy.
>     The intention was to be able to create, store and manage
>     these books directly with the usual Smalltalk tools.
>     You can even restructure your book with the RefactoringBrowser.
> 10. If you want to write API help you (see 6.B) can contribute
>     right now by commenting all the undocumented classes in the
>     standard image.
>     HelpSystem just queries these informations from the usual
>     sources (class comments, ...). I would not change this
>     or make it too complicated since this is what people are 
>     used too. 
>     I dont see more documented classes by introducing a 
>     special syntax (wiki or whatever) people have to learn/know about
>     - so lets clean up documenting the classes first.
> 11. HelpSystem is able to get contents from external sources
>     (see the IRC example) - but I would prefer that authoring/viewing
>     could be done right from within the image. 
>     Even when the result is stored external afterwards. 
>     Look at my example books: I can view and change them
>     right from the image and make them available to other images 
>     using Metacello/Squeaksource. 
>     Accessibility of docu (viewing and authoring) is the key to keep 
>     the system and docu in sync and up to date. 
>     External authoring mostly results in unmaintained docu (see
>     the Squeak Swiki).
> 12. I thought again if it is ready to integrate into Pharo and
>     Squeak. From all the discussions I would say it is too early.
> 13. If one wants the docu on the web the answer is easy: we
>     can generate static files or serve them with Seaside. 
>     But I have no need for that right now, especially since
>     this is already available in various forms.
> We can do many things (similar to Python, JavaDoc, you name it)     
> But - let's do it step by step. As I said:
> - Someone working on a good HTML Viewer that I can integrate
>   would really help moving this forward
>   (based on Scamper or by porting WithStyle)
> - Updating class comments would also help a lot 
> Bye
> Torsten
> -- 
> GRATIS für alle GMX-Mitglieder: Die maxdome Movie-FLAT!
> Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01
> _______________________________________________
> Pharo-project mailing list
> Pharo-project at lists.gforge.inria.fr
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

More information about the Squeak-dev mailing list