[ANN] Pharo Online Help 1.0

> 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>

> 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>

> Where is the code:
>
> 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.

>
> On 10 Nov 2012, at 21:33, Stéphane Ducasse <[hidden email]> wrote:
>
>>> 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
>>
>> I want to use the pier syntax because I know that I can generate the correct latex
>> with it for the books, and of course any kind of html and other formats.
>
> I vote for Markdown, it is more like a defacto standard.

> On Nov 10, 2012, at 9:41 PM, Sven Van Caekenberghe wrote:
>
>> On 10 Nov 2012, at 21:33, Stéphane Ducasse <[hidden email]> wrote:
>>
>>>> 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
>>>
>>> I want to use the pier syntax because I know that I can generate the correct latex
>>> with it for the books, and of course any kind of html and other formats.
>>
>> I vote for Markdown, it is more like a defacto standard.
>
> I prefer pier since I can convert all the book macros (and I cannot do that in markdown).
> I'm spending so much time writing that at least I want the result to look more than a bad documentation.
>
>> And you can convert Markdown into anything, there exit tons of tools for it.
>>
>> Remember that I sent you my Zinc & Zodiac docs converted to Latex ? Were they no good ?
>
> It depends at which level.
> Can you tag on word in markdown to have bold, italic, index?
> If I would not have written 350 pages of seaside book with pier it would be a different story but
> so far pier syntax is good for doing everything: html, latex, even markdown.

>> If I would not have written 350 pages of seaside book with pier it would be a different story but
>> so far pier syntax is good for doing everything: html, latex, even markdown.
>
> In Markdown, it is *italic* or _italic_ and **bold** and __bold__.
>
> Now for index entries, I don't know exactly - making an automatic index is a special post process function anyway.
> I think you could do something like [ReadStream][index-entry]s are objects that you can read bytes or characters from.
>
> Making a book from several independent source files is quite a job that requires custom programming. It would be very cool if we could do all that in Smalltalk, using a good Markdown parser and a cool object representation.
>
> I have nothing against Pier, but it is something that only exists in our niche world, not in the larger world out there.

>>> It depends at which level.
>>> Can you tag on word in markdown to have bold, italic, index?
>
> stef, I already explained you that at least 4 times! Plus I gave you the solutions,
> the only thing I don't have is the time to complete the Markdown parser!
>
>>> If I would not have written 350 pages of seaside book with pier it would be a different story but
>>> so far pier syntax is good for doing everything: html, latex, even markdown.
>>
>> In Markdown, it is *italic* or _italic_ and **bold** and __bold__.
>>
>> Now for index entries, I don't know exactly - making an automatic index is a special post process function anyway.
>> I think you could do something like [ReadStream][index-entry]s are objects that you can read bytes or characters from.
>>
>> Making a book from several independent source files is quite a job that requires custom programming. It would be very cool if we could do all that in Smalltalk, using a good Markdown parser and a cool object representation.
>>
>> I have nothing against Pier, but it is something that only exists in our niche world, not in the larger world out there.
>
> my words!
>
> So we already had a Markdown / HelpSystem crossover for NativeBoost / ASMJit where we injected
> custom URLs to add method and class links, that worked pretty well. So I assume it will be
> not that much work on top to get section links ready.
>
> Something like book://section/subsection is very easy to do, a bit verbose maybe but very
> consistent.
>
>
> so, please support:
> https://github.com/dh83/PPMarkdown
> http://ss3.gemstone.com/ss/petitmarkdown.html/

