[squeak-dev] Help system changes

H. Hirzel hannes.hirzel at gmail.com
Tue Jun 5 03:58:00 UTC 2018

On 6/5/18, Chris Muller <asqueaker at gmail.com> wrote:
>>>> I've been trying to clean up the help system a bit; starting with
>>>> tidying the code side of things to make it easier to edit the content
>>>> etc. Mostly I want to update some stuff- having an 'official' help page
>>>> for Squeak 5.2 that tells people they need SqueakV64.sources is probably
>>>> a bit unhelpful, for example.
>>> That sounds helpful to me, why is that unhelpful?
>> Oh, I don't know, perhaps because it's factually incorrect? That seems a
>> bit unhelpful to me.
> Tim, you mentioned an 'official' [sic] help page -- at first I thought
> you meant the one presented by selecting, "Squeak Help".  But there's
> no mention of the .sources file there, so I asked an honest question
> for clarification.  Your response is, uh, unhelpful, and why I still
> no idea what you're talking about.
> A changeset or Inbox mcz is the easiest way to understand your
> proposal, even if only an incomplete sketch.

And some screen shots ....


>  - Chris
>> [snip]
>>>> 2. The general help is opened such that the content is displayed in a
>>>> plain PluggableTextMorphPlus. Any pages displayed within the general
>>>> help are plain text. However, the 'TerseGuide' and 'Useful Expressions'
>>>> specific entries open help browsers that are set up with Shout styling.
>>>> There's a couple issues with that
>>>> a) The content looks different in the two versions, which seems like a
>>>> good way to engender some confusion in new users.
>>> If they're to be on their way to interacting with Squeak, I would
>>> expect the executable code examples to be Shout styled, while the
>>> non-code help to not (necessarily) be.
>> You are making my argument for me about why the styling should not be
>> decided at the gross level but at the 'retail' level.
>>>> b) There really isn't any meaningful benefit I can see to using shout
>>>> styling in either of these two places (I'm sure there are case where it
>>>> would be important)
>>> They're code examples, Shout styling is tremendously beneficial.
>> I disagree about the 'tremendously' part. And the problem part is the way
>> that they are styled or not in surprising places, not particularly whether
>> styled or  not.
>>>> c) The choice is made in the the TheWorldMainDockingBar>>#commandKeyHelp
>>>> and related methods, whereas it surely ought to be at least specific to
>>>> the Help book, better yet specific to the topic and probably best of
>>>> all, limited to sections of  pages where it is marked up to be styled.
>>> I'm not sure what you're saying here.  Command-key help is one of the
>>> first things both new and returning users look for, it should
>>> _definitely_ remain on that menu.  I see no reason to slow new users
>>> down from learning how to navigate and use the system with hot-keys
>>> before they get around to opening up that help tome and get to
>>> "Chapter 37 -- Hot Keys".  Please, no.
>> Yet again you're completely and utterly missing the point of what was
>> written. Read section c) again. It's *nothing* to do with whether 'command
>> key help' should or should not be listed anywhere.
>>>> For 1. I propose reducing the menu entries to Squeak Help, Release Notes
>>>> & About Squeak. The only complication I see is adding the swiki based
>>>> help book into the general help.
>>> Yikes!  Why?
>> Reduction of redundant and unnecessarily repeated redundancy. Tastes may
>> vary.
>>>> For 2. I suggest dropping the
>>>> TheWorldMainDockingBar>>#openHelp:topic:styled: and just opening the
>>>> general help browser. In the future I'd hope we can provide a markup
>>>> facility to allow a section of text to be styled with Shout or indeed
>>>> some other mechanism. Maybe we could extend the cmd-6 menu to add that.
>>> If they are to learn Squeak and OO, we should reinforce the idea that
>>> paths to objects are *designed* based on _human_ needs, not merely one
>>> grand root that forces you to navigate down a hierarchical path just
>>> to ask how to open a browser with the keyboard.
>> Yet again, completely and utterly missing the point. This is a suggestion
>> to change the API the opens the help browser in such a way as to improve
>> the readability of the help content by enabling Shout styling where you
>> want it and detailed manual styling - like maybe bolding and italic and
>> underlining - where you want it. Which would as a nice side-effect obviate
>> the current unfortunate scenario of one route to seeing the TerseGuide
>> content displaying it styled and the alternate route showing it completely
>> plain.
>> tim
>> --
>> tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
>> Strange OpCodes: PFM: Pray For Miracle
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Main_help_system_menu_Screenshot_2018-06-05.png
Type: image/png
Size: 70706 bytes
Desc: not available
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20180605/53d0590d/attachment-0001.png>

More information about the Squeak-dev mailing list