this is cool. No time to fully read now but later for sure. I would like to see how we can integrate the book chapters. This is why we brainstormed with damien c to see how we can use Pier format as a core format for all the doc and so that we can generate the book (like for the seaside book).
Stef On Nov 6, 2012, at 11:13 PM, Torsten Bergmann wrote: > Hi, > > 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'; > load. > > ((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. > > Thanks > Torsten > <onlinehelp.png>
