The Inbox: HelpSystem-Core-dtl.110.mcz

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

The Inbox: HelpSystem-Core-dtl.110.mcz

commits-2
David T. Lewis uploaded a new version of HelpSystem-Core to project The Inbox:
http://source.squeak.org/inbox/HelpSystem-Core-dtl.110.mcz

==================== Summary ====================

Name: HelpSystem-Core-dtl.110
Author: dtl
Time: 6 August 2019, 8:02:02.4221 pm
UUID: 1d5757f7-f282-4072-bee9-cacb63c3f24d
Ancestors: HelpSystem-Core-kks.109

Let any Behavior open a help browser on itself.

=============== Diff against HelpSystem-Core-kks.109 ===============

Item was added:
+ ----- Method: Behavior>>help (in category '*HelpSystem-Core') -----
+ help
+ "Open a help browser. For classes that implement #help for some other purpose,
+ use #openHelpBrowser instead."
+
+ "Array help"
+ "ObjectTracer help"
+ "SMLoader openHelpBrowser"
+
+ self openHelpBrowser!

Item was added:
+ ----- Method: Behavior>>openHelpBrowser (in category '*HelpSystem-Core') -----
+ openHelpBrowser
+ HelpBrowser openOn: self asHelpTopic!


Reply | Threaded
Open this post in threaded view
|

Re: The Inbox: HelpSystem-Core-dtl.110.mcz

Chris Muller-3
+1 for adding #openHelpBrowser, but -1 for overloading #help.  Please don't.

#openHelpBrowser is perfectly descriptive.  JavaDoc was never very useful, we don't need to try to save typing for this feature.  If you disagree, please consider integrating somewhere into the IDE (class menu?) but still use #openHelpBrowser.  The core library should not poach #help from the namespace.

Best,
  Chris



On Tue, Aug 6, 2019 at 7:02 PM <[hidden email]> wrote:
David T. Lewis uploaded a new version of HelpSystem-Core to project The Inbox:
http://source.squeak.org/inbox/HelpSystem-Core-dtl.110.mcz

==================== Summary ====================

Name: HelpSystem-Core-dtl.110
Author: dtl
Time: 6 August 2019, 8:02:02.4221 pm
UUID: 1d5757f7-f282-4072-bee9-cacb63c3f24d
Ancestors: HelpSystem-Core-kks.109

Let any Behavior open a help browser on itself.

=============== Diff against HelpSystem-Core-kks.109 ===============

Item was added:
+ ----- Method: Behavior>>help (in category '*HelpSystem-Core') -----
+ help
+       "Open a help browser. For classes that implement #help for some other purpose,
+       use #openHelpBrowser instead."
+
+       "Array help"
+       "ObjectTracer help"
+       "SMLoader openHelpBrowser"
+
+       self openHelpBrowser!

Item was added:
+ ----- Method: Behavior>>openHelpBrowser (in category '*HelpSystem-Core') -----
+ openHelpBrowser
+       HelpBrowser openOn: self asHelpTopic!




Reply | Threaded
Open this post in threaded view
|

Re: The Inbox: HelpSystem-Core-dtl.110.mcz

David T. Lewis
On Wed, Aug 07, 2019 at 05:26:51PM -0500, Chris Muller wrote:
> +1 for adding #openHelpBrowser, but -1 for overloading #help.  Please don't.
>

Point well taken. I put #openHelpBrowser into trunk and moved my inbox
submission to treated.


> #openHelpBrowser is perfectly descriptive.  JavaDoc was never very useful,
> we don't need to try to save typing for this feature.  If you
> disagree, please consider integrating somewhere into the IDE (class menu?)
> but still use #openHelpBrowser.  The core library should not poach #help
> from the namespace.
>

Interestingly and somewhat ironically, the current implementers of #help
do nothing of direct interest to the hypothetical DynaBook user. They might
better be renamed to e.g. #helpString.

If the selector #help were to be implemented in some way that might be
directly meaningful to users, then what should it do?

Dave



> Best,
>   Chris
>
>
>
> On Tue, Aug 6, 2019 at 7:02 PM <[hidden email]> wrote:
>
> > David T. Lewis uploaded a new version of HelpSystem-Core to project The
> > Inbox:
> > http://source.squeak.org/inbox/HelpSystem-Core-dtl.110.mcz
> >
> > ==================== Summary ====================
> >
> > Name: HelpSystem-Core-dtl.110
> > Author: dtl
> > Time: 6 August 2019, 8:02:02.4221 pm
> > UUID: 1d5757f7-f282-4072-bee9-cacb63c3f24d
> > Ancestors: HelpSystem-Core-kks.109
> >
> > Let any Behavior open a help browser on itself.
> >
> > =============== Diff against HelpSystem-Core-kks.109 ===============
> >
> > Item was added:
> > + ----- Method: Behavior>>help (in category '*HelpSystem-Core') -----
> > + help
> > +       "Open a help browser. For classes that implement #help for some
> > other purpose,
> > +       use #openHelpBrowser instead."
> > +
> > +       "Array help"
> > +       "ObjectTracer help"
> > +       "SMLoader openHelpBrowser"
> > +
> > +       self openHelpBrowser!
> >
> > Item was added:
> > + ----- Method: Behavior>>openHelpBrowser (in category '*HelpSystem-Core')
> > -----
> > + openHelpBrowser
> > +       HelpBrowser openOn: self asHelpTopic!
> >
> >
> >

