Torsten Bergmann wrote:
> Andreas Raab wrote:
>> a) Currently a book depends on the presence of HelpSystem (i.e., via 
>> subclassing). 
> 
> No, you are not forced to be in the "CustomHelp" hierarchy.
> You can define an own hierarchy, directly as subclass of Object, whatever

What I'm looking for is a mechanism by which the documentation can 
remain in the image even when HelpSystem is absent. So when HelpSystem 
is loaded it needs to discover available books. Is there some tag/marker 
mechanism by which one can flag those pre-existing books?

> The standard builder ("HelpBuilder") is able to use a different root. 
> See HelpBuilder class>>buildFromRoot: and HelpBuilder>>defaultRoot.
> 
> 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!" :-)

> b) Typing in '' quotes is pretty insane when you quote text.
> 
>   I know, but this is annoying since you currently write it manually 
>   using the browser and by adding methods yourself. Storing the
>   contents in method is just the vehicle - additional authoring 
>   capabilities would help here in the future (an additional HelpEditor
>   beside the HelpViewer). Again you judged too early. 

It's simply extremely annoying. That's why I was saying, why not derive 
help books from class comments? That's is a place for documentation 
already, it has all those properties. And for many types of 
documentation this is just the right place.

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

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

Cheers,
   - Andreas