Hi,
sorry for the delay on the help system - but time is
rare these days.
I know some of you are impatient - therefore I've commited my
restructured code for the help system for you to look what
is coming - even when it is not fully finished. But the restructured
new model is now in place - I have to add more tests and
adapt the "help on the help system" to document my ideas.
I also want to work on compatibility with Squeak as the
first version had. Currently the new stuff only work
in Pharo.
What is new
===========
While we had 3 model classes in my initial version (and after
Dannys additions even more classes) I now reduced the model
to a very, very simple approach with just one model class.
We now have a HelpBrowser that is "just" displaying topics.
A topic (see class HelpTopic) is
- providing a title and optionally an icon
- able to have subtopics,
- provides contents (that is displayed be the browser),
- can be identified by a unique key (so we can later open the
help browser on a specific topic from within other tools)
You can create help topics from each and anything.
To try it out just load the baseline (in Pharo 1.0 or 1.1):
--------------------------------------------
Gofer new
squeaksource: 'MetacelloRepository';
package: 'ConfigurationOfHelpSystem';
load.
((Smalltalk at: #ConfigurationOfHelpSystem) project version: '1.0-baseline')
load
--------------------------------------------
You can open the help browser from the world tool menu or via
code:
HelpBrowser open
You can open the help browser on any object that is able to
be converted into a help topic (via method #asHelpTopic).
So you can write for instance:
HelpBrowser openOn: Integer
opening a short API help/system reference on the Integer class.
The above expression is the short form for:
HelpBrowser openOn: (SystemReference forClass: Integer)
If you want you can include the subclasses:
HelpBrowser openOn: (SystemReference hierarchyFor: Integer)
or even methods
HelpBrowser openOn: (SystemReference hierarchyWithMethodsFor: Integer)
You can browse the whole system reference documentation using:
HelpBrowser openOn: SystemReference
But these are only a few examples what we can extract from the
system.
However - the major goal is NOT an API browser, the idea is to
provide a simple architecture to provide browsable help contents
depending on the context. For instance it should also be possible
to use the help system to provide end user help on any commercial
application that is written with Pharo.
As I said you can convert any text data into topics to be displayed
by the help system: the browser is able to open on anything that
is convertable to a root topic using #asHelpTopic. More on this later.
When you open the help browser it provides help for the
whole system, so
HelpBrowser open
is the same as
HelpBrowser openOn: SystemHelp
which internally uses the class CustomHelp and subclasses to provide
written text and API help to form a system wide help system.
If you want you can also load "Metacello-Help" and "Squeak-Help"
from the http://www.squeaksource.com/HelpSystem repository to see
how the new topics are automatically used when they were just loaded.
Yes, I would like to see a richer text support (using markup
language) and written text documentation accessible directly
from within the image. But the first step was to get a simple
model, the next step would be to see if the extension mechanism
is good enough (CustomHelp, HelpBuilder with own builders, ...)
Some more notes on the architecture and extension ideas:
========================================================
1. the model as I said before is now reduced to a single class
(HelpTopic)
2. When you open the help browser on an object the method #asHelpTopic
is sent to the object by the browser to get the root node of
the displayed topic hierarchy:
HelpBrowser openOn: myObject
Typically the object does not convert itself to a help topic structure,
usually it dispatches to a builder (see HelpBuilder and subclasses)
who does all this.
So the help text can be already in the image even when the help
system itself is NOT YET THERE/LOADED and if you want to provide help text
in whatever form you are not dependent on the help system itself!!!
Later a builder can extract and convert the data. You can have builders
for anything - even a builder who gets informations from the web or
hard disk.
But note: if you want to have your own help shown up in the
standard help then you have to at least use the "CustomHelp" subclass
mechanism.
3. The help browser is a simple tree view and is currently limited to
ASCII text. One step in the future could be to provide a "contentType"
(similar to MIME) to support other content types (for instance active
morphs displayed in clean up book morphs, HTML help with scamper in
the help browser, ...)
4. I dont expect the basic model to change much further - maybe
Take care: all of this is still unfinished but in a usable state.
The "Help on Help" is not yet updated. The tests are not reviewed,
just brouht to green.
So you have to rely on the implementation, all the informations
in this mail or directly ask questions.
Bye
Torsten
--
GMX DSL: Internet, Telefon und Entertainment für nur 19,99 EUR/mtl.!
http://portal.gmx.net/de/go/dsl02
_______________________________________________
Pharo-project mailing list
[email protected]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
