[squeak-dev] Help system changes

tim Rowledge tim at rowledge.org
Mon Jun 4 21:36:34 UTC 2018

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.

Whilst digging through this I note some areas that might be improved and simplified. This really isn't a good time to be making huge changes but we can probably tidy up some.

1. Is it really best to have the current Help menu with a general HelpBrowser opening entry and then several menu items that open browsers on content that is within the general help? Yes, sort-of shortcuts, no, potential for confusion and drift

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

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.

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.

Other ideas welcomed.

tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
Strange OpCodes: UDF: Use Disk for Frisbee

More information about the Squeak-dev mailing list