Hi -

I'd like to add a feature request to HelpSystem: Adding a very simple 
pattern that can be used to provide structure in class comments, perhaps 
along the lines of Wiki syntax. Why would that be good? Several reasons:

a) Currently a book depends on the presence of HelpSystem (i.e., via 
subclassing). This needs to be fixed - we need to be able to have 
documentation in the system without necessarily requiring a viewer.

b) Typing in '' quotes is pretty insane when you quote text. The 
constant use of it''s instead of it's etc. is VERY distracting. Code 
examples look like crap etc. In the class comment you can write straight 
away.

c) Class comments are WYSIWIG for the purposes of HelpSystem. One can 
create links, doIts, highlights and see the effects right away. This 
isn't easily possible otherwise since we don't have literal text syntax.

d) It's the right place for documentation anyway.

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. In fact what happened was that I was 
trying to use HelpSystem and ended up to move all the docs into the 
class comment for all of the above reasons.


For example, we could just say that we define a help book marker and a 
topic boundary and then your class comment looks like here:

This is a sample class comment.

[HelpBook: 'MyClass Introduction']

Anything you see here will be displayed as the abstract for the help book.

=== MyClass Introduction

This is an introduction to MyClass. You can read about its most 
interesting feature.

=== MyClass Frobnification

Frobnification, the process of frobnifiying a snuzzle, is the main 
purpose of MyClass.

[HelpBook: 'MyClass Reference']

=== frobnify: aSnuzzle

This is the main interface to MyClass. It takes a Snuzzle and frobnifies 
it. Note that there is some discussion about whether the result is a 
fronbnified or a frobnificated snuzzle.

Example:

	MyClass new frobnify: RectangularSnuzzle new.


Etc. The point being that it's easy to edit, you get both a class 
comment and a book out of it, and people looking at it will say "holy 
cow! i guess there *is* some documentation somewhere here :-)"

I'd be happy to help you with this if you think it's worthwhile.

Cheers,
   - Andreas