Re: What should the user see? (Was: ANNOUNCE : HelpViewer 0.1)

[Richard Frith-Macdonald]

On Wednesday, January 22, 2003, at 03:42  pm, Jonathan Gapen wrote:

> On Wed, 22 Jan 2003 discuss-gnustep-request@gnu.org wrote:
> > Date: Wed, 22 Jan 2003 13:14:03 +0000
> > From: Richard Frith-Macdonald <richard@brainstorm.co.uk>
> > Subject: Re: ANNOUNCE : HelpViewer 0.1
>
> > 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.
>
>      OPENSTEP has tooltips, too, and they are different than what
> NSHelpManager provides though they look superficially similar.  You 
> add a
> tooltip with the NSView method -setToolTip:.  It's just an NSString 
> that
> appears in a yellow rectangle if the mouse pointer lingers in a view, 
> and
> disappears when the mouse pointer moves.

I never used OPENSTEP ... I used NeXTstep.  As far as I can tell, the 
last
versions of NeXTstep for sure, and probably early versions of OPENSTEP
were much closer to the OpenStep idea than later versions of OPENSTEP
or MacOS-X.   I think tooltips must have been added in a late version of
OPENSTEP, as I never saw them in NeXTstep and I don't think they are in
the OpenStep API.

>      The context help is set by the NSHelpManager method
> -setContextHelp:withObject:.  It's an NSAttributedString that appears 
> in a
> yellow rectangle with a drop shadow when the user 'help-clicks' an 
> object,
> and disappears upon the next click.

I have nothing particular against tooltips, but I do very much dislike 
the
replacement of the very good help panel context sensitive help by this
tooltip-like help in NSHelpManager.

> > 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.
>
>      I agree.  As you said, a help panel keeps its state 
> per-application.
>      Using the existing API, a helpviewer app could fill up its own 
> help
> panel with other apps' help files (ab)using the -addSupplement:inPath:
> method, but a more general method which could prove useful is adding a
> method to allow apps to generate help items at run-time.
>                                 ----
>      Perhaps it would help (ha! ha!) in this discussion to put aside
> issues of external apps vs. panels, DO APIs, file formats and other
> implementation issues to focus on the question:  What should the user 
> see?
>      In some cases, that's pretty clear:  When using GNUstep as a
> cross-platform compatibility layer, the user should see the native help
> system.  That's why NeXT invented the NSHelpManager class.

I think you are probably right ... NSHelpManager does seem to be a kind
of lowest common denominator help system.  IMO NeXT lost their way when
they decided to port to windows and began to modify the API to blend in
with the native systems rather than to be good.

>   But in a
> native GNUstep environment, what?

I know I'm repeating myself ... but I'd like a help panel  similar to 
the NeXTstep one -

Fast, context sensitive, searchable, hypertext links, back/forward 
buttons,
an index of topics, hidden when the app is inactive.  The only thing 
I'd change really
would be to make it support xhtml rather than just rtfd.  Perhaps it 
could invoke an
external viewer application to follow links to remote systems.