[squeak-dev] HelpSystem & Class comments
astares at gmx.de
Wed Feb 24 08:55:48 UTC 2010
Andreas Raab wrote:
>a) Currently a book depends on the presence of HelpSystem (i.e., via
No, you are not forced to be in the "CustomHelp" hierarchy.
You can define an own hierarchy, directly as subclass of Object, whatever
(athough I would recommond CustomHelp as common superclass similar to
TestCase in SUnit)
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.
To get the latest you can just load the baseline:
(ConfigurationOfHelpSystem project version: '1.0-baseline') load
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.
I would also like to see some reactivation of Scamper code for
a more capable viewer/editor - since with a basic support for
simple markup we could catch two flies by providing in-image and
web-help with the same contents/source.
>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).
We may add a book "Reference" where you open two subbooks:
"By categories" and "By hierarchy" - displaying the classes
using categories or in their usual class hierarchy for browsing.
However: the main question to me is the kind of format we should
a) Wiki Style or similar
+ easy to write
+ easy to transform
- mostly non-standard
With Maven the APT format is often used , Eclipse for instance
provides even editors, see  for screenshots)
But we also have Tiny wiki syntax somewhere on SqueakSource which
may be similar.
b) real markup like HTML
+ easy to put onto the web without tranformation
- we need to have more markup support
-/+ embedding of Smalltalk has to be done the W3C way, similar
c) specific format like Squeaks Text representation with textDoits, ...
- very Squeak specific and may not work in Pharo
- hard to put on the web
I would like to see b) with a cleaned up Scamper code since
a general markup editor/viewer would be helpfull anyway and it would
be easy to publish stuff on the web. But looks like more work.
There is also another HTML browser with markup and CSS now available
open source as MIT (WithStyle), see  and  for more info.
Maybe someone has a minute ;)
Sicherer, schneller und einfacher. Die aktuellen Internet-Browser -
jetzt kostenlos herunterladen! http://portal.gmx.net/de/go/chbrowser
More information about the Squeak-dev