>


Reply | Threaded
Open this post in threaded view
|

Re: The Inbox: HelpSystem-Core-dtl.110.mcz

Chris Muller-4
> On Wed, Aug 07, 2019 at 05:26:51PM -0500, Chris Muller wrote:
> > +1 for adding #openHelpBrowser, but -1 for overloading #help.  Please don't.
> >
>
> Point well taken. I put #openHelpBrowser into trunk and moved my inbox
> submission to treated.

Cool, thanks.

> > #openHelpBrowser is perfectly descriptive.  JavaDoc was never very useful,
> > we don't need to try to save typing for this feature.  If you
> > disagree, please consider integrating somewhere into the IDE (class menu?)
> > but still use #openHelpBrowser.  The core library should not poach #help
> > from the namespace.
> >
>
> Interestingly and somewhat ironically, the current implementers of #help
> do nothing of direct interest to the hypothetical DynaBook user. They might
> better be renamed to e.g. #helpString.

I saw them too and had that very same thought.  At least they're
app-specific, except ToolBuilderSpec, but its probably fine for now..

> If the selector #help were to be implemented in some way that might be
> directly meaningful to users, then what should it do?

That's a great question.  "help" is such a universal word, the idea of
being able to ask any Object for help feels right, doesn't it?

So which behaviors would we want to encapsulate "generally", and which
hooks to provide enough customization for apps to "do their own
thing"?  On the one hand, it would be nice to provide an apparatus
that apps can hook in to with very little effort which could provide
something like #openHelpBrowser.  On the other, I can see apps and
frameworks wanting to provide their own entirely different solution to
#help, so there'd need to be an overridability at that broader level
too.


 - Chris

Reply | Threaded
Open this post in threaded view
|

Re: The Inbox: HelpSystem-Core-dtl.110.mcz

David T. Lewis
On Thu, Aug 08, 2019 at 03:15:05PM -0500, Chris Muller wrote:

> > On Wed, Aug 07, 2019 at 05:26:51PM -0500, Chris Muller wrote:
> > > +1 for adding #openHelpBrowser, but -1 for overloading #help.  Please don't.
> > >
> >
> > Point well taken. I put #openHelpBrowser into trunk and moved my inbox
> > submission to treated.
>
> Cool, thanks.
>
> > > #openHelpBrowser is perfectly descriptive.  JavaDoc was never very useful,
> > > we don't need to try to save typing for this feature.  If you
> > > disagree, please consider integrating somewhere into the IDE (class menu?)
> > > but still use #openHelpBrowser.  The core library should not poach #help
> > > from the namespace.
> > >
> >
> > Interestingly and somewhat ironically, the current implementers of #help
> > do nothing of direct interest to the hypothetical DynaBook user. They might
> > better be renamed to e.g. #helpString.
>
> I saw them too and had that very same thought.  At least they're
> app-specific, except ToolBuilderSpec, but its probably fine for now..
>
> > If the selector #help were to be implemented in some way that might be
> > directly meaningful to users, then what should it do?
>
> That's a great question.  "help" is such a universal word, the idea of
> being able to ask any Object for help feels right, doesn't it?
>
> So which behaviors would we want to encapsulate "generally", and which
> hooks to provide enough customization for apps to "do their own
> thing"?  On the one hand, it would be nice to provide an apparatus
> that apps can hook in to with very little effort which could provide
> something like #openHelpBrowser.  On the other, I can see apps and
> frameworks wanting to provide their own entirely different solution to
> #help, so there'd need to be an overridability at that broader level
> too.
>

Maybe provide the concept of a help provider that can be different
depending on what help services are available in the image, and defaulting
to a vanilla browser.


   Behavior>>help
      Smalltalk helpProvider helpFor: self.
   
   SmalltalkImage>>helpProvider
      "Default implementation, but maybe use a registry of providers"
      ^self at: #HelpBrowser ifAbsent: ToolSet
   
   ToolSet class>>helpFor: aBehavior
      self browseClass: aBehavior
   
   HelpBrowser class>>helpFor: aBehavior
      self openOn: aBehavior asHelpTopic

Dave