[Pharo-project] [ANN] Pharo Online Help 1.0

Torsten Bergmann astares at gmx.de
Tue Nov 6 23:13:30 CET 2012


a little story:

As you may know I wrote the current "Pharo help" implementation which
you can access from the Help menu or via 

  HelpBrowser open 

I'm still not satisfied with it. Some projects like NativeBoost, 
Metacello and others already provide an appropriate help package - but
still beginners help and documentation is not where I would like to see it.

The HelpBrowser is only usable within the image and other nice docu (blog
posts, videos, ...) for Pharo is available online. You have to know
about these pages after downloading Pharo to find the tips and tricks 
and nice features of the Smalltalk world.

There is also no central "docu" point for someone who just downloaded 
Pharo and want a "Quick start". Also I dislike that we are limited with 
the in-image presentation style (text only) and that content is not 
visible to Google, Bing, etc.
That made me think about web/HTML/Internet like documentation again
and the image as the central place beginners have downloaded already. 

After many years of private research I now noticed that HTML is 
nothing more than a structured String - so I started coding... :)

Packaging Seaside with the default Pharo image to serve help content
would be overkill - but there is always a leaner way. 
Since Pharo 2.0 we have Zinc HTTP components within the image 
(thanks Sven!) and I played a little bit with it. It is really easy 
to setup/startup a webserver from Smalltalk now.
So I wrote a basic "HelpServer" and wrapped the nice "twitter bootstrap"
library. Code may be ugly and require some refactoring ... but it is
currently more a prove of concept. 

Attached is a screenshot of the result running in a webbrowser.

What is it: the idea is that we server the documentation from within the 
image but use the local webbrowser to display it. Since we soon integrate NativeBoost in Pharo 2.0 it is also easy to open the browser as soon as "Help" is requested from a menu. 

Serving for the web would also mean we could easily setup an image 
online that displays the docu online for indexing by search engines etc.

Where is the code:

 http://ss3.gemstone.com/ss/PharoOnlineHelp.html  (Read/Write)

If you want to play with it yourself then start a Pharo 2.0 image, go to 
"Tools" -> "ConfigurationBrowser", select "PharoOnlineHelp" and select
"Install configuration (stable version)" from the context menu.

After that evaluate 

   HelpServer start

and point your browser to http://localhost:8080

If you like scripting you can also evaluate in a Pharo 2.0 image:

   Gofer it
	squeaksource3: 'PharoOnlineHelp';
	package: 'ConfigurationOfPharoOnlineHelp';
   ((Smalltalk at: #ConfigurationOfPharoOnlineHelp) project version: #stable) load.
   (Smalltalk at: #HelpServer) start 

Next steps:

 1. Lets discuss how we want to fill the "API help" section. I know that 
    there once was a project that generated static API help  
    (http://magaloma.seasidehosting.st) but we can now directly serve 
    from the live image.

    My current implementation allows to navigate from classes to 
    subclasses and superclasses - just to give you an idea. Maybe we 
    want to display only class comments or provide a real Smalltalk 
    browser within the webbrowser (similar to http://www.Amber-lang.net)

 2. The section "Intro" is only a mock. I would like to see that people 
    can find short "Quick start" like tutorials here to start with 
    basic things like Smalltalk, Metacello, ...

    Maybe we can integrate a live and running ProfStef similar to 
    http://amber-lang.net/learn.html that is adopted to Pharo.

 3. Lets discuss how we want to describe the content "in-image" 
    for "serving on the web". Maybe with a "Markup to HTML translator" 
    - or a "WikiStyle to HTML" like help

My wish to Santa would be that Pharo 2.0 comes with a better and
nicer out-of-the-box documentation. For each package/project we should
have a common way to define/load/browse docu and tutorials so people 
can just load and quick start without much hazzle.

The code repo is open for read and write - I would appreciate 
comments, code contributions, help/tutorial content and ideas.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: onlinehelp.png
Type: image/png
Size: 43530 bytes
Desc: not available
URL: <http://lists.gforge.inria.fr/pipermail/pharo-project/attachments/20121106/38371199/attachment.png>

More information about the Pharo-project mailing list