[squeak-dev] HelpSystem (was Documentation Team)

Tue Apr 20 18:31:04 UTC 2010

Hi,

sorry for changing the topic - but again I saw discussion on 
"in-image" documentation.

Are you all aware of the "HelpSystem" project that I wrote for Pharo and
Squeak and that was already discussed on pharo-dev list. 

It is ready for integration and we can already fill it with 
content packages (docus, lessons as books). It is still ASCII based 
but maybe we can later enhance it using old Scamper code to be based
 on simple markup, ...

If you want to have a look at the "core":

   Installer squeaksource
     project: 'HelpSystem';
     install: 'HelpSystem-Core'.

This "core" has the basic support and the browser. But you can
write your documentation content even without it and later
convert it using a special method. More on this below.

You can open the help browser via "open" -> "HelpBrowser" or by evaluating
"HelpBrowser open". By default it only provides the help for the help 
system itself. 

If you load it with example books like

   Installer squeaksource
     project: 'HelpSystem';
     install: 'HelpSystem-Core';
     install: 'HelpSystem-Tests';
     install: 'Metacello-Help';
     install: 'Pharo-Project-Help';
     install: 'Squeak-Project-Help'.
  HelpBrowser open

from the same repository you will get examples how books can 
look like. 

It also integrates an API Help like system, try one of these:

  HelpBrowser openOn: Integer.
  HelpBrowser openOn: (SystemReference hierarchyFor: Integer).
  HelpBrowser openOn: SystemReference. "Complete reference"

Gives contents without much work ;)

The basic model is simple now (see [1] and class HelpTopic and
HelpBrowser). Read [2] and [3] and the "Help on Help" book in 
the help browser itself to learn about it.

If you want to write own books that show up in the standard
SystemHelp look at subclasses of CustomHelp.

But you can open the help browser on anything that implements
#asHelpTopic. Check for implementors to learn from the code.

So either you create a book in the CustomHelp class hierarchy 
or define your content elsewhere.

You can easily convert any source into a help topic, which I
demoed with the IRC channel logs. 
Evaluate my code example in [4] to get a help browser on last 
weeks activity on squeak IRC channel.