Crosspost squeak-dev/pharo-dev 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 (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 use: a) Wiki Style or similar + easy to write + easy to transform - mostly non-standard With Maven the APT format is often used [1], Eclipse for instance provides even editors, see [2] 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 to javascript <a href="smalltalk:..." 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 [3] and [4] for more info. Maybe someone has a minute ;) Bye T. [1] http://maven.apache.org/doxia/references/apt-format.html [2] http://sourceforge.net/project/screenshots.php?group_id=193560 [3] http://n4.nabble.com/ANN-HelpSystem-was-ProfStef-td1554685.html [4] http://www.cincomsmalltalk.com/userblogs/rowanb/blogView?showComments=true&p... -- Sicherer, schneller und einfacher. Die aktuellen Internet-Browser - jetzt kostenlos herunterladen! http://portal.gmx.net/de/go/chbrowser