HelpSystem (was Documentation Team)

> To clearify a few things from my side on the discussion
> on squeak-dev:
>
>  1. HelpSystem is working, if ASCII is OK for now we can use
>     it Pharo/Squeak - otherwise I would see it as an early preview.
>     I have clear goals how it should look like in the
>     next iterations. For this more patience is necessary.
>
>  2. HelpSystem is independent from where and how the actual
>     information is stored (I think I demonstrated this with
>     the IRC example, the books and the API help).
>
>  3. I hope to keep HelpSystem in sync for major Squeak distributions
>     (Squeak, Pharo, Cuis, ...)
>
>     The last additions from Hannes already broke the code
>     in Pharo. Seems to be a Pharo issue this time
>     http://code.google.com/p/pharo/issues/detail?id=2342
>
>     But please dont commit when it is only working in
>     Squeak since my development environment is Pharo.
>
>  4. Yes, the content is currently ASCII but the design is prepared
>     to add other types in future releases.
>
>     A HelpTopic defines an ivar "contents" - currently referring
>     to a string. I may add another ivar "contentType"
>     in the future to handle/distinguish additionaly types
>     (HTML, SqueaksRichText, Morphs/BookMorph, ...)
>
>  5. HelpSystem should not be limited to Squeak. It should also
>     serve the case that when you write and deploy a commercial
>     app in Squeak you may use it to provide help to your
>     end user/customer
>
>  6. There are two types of help I see:
>
>       A. SystemHelp:      Help books/Tutorials/Manuals
>       B. SystemReference: API Help, class comments
>
>     HelpSystem is supporting both.
>     I already wrote about the differences and details in
>     http://lists.gforge.inria.fr/pipermail/pharo-project/2010-April/024857.html
>
>  7. I would really like to see support for HTML viewing
>     in the image (HTMLViewMorph or so) - maybe based on Scamper
>     to get a better viewer (headings, tables, ...) than the
>     current plain text.
>     If people want to contribute they should start right with this
>     task.
>
>     I know that Laurent already made Scamper loadable in Pharo,
>     dont know about the state in Squeak.
>
>     There is also another HTML browser with markup and CSS now available
>     open source as MIT (WithStyle), I already mentioned this.
>
>     http://www.cincomsmalltalk.com/userblogs/rowanb/blogView?showComments=true&printTitle=Im_back..._but_SWS_isnt&entry=3364012145
>
>  8. I know that we now have discussions on which syntax (Wiki,...)
>     to use for describing the contents.
>     My answer is: it is important but I dont care (yet) since
>     this discussion is useless until we have an HTML viewer (see 7.)
>     and  even when there are different syntax styles you can provides
>     builders to transform them into HTML or other contentTypes
>     afterwards.
>
>     See the class HelpBuilder and subclasses.
>
>  9. If you want to write a book for SystemHelp (see 6.A) then
>     the help system provides a class "CustomHelp" similar
>     to TestCase in SUnit. This class is used to directly
>     map book structures to the class hierarchy.
>
>     The intention was to be able to create, store and manage
>     these books directly with the usual Smalltalk tools.
>     You can even restructure your book with the RefactoringBrowser.
>
> 10. If you want to write API help you (see 6.B) can contribute
>     right now by commenting all the undocumented classes in the
>     standard image.
>
>     HelpSystem just queries these informations from the usual
>     sources (class comments, ...). I would not change this
>     or make it too complicated since this is what people are
>     used too.
>
>     I dont see more documented classes by introducing a
>     special syntax (wiki or whatever) people have to learn/know about
>     - so lets clean up documenting the classes first.
>
> 11. HelpSystem is able to get contents from external sources
>     (see the IRC example) - but I would prefer that authoring/viewing
>     could be done right from within the image.
>     Even when the result is stored external afterwards.
>
>     Look at my example books: I can view and change them
>     right from the image and make them available to other images
>     using Metacello/Squeaksource.
>     Accessibility of docu (viewing and authoring) is the key to keep
>     the system and docu in sync and up to date.
>
>     External authoring mostly results in unmaintained docu (see
>     the Squeak Swiki).
>
> 12. I thought again if it is ready to integrate into Pharo and
>     Squeak. From all the discussions I would say it is too early.
>
> 13. If one wants the docu on the web the answer is easy: we
>     can generate static files or serve them with Seaside.
>     But I have no need for that right now, especially since
>     this is already available in various forms.
>
> We can do many things (similar to Python, JavaDoc, you name it)    
>
> But - let's do it step by step. As I said:
>
> - Someone working on a good HTML Viewer that I can integrate
>   would really help moving this forward
>   (based on Scamper or by porting WithStyle)
> - Updating class comments would also help a lot
>
> Bye
> Torsten
>
>
>
>
>
>
>
>
> --
> GRATIS für alle GMX-Mitglieder: Die maxdome Movie-FLAT!
> Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01
>
> _______________________________________________
> Pharo-project mailing list
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

>> Most systems do not try to implement an HTML viewer.  Instead, they
>> talk to whatever web browser you are already using.  Why can't Squeak
>> do the same?  There ought to be some way ti send a URL to an already
>> open browser and tell it to open a window on it.  This is probably
>> done differently on the Mac, WIndows and Linux, but we out to be able
>> to make a simple Squeak API to hide this.
>
> +1
>
> Stef
>

>> Most systems do not try to implement an HTML viewer.  Instead, they
>> talk to whatever web browser you are already using.  Why can't Squeak
>> do the same?  There ought to be some way ti send a URL to an already
>> open browser and tell it to open a window on it.  This is probably
>> done differently on the Mac, WIndows and Linux, but we out to be able
>> to make a simple Squeak API to hide this.
>
> +1
>
> Stef
>

>
> 2010/4/21 Ralph Johnson <[hidden email]>:
>> Most systems do not try to implement an HTML viewer.  Instead, they
>> talk to whatever web browser you are already using.  Why can't Squeak
>> do the same?  There ought to be some way ti send a URL to an already
>> open browser and tell it to open a window on it.  This is probably
>> done differently on the Mac, WIndows and Linux, but we out to be able
>> to make a simple Squeak API to hide this.
>
> I don't know if this still works on all platforms, but you could try
> the following after loading FFI.
>
> "ExternalWebBrowser"
> (Installer repository:
> 'http://www.squeaksource.com/ExternalWebBrowser') install:
> 'ExternalWebBrowser'.
> ExternalWebBrowser openOnUrl:
> 'http://www.squeaksource.com/ExternalWebBrowser.html'.
>
> Alex