> On Nov 12, 2012, at 3:11 PM, Camillo Bruni wrote:
>
>>>> It depends at which level.
>>>> Can you tag on word in markdown to have bold, italic, index?
>>
>> stef, I already explained you that at least 4 times! Plus I gave you the solutions,
>> the only thing I don't have is the time to complete the Markdown parser!
>>
>>>> If I would not have written 350 pages of seaside book with pier it would be a different story but
>>>> so far pier syntax is good for doing everything: html, latex, even markdown.
>>>
>>> In Markdown, it is *italic* or _italic_ and **bold** and __bold__.
>>>
>>> Now for index entries, I don't know exactly - making an automatic index is a special post process function anyway.
>>> I think you could do something like [ReadStream][index-entry]s are objects that you can read bytes or characters from.
>>>
>>> Making a book from several independent source files is quite a job that requires custom programming. It would be very cool if we could do all that in Smalltalk, using a good Markdown parser and a cool object representation.
>>>
>>> I have nothing against Pier, but it is something that only exists in our niche world, not in the larger world out there.
>>
>> my words!
>>
>> So we already had a Markdown / HelpSystem crossover for NativeBoost / ASMJit where we injected
>> custom URLs to add method and class links, that worked pretty well. So I assume it will be
>> not that much work on top to get section links ready.
>>
>> Something like book://section/subsection is very easy to do, a bit verbose maybe but very
>> consistent.
>>
>>
>> so, please support:
>> https://github.com/dh83/PPMarkdown
>> http://ss3.gemstone.com/ss/petitmarkdown.html/
>
>

> You won I put a filter markdown to thrash on my mail sadly.
>
>
> On Nov 12, 2012, at 3:11 PM, Camillo Bruni wrote:
>
>>>> It depends at which level.
>>>> Can you tag on word in markdown to have bold, italic, index?
>>
>> stef, I already explained you that at least 4 times! Plus I gave you the solutions,
>> the only thing I don't have is the time to complete the Markdown parser!
>>
>>>> If I would not have written 350 pages of seaside book with pier it would be a different story but
>>>> so far pier syntax is good for doing everything: html, latex, even markdown.
>>>
>>> In Markdown, it is *italic* or _italic_ and **bold** and __bold__.
>>>
>>> Now for index entries, I don't know exactly - making an automatic index is a special post process function anyway.
>>> I think you could do something like [ReadStream][index-entry]s are objects that you can read bytes or characters from.
>>>
>>> Making a book from several independent source files is quite a job that requires custom programming. It would be very cool if we could do all that in Smalltalk, using a good Markdown parser and a cool object representation.
>>>
>>> I have nothing against Pier, but it is something that only exists in our niche world, not in the larger world out there.
>>
>> my words!
>>
>> So we already had a Markdown / HelpSystem crossover for NativeBoost / ASMJit where we injected
>> custom URLs to add method and class links, that worked pretty well. So I assume it will be
>> not that much work on top to get section links ready.
>>
>> Something like book://section/subsection is very easy to do, a bit verbose maybe but very
>> consistent.
>>
>>
>> so, please support:
>> https://github.com/dh83/PPMarkdown
>> http://ss3.gemstone.com/ss/petitmarkdown.html/
>
>

> Hi,
>
> I completely agree that the PIer syntax is rather niche these days, but we should not confuse the PIer syntax with the Pier model. I think that it would be beneficial to capitalize on this model (and all the infrastructure built on top of it) and simply create a Markdown support.
>
> Cheers,
> Doru
>
>
> On 12 Nov 2012, at 15:56, Stéphane Ducasse <[hidden email]> wrote:
>
>> You won I put a filter markdown to thrash on my mail sadly.
>>
>>
>> On Nov 12, 2012, at 3:11 PM, Camillo Bruni wrote:
>>
>>>>> It depends at which level.
>>>>> Can you tag on word in markdown to have bold, italic, index?
>>>
>>> stef, I already explained you that at least 4 times! Plus I gave you the solutions,
>>> the only thing I don't have is the time to complete the Markdown parser!
>>>
>>>>> If I would not have written 350 pages of seaside book with pier it would be a different story but
>>>>> so far pier syntax is good for doing everything: html, latex, even markdown.
>>>>
>>>> In Markdown, it is *italic* or _italic_ and **bold** and __bold__.
>>>>
>>>> Now for index entries, I don't know exactly - making an automatic index is a special post process function anyway.
>>>> I think you could do something like [ReadStream][index-entry]s are objects that you can read bytes or characters from.
>>>>
>>>> Making a book from several independent source files is quite a job that requires custom programming. It would be very cool if we could do all that in Smalltalk, using a good Markdown parser and a cool object representation.
>>>>
>>>> I have nothing against Pier, but it is something that only exists in our niche world, not in the larger world out there.
>>>
>>> my words!
>>>
>>> So we already had a Markdown / HelpSystem crossover for NativeBoost / ASMJit where we injected
>>> custom URLs to add method and class links, that worked pretty well. So I assume it will be
>>> not that much work on top to get section links ready.
>>>
>>> Something like book://section/subsection is very easy to do, a bit verbose maybe but very
>>> consistent.
>>>
>>>
>>> so, please support:
>>> https://github.com/dh83/PPMarkdown
>>> http://ss3.gemstone.com/ss/petitmarkdown.html/
>>
>>
>
> --
> www.tudorgirba.com
>
> "Every thing should have the right to be different."
>
>
>
>

> On Nov 12, 2012, at 9:57 PM, Tudor Girba <[hidden email]> wrote:
>
>> Hi,
>>
>> I completely agree that the PIer syntax is rather niche these days, but we
>> should not confuse the PIer syntax with the Pier model. I think that it
>> would be beneficial to capitalize on this model (and all the
>> infrastructure built on top of it) and simply create a Markdown support.
>>
>> Cheers,
>> Doru
>>
>>
>> On 12 Nov 2012, at 15:56, Stéphane Ducasse <[hidden email]>
>> wrote:
>>
>>> You won I put a filter markdown to thrash on my mail sadly.
>>>
>>>
>>> On Nov 12, 2012, at 3:11 PM, Camillo Bruni wrote:
>>>
>>>>>> It depends at which level.
>>>>>> Can you tag on word in markdown to have bold, italic, index?
>>>>
>>>> stef, I already explained you that at least 4 times! Plus I gave you the
>>>> solutions,
>>>> the only thing I don't have is the time to complete the Markdown
>>>> parser!
>>>>
>>>>>> If I would not have written 350 pages of seaside book with pier it
>>>>>> would be a different story but
>>>>>> so far pier syntax is good for doing everything: html, latex, even
>>>>>> markdown.
>>>>>
>>>>> In Markdown, it is *italic* or _italic_ and **bold** and __bold__.
>>>>>
>>>>> Now for index entries, I don't know exactly - making an automatic index
>>>>> is a special post process function anyway.
>>>>> I think you could do something like [ReadStream][index-entry]s are
>>>>> objects that you can read bytes or characters from.
>>>>>
>>>>> Making a book from several independent source files is quite a job that
>>>>> requires custom programming. It would be very cool if we could do all
>>>>> that in Smalltalk, using a good Markdown parser and a cool object
>>>>> representation.
>>>>>
>>>>> I have nothing against Pier, but it is something that only exists in
>>>>> our niche world, not in the larger world out there.
>>>>
>>>> my words!
>>>>
>>>> So we already had a Markdown / HelpSystem crossover for NativeBoost /
>>>> ASMJit where we injected
>>>> custom URLs to add method and class links, that worked pretty well. So I
>>>> assume it will be
>>>> not that much work on top to get section links ready.
>>>>
>>>> Something like book://section/subsection is very easy to do, a bit
>>>> verbose maybe but very
>>>> consistent.
>>>>
>>>>
>>>> so, please support:
>>>> https://github.com/dh83/PPMarkdown
>>>> http://ss3.gemstone.com/ss/petitmarkdown.html/
>>>
>>>
>>
>> --
>> www.tudorgirba.com
>>
>> "Every thing should have the right to be different."
>>
>>
>>
>>
>
>
>