[squeak-dev] Re: HelpSystem & Class comments

Danny Chan chan_dhf at yahoo.de
Wed Feb 24 20:41:27 UTC 2010

> > With HelpSystem-Core-tbn.16 I even allow to provide own builders.
> That's useful, but I'd still need a way of denoting to HelpSystem, "hey,
> here, over here, (*hand waiving*) me, yes, me, I'm a HelpBook!" :-)

Load HelpSystem-Core-DannyChan.17 and the attached file. Then do

HelpSystem builder: MyBuilder.
HelpSystem reset.
HelpBrowser open.

You will see a class help on Object. Now you can customize MyBuilder to return 
every collection of books you want. If you want to create the list by some 
special tag, then you can override rootTopics to do what you want. I guess all 
of this can be still streamlined, but it already possible to customize the 
lookup process to your liking.

> >> I'm not saying that comments are the only way by which HelpBooks should
> >> be created but I think that this should be one of the ways that
> >> HelpSystem directly supports.
> >
> > That's already there - Danny already added this for the help classes.
> > Just open the book "Help on Help" -> "HelpSystem API Documentation"
> > and subnodes after loading the latest baseline.
> > If you click on a class node you will see the class comment displayed
> > in the help (currently as ASCII).
> Right I've seen that. This is pretty good already, the only thing I'm
> asking for is just a tiny bit of additional structure in a class comment
> so that one can have sections etc.

I want to do this, but I don't have much time currently. Its probably quite 
simple, have a look at ClassAPIHelp and customize the two class side methods. 

> > However: the main question to me is the kind of format we should
> >          use:
> >
> >   a) Wiki Style or similar
> >   b) real markup like HTML
> >   c) specific format like Squeaks Text representation with textDoits, ...

> I'd say: All of them! :-) This is a matter of builders, no? I don't
> think there's a need to decide upfront that only one format will be
> supported. We could start with simple Wiki syntax which can be used in
> class comments and other simple places. If people feel unsatisfied or
> need more or want to use HelpSystem for other purposes, extend it as
> desired.

That's why I added a class for the content of a page. Right now it takes a 
string, but why not have classes for showing screencasts from URLs, HTML, 
whatever. The page itself should decide how it should be presented. Actually 
right now I don't know why we need builders, a page has the content, it knows 
how it wants its content to be presented to be most helpful to users, and it 
probably also knows where to get other content dynamically if it needs to 
(like API documentation, which should be always up to date).

-------------- next part --------------
'From Pharo-1.0-10508-rc2 of 19 October 2009 [Latest update: #10508] on 24 February 2010 at 9:22:32 pm'!
Object subclass: #MyBuilder
	instanceVariableNames: ''
	classVariableNames: ''
	poolDictionaries: ''
	category: 'SandBox'!

"-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- "!

MyBuilder class
	instanceVariableNames: ''!

!MyBuilder class methodsFor: 'as yet unclassified' stamp: 'DannyChan 2/24/2010 21:21'!
! !

!MyBuilder class methodsFor: 'as yet unclassified' stamp: 'DannyChan 2/24/2010 21:21'!
	^{ClassAPIHelp on: Object}! !

More information about the Squeak-dev mailing list