[Preview] Help System with new model

> Hi,
>
> sorry for the delay on the help system - but time is
> rare these days.
>
> I know some of you are impatient - therefore I've commited my
> restructured code for the help system for you to look what
> is coming - even when it is not fully finished. But the restructured
> new model is now in place - I have to add more tests and
> adapt the "help on the help system" to document my ideas.
> I also want to work on compatibility with Squeak as the
> first version had. Currently the new stuff only work
> in Pharo.
>
> What is new
> ===========
> While we had 3 model classes in my initial version (and after
> Dannys additions even more classes) I now reduced the model
> to a very, very simple approach with just one model class.
>
> We now have a HelpBrowser that is "just" displaying topics.
> A topic (see class HelpTopic) is
>
> - providing a title and optionally an icon
> - able to have subtopics,
> - provides contents (that is displayed be the browser),
> - can be identified by a unique key (so we can later open the
>   help browser on a specific topic from within other tools)
>
> You can create help topics from each and anything.
>
>
> To try it out just load the baseline (in Pharo 1.0 or 1.1):
>
> --------------------------------------------
> Gofer new
>   squeaksource: 'MetacelloRepository';
>   package: 'ConfigurationOfHelpSystem';
>   load.
>
>  ((Smalltalk at: #ConfigurationOfHelpSystem) project version: '1.0-baseline') load
> --------------------------------------------
>
>
> You can open the help browser from the world tool menu or via
> code:
>
>   HelpBrowser open
>
> You can open the help browser on any object that is able to
> be converted into a help topic (via method #asHelpTopic).
>
> So you can write for instance:
>
>   HelpBrowser openOn: Integer
>
> opening a short API help/system reference on the Integer class.
> The above expression is the short form for:
>
>   HelpBrowser openOn: (SystemReference forClass: Integer)
>
> If you want you can include the subclasses:
>
>   HelpBrowser openOn: (SystemReference hierarchyFor: Integer)
>
> or even methods
>
>   HelpBrowser openOn: (SystemReference hierarchyWithMethodsFor: Integer)
>
> You can browse the whole system reference documentation using:
>
>    HelpBrowser openOn: SystemReference
>
> But these are only a few examples what we can extract from the
> system.
>
> However - the major goal is NOT an API browser, the idea is to
> provide a simple architecture to provide browsable help contents
> depending on the context. For instance it should also be possible
> to use the help system to provide end user help on any commercial
> application that is written with Pharo.
>
> As I said you can convert any text data into topics to be displayed
> by the help system: the browser is able to open on anything that
> is convertable to a root topic using #asHelpTopic. More on this later.
>
> When you open the help browser it provides help for the
> whole system, so
>
>   HelpBrowser open
>
> is the same as
>
>   HelpBrowser openOn: SystemHelp
>
> which internally uses the class CustomHelp and subclasses to provide
> written text and API help to form a system wide help system.
>
> If you want you can also load "Metacello-Help" and "Squeak-Help"
> from the http://www.squeaksource.com/HelpSystem repository to see
> how the new topics are automatically used when they were just loaded.
>
>
> Yes, I would like to see a richer text support (using markup
> language) and written text documentation accessible directly
> from within the image. But the first step was to get a simple
> model, the next step would be to see if the extension mechanism
> is good enough (CustomHelp, HelpBuilder with own builders, ...)
>
>
> Some more notes on the architecture and extension ideas:
> ========================================================
> 1. the model as I said before is now reduced to a single class
>    (HelpTopic)
>
> 2. When you open the help browser on an object the method #asHelpTopic
>    is sent to the object by the browser to get the root node of
>    the displayed topic hierarchy:
>
>       HelpBrowser openOn: myObject
>
>    Typically the object does not convert itself to a help topic structure,
>    usually it dispatches to a builder (see HelpBuilder and subclasses)
>    who does all this.
>
>    So the help text can be already in the image even when the help
>    system itself is NOT YET THERE/LOADED and if you want to provide help text
>    in whatever form you are not dependent on the help system itself!!!
>
>    Later a builder can extract and convert the data. You can have builders
>    for anything - even a builder who gets informations from the web or
>    hard disk.
>
>    But note: if you want to have your own help shown up in the
>    standard help then you have to at least use the "CustomHelp" subclass
>    mechanism.
>
> 3. The help browser is a simple tree view and is currently limited to
>    ASCII text. One step in the future could be to provide a "contentType"
>    (similar to MIME) to support other content types (for instance active
>    morphs displayed in clean up book morphs, HTML help with scamper in
>    the help browser, ...)
>
> 4. I dont expect the basic model to change much further - maybe
>
> Take care: all of this is still unfinished but in a usable state.
>      The "Help on Help" is not yet updated. The tests are not reviewed,
>      just brouht to green.
>
>      So you have to rely on the implementation, all the informations
>      in this mail or directly ask questions.
>
> Bye
> Torsten
>
>
>
>
>
>
>
>
>
>
>
>
> --
> GMX DSL: Internet, Telefon und Entertainment für nur 19,99 EUR/mtl.!
> http://portal.gmx.net/de/go/dsl02
>
> _______________________________________________
> Pharo-project mailing list
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

> Hi,
>
> sorry for the delay on the help system - but time is
> rare these days.
>
> I know some of you are impatient - therefore I've commited my
> restructured code for the help system for you to look what
> is coming - even when it is not fully finished. But the restructured
> new model is now in place - I have to add more tests and
> adapt the "help on the help system" to document my ideas.
> I also want to work on compatibility with Squeak as the
> first version had. Currently the new stuff only work
> in Pharo.
>
> What is new
> ===========
> While we had 3 model classes in my initial version (and after
> Dannys additions even more classes) I now reduced the model
> to a very, very simple approach with just one model class.
>
> We now have a HelpBrowser that is "just" displaying topics.
> A topic (see class HelpTopic) is
>
> - providing a title and optionally an icon
> - able to have subtopics,
> - provides contents (that is displayed be the browser),
> - can be identified by a unique key (so we can later open the
>   help browser on a specific topic from within other tools)
>
> You can create help topics from each and anything.
>
>
> To try it out just load the baseline (in Pharo 1.0 or 1.1):
>
> --------------------------------------------
> Gofer new
>   squeaksource: 'MetacelloRepository';
>   package: 'ConfigurationOfHelpSystem';
>   load.
>
>  ((Smalltalk at: #ConfigurationOfHelpSystem) project version: '1.0-baseline') load
> --------------------------------------------
>
>
> You can open the help browser from the world tool menu or via
> code:
>
>   HelpBrowser open
>
> You can open the help browser on any object that is able to
> be converted into a help topic (via method #asHelpTopic).
>
> So you can write for instance:
>
>   HelpBrowser openOn: Integer
>
> opening a short API help/system reference on the Integer class.
> The above expression is the short form for:
>
>   HelpBrowser openOn: (SystemReference forClass: Integer)
>
> If you want you can include the subclasses:
>
>   HelpBrowser openOn: (SystemReference hierarchyFor: Integer)
>
> or even methods
>
>   HelpBrowser openOn: (SystemReference hierarchyWithMethodsFor: Integer)
>
> You can browse the whole system reference documentation using:
>
>    HelpBrowser openOn: SystemReference
>
> But these are only a few examples what we can extract from the
> system.
>
> However - the major goal is NOT an API browser, the idea is to
> provide a simple architecture to provide browsable help contents
> depending on the context. For instance it should also be possible
> to use the help system to provide end user help on any commercial
> application that is written with Pharo.
>
> As I said you can convert any text data into topics to be displayed
> by the help system: the browser is able to open on anything that
> is convertable to a root topic using #asHelpTopic. More on this later.
>
> When you open the help browser it provides help for the
> whole system, so
>
>   HelpBrowser open
>
> is the same as
>
>   HelpBrowser openOn: SystemHelp
>
> which internally uses the class CustomHelp and subclasses to provide
> written text and API help to form a system wide help system.
>
> If you want you can also load "Metacello-Help" and "Squeak-Help"
> from the http://www.squeaksource.com/HelpSystem repository to see
> how the new topics are automatically used when they were just loaded.
>
>
> Yes, I would like to see a richer text support (using markup
> language) and written text documentation accessible directly
> from within the image. But the first step was to get a simple
> model, the next step would be to see if the extension mechanism
> is good enough (CustomHelp, HelpBuilder with own builders, ...)
>
>
> Some more notes on the architecture and extension ideas:
> ========================================================
> 1. the model as I said before is now reduced to a single class
>    (HelpTopic)
>
> 2. When you open the help browser on an object the method #asHelpTopic
>    is sent to the object by the browser to get the root node of
>    the displayed topic hierarchy:
>
>       HelpBrowser openOn: myObject
>
>    Typically the object does not convert itself to a help topic structure,
>    usually it dispatches to a builder (see HelpBuilder and subclasses)
>    who does all this.
>
>    So the help text can be already in the image even when the help
>    system itself is NOT YET THERE/LOADED and if you want to provide help text
>    in whatever form you are not dependent on the help system itself!!!
>
>    Later a builder can extract and convert the data. You can have builders
>    for anything - even a builder who gets informations from the web or
>    hard disk.
>
>    But note: if you want to have your own help shown up in the
>    standard help then you have to at least use the "CustomHelp" subclass
>    mechanism.
>
> 3. The help browser is a simple tree view and is currently limited to
>    ASCII text. One step in the future could be to provide a "contentType"
>    (similar to MIME) to support other content types (for instance active
>    morphs displayed in clean up book morphs, HTML help with scamper in
>    the help browser, ...)
>
> 4. I dont expect the basic model to change much further - maybe
>
> Take care: all of this is still unfinished but in a usable state.
>      The "Help on Help" is not yet updated. The tests are not reviewed,
>      just brouht to green.
>
>      So you have to rely on the implementation, all the informations
>      in this mail or directly ask questions.
>
> Bye
> Torsten
>
>
>
>
>
>
>
>
>
>
>
>
> --
> GMX DSL: Internet, Telefon und Entertainment für nur 19,99 EUR/mtl.!
> http://portal.gmx.net/de/go/dsl02
>
> _______________________________________________
> Pharo-project mailing list
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

> Can you consider the idea of a PragmaHelpBuilder as an extension to
> your system?
>
> I can define a method like this on some class:
>
> helpForThisPartOfTheSystem
> <helpTopic: 'Title goes here'>
>
> ^'Contents goes here.
> foo
> bar
> wibble'
>
> And then I can find all of these pragmas:
>
> | pragmas topics |
> pragmas := ((SystemNavigation default allMethodsSelect: [:each | each
> pragmas notEmpty])
> select: [:each | each compiledMethod pragmas allSatisfy: [:eachPragma |
> eachPragma keyword = #helpTopic:]])
> collect: [:each | each compiledMethod pragmaAt: #helpTopic:].
> topics := pragmas collect: [:each |
> HelpTopic
> title: (each argumentAt: 1)
> contents: (each method valueWithReceiver: nil arguments: #())]
>
> With a bit more annotation we could build classes just like the simple
> subclass case of CustomHelp where you only have a few methods on the
> class side. i.e just like your metacello example.  Then there is no
> dependency on CustomHelp, and help comments can go anywhere in our
> various package structures for e.g pharo core, dev image.  We would
> just need to decide on a set of annotations.

> Hi Torsten, i like a lot of the new features.
>
> regarding defining help in classes without the help system loaded - i
> think it could be simpler.  I am not sure how this would work as you
> describe in my example where I want to shove some simple help in the
> monticello package.  I don't understand the asHelpTopic conversion and
> which builder to use etc.
>
> I think it should be possible for help to appear in the global help
> browser without having to define a subclass of CustomHelp. This would
> make the entry barrier really low for people to be able to document
> parts of the system using this help system. For example I have spent
> too long on this already ;-)
>
>
> Can you consider the idea of a PragmaHelpBuilder as an extension to
> your system?
>
> I can define a method like this on some class:
>
> helpForThisPartOfTheSystem
> <helpTopic: 'Title goes here'>
>
> ^'Contents goes here.
> foo
> bar
> wibble'
>
> And then I can find all of these pragmas:
>
> | pragmas topics |
> pragmas := ((SystemNavigation default allMethodsSelect: [:each | each
> pragmas notEmpty])
> select: [:each | each compiledMethod pragmas allSatisfy: [:eachPragma |
> eachPragma keyword = #helpTopic:]])
> collect: [:each | each compiledMethod pragmaAt: #helpTopic:].
> topics := pragmas collect: [:each |
> HelpTopic
> title: (each argumentAt: 1)
> contents: (each method valueWithReceiver: nil arguments: #())]
>
> With a bit more annotation we could build classes just like the simple
> subclass case of CustomHelp where you only have a few methods on the
> class side. i.e just like your metacello example.  Then there is no
> dependency on CustomHelp, and help comments can go anywhere in our
> various package structures for e.g pharo core, dev image.  We would
> just need to decide on a set of annotations.
>
> thanks,
> Mike
>
> _______________________________________________
> Pharo-project mailing list
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project