Re: ANNOUNCE : HelpViewer 0.1

[Richard Frith-Macdonald]

On Wednesday, January 22, 2003, at 10:57  am, Andreas Heppel wrote:
> different levels of help. To me it looks like we all know what we 
> want, but only name it differently. Let me resume a couple of points I 
> think we all more or less agree on:
>
> - There is something we call tooltips, which is a very short 
> description of a control. This pops up automatically some time after 
> the mouse cursor starts to hover over an UI element and goes away 
> automatically, too.

This is clearly what NSHelpManager in MacOS-X is supposed to do ... 
with the exception that you actually have to hold the 'help' key and 
click on an item rather than just move the mouse over it.
I don't think there is an equivalent in OpenStep/NeXTstep as the action 
of help-clicking an item was supposed to give you context sensitive 
help there (which is presumably why NSHelpManager documentation talks 
about context sensitive help when it really means tooltips).

> - We need an application help being displayed when the user chooses 
> the 'Help' menu. This text is an overall description of the app and 
> how it works and is displayed in a more sophisticated viewer being 
> able to index, search, follow links etc. This currently is supplied by 
> Nicolas' HelpViewer. I think the only question here is which file 
> format to use and whether to integrate this viewer into GNUstep 
> instead of being a separate app. IMHO, HelpViwer is good the way it 
> is, thus remaining only the question about help file formats.

In MacOS-X this is done by a separate helpviewer application, and the 
NSApplication -showHelp method triggers it.
In OpenStep/NeXTstep it's handled by the NSHelpPanel/HelpPanel.

> - We want some 'context help' being a relatively short description of 
> what the user can do in an exact situation, e.g. what is a certain 
> panel used for.

In MacOS-X I don't think you do this ... except in as much as you have 
a bit more text in your 'tooltip'

In OpenStep/NeXTstep this is handled by NSHelpPanel/HelpPanel ... 
basically, the help panel is displayed, with the current view set to 
that portion of the application help which is relevant to the current 
context.

> To me it makes no sense to have some kind of enhanced tooltips being 
> displayed in a separate panel (like in Windoze, I don't know KDE). I 
> want this help to be displayed in viewer with exact the same functions 
> as described above: follow links to topics, search for keywords etc 
> (which is what the Windoze context help does not provide).

This is what NSHelpPanel is supposed to do.

> Thus, I vote for using HelpViewer for the context help because it 
> provides (or at least will do so) all this.
> The question left is how to make HelpViewer  display only a certain, 
> context sensitive portion of the help file. IMO, we must clarify two 
> points here:
> 1. the API by which HelpViewer is triggered and
> 2. how to make context help available to the user, i.e. what will the 
> user have to press, click, point to to get context help?
> This 2nd point is very important because the user needs a consistent 
> way in all (GNUstep) apps to get the desired help.
>
> Before I get into probably rather logish discussions on any of those 
> points I would like to know your opinion on the above. Do we agree on 
> those points as a base for further discussion? Any comments?

I think NeXT had this more or less right with NSHelpPanel and went 
wrong when they/Apple replaced it with NSHelpManager.  Certainly my 
experience of using help under NeXTstep was much nicer than that under 
MacOS-X.

They didn't have tooltips, but they did have good context sensitive 
help.

In an ideal world I'd provide a range of help capabilities like this ...

1. tooltips ... use NSHelpManager but change it so that the tooltip is 
displayed when the mouse passes over an item rather than when it's 
clicked.
2. context help ... use NSHelpPanel as it was intended (but perhaps it 
should support xhtml help rather than rtf help)
3. main app help from the menu ... perhaps ask a helpviewer app to open 
the apps help file, if no helpviewer is available, use NSHelpPanel

I'd put the main part of the help display code in NSHelpPanel, and have 
the helpviewer app add the capability to show/search help from
multiple applications.

Using NSHelpPanel has the advantage that the state of your help panel 
is retained on a per-app basis, so you can switch between looking at 
the help in different apps very easily/quickly.  Getting the same 
usability with a single helpviewer app depends on defining an extra DO 
API for the apps to tell the helpviewer what to do ... it can be done 
but seems like a lot of effort for no real gain.