46226 - Context-sensitive Help (triggered by f1, help buttons in some dialogs) (PDT approved to checkin)

Status: VERIFIED FIXED

(SeaMonkey :: Help Documentation, enhancement, P3)

Description

[Ben Bucksch (:BenB)]

Implement infrastructure to provide context-sensitive help, i.e. allow app
developers to provide a away to access extended information about a certain
topic, e.g. via a "Help" button or clicking on labels in dialogs.

Implementation should be easy: Just create some simple chrome for the Help
window (if it doesn't already exist) and give a way to jump directly to a
certain topic, e.g. via |window.open("chrome://mypackage/myhelpfile.html#topic",
...)|. Or am I missing soemthing?

Taking bug for now, but helpwanted.

Comment 1

[Matthew T (active 1999-2002)]

Ian Oeschger has reportedly produced a simple Help window, CCing him.

Ideally, you'd have the following.

* A "title" attribute for XPToolkit widgets. (Usually, the value of the title
  attribute would be one or two entities taken from the DTD for that bit of
  interface.) The title would be shown as tooltips/balloons if `Show Help Tips'
  (on Windows and X) or `Show Balloons' (on Mac OS) was turned on in the `Help'
  menu.

* A button class="help" in XPToolkit, which would appear as a normal button on
  Windows and X (with the text `Help', if no text was specified), and as the
  normal Help button (question mark inside a circle) on Mac OS. (OS-specific
  positioning for it could be built in to dialogOverlay.xul or whatever it's
  called.)

* An easy way of making a Help button open the Help window at a given page of the
  local documentation (or even at a remote URL).

Comment 2

[Ben Bucksch (:BenB)]

Mattew,
- 1 works (see Prefs|Mailnews|Viewing|structs/smilies)
- this bug is about 3
- 2 is nice-to-have (app developer should certainly specify this class)

Comment 3

[Ben Bucksch (:BenB)]

Problem i ran into while trying to implement bug 52222:
- Commondialog doesn't allow for a help button. If make one of the (2) "custom"
buttons the help button (the solution I had to take), it will end up in the
middle between OK and Cancel on Win and Unix. Non-trivial to fix.
- No Help Window chrome. Trivial.
- Modality. If I specify "modal", the user can't access the original dialog
while the help window is open. If I don't specify "modal", the user can't access
the help window at all. Should we fix this? How? Will be extremely difficult to
fix.

Comment 4

[Matthew T (active 1999-2002)]

[Taking QA from the departed Eli.]

> - Commondialog doesn't allow for a help button.

Filed bug 52778.

> - No Help Window chrome. Trivial.

IIRC, Ian Oeschger had a minimal XUL help window working several months ago. Ask 
him.

> Modality. If I specify "modal", the user can't access the original dialog
> while the help window is open.

Help should never be modal. That's like a driving instructor making you stop the 
car every time he says something to you.

>                                If I don't specify "modal", the user can't
> access the help window at all.

Why not?

Comment 5

[Ben Bucksch (:BenB)]

> Filed bug 52778.

Tnx.

> IIRC, Ian Oeschger had a minimal XUL help window working several months ago.
> Ask him.

*ask*

> > If I don't specify "modal", the user can't access the help window at all.
> Why not?

Because the modal dailog opening the help window is still modal and obviously
blocks all other windows (unless a dependant window get modal, what I did).
Propably, there's no intrastructure for 2 top-level windows being accessible,
but at the same time blocking the rest.

OTOH, I just realised that the modality of teh askSendFormat is propably wrong
in the first place - it blocks all of Mozilla, which makes no sense. I don't
know, if that makes sense in *any* case. Need to investiagte.

Comment 6

[sairuh (rarely reading bugmail)]

spam: mass-moving currently open help bugs to Terri, who now does qa on 'em. :)

Comment 7

[verah (gone)]

Ben, Matthew: The problem of calling a Help window from modal dialog is a 
long-standing headache that no one has ever solved satisfactorily. Notice that 
if you open a control panel on a Windows machine, there's no Help button. 
There's a reason for that... Now click the F1 (help) key. You get a snippet of 
help that goes away as soon as you click the mouse or press a key.

I've been a designer and writer of online help for something like 10 years now, 
and I used to advocate Help buttons in dialogs. But I would not take this one 
on, for two reasons. (1) Many dialogs that are modal, shouldn't be. I'd solve 
that problem first. (2) The remaining dialogs that *should be* modal probably 
shouldn't have Help buttons -- instead, they should be designed and written in 
such a way as to be crystal clear.

I think we need to move beyond the notion of putting Help buttons in dialogs. 
Information on how to use an interface should be imbedded in the interface 
itself. The online help should simply be a set of questions users can ask about 
*tasks* -- not (for instance) "How do I use the Fonts preferences dialog?" -- 
that's not a real user task. Online help should concentrate on tasks like, "How 
do I change the font my browser uses to display web pages?  (Of course, this 
isn't a great example at the moment, since Fonts preferences isn't working.)

BTW, True context-sensitive online help isn't just a matter of bringing up a 
paragraph of information on (say) mail servers when the user clicks a Help 
button in the mail server preferences panel. To see true context sensitive help, 
you have to look at Apple Guide on the Mac OS. Apple Guide knows what hardware 
the user has, which windows are open, what steps the user has already followed 
(so the help system skips those steps), and so on. Too bad Apple didn't support 
Apple Guide.

BTW(2) You could say that the Mac OS satisfactorily solves the problem of 
opening a help window from a modal dialog. However, the people working on the 
machinery that gets the job done might not agree that what they must go through 
qualifies as "satisfactory."

Comment 8

[Ben Bucksch (:BenB)]

verah, thanks for that little "essay". Appreciated. I agree with much you said.

> 1) Many dialogs that are modal, shouldn't be. I'd solve that problem first

Completely agreed. IMO, this applies to almost all modal dialogs in Mozilla.
They just block the current *task* (e.g. the mail composer, if something during
Send goes wrong), not the whole app suite. Why should I be unable to browse or
read new mail, while I enter a subject for the mail I just tried to send
(accidently without a subject)?
The only really modal dialogs are fatal application errors, like low memory.

If the dialog is modal to the current task only, it is easy to opne a new
browser or help chrome window to display the help, and the user can switch
between both.

> I think we need to move beyond the notion of putting Help buttons in dialogs. 
> Information on how to use an interface should be imbedded in the interface 
> itself.

"move beyond" - crap alert ;) In fact, I don't buy that as-is.

Of course, Help buttons are a nice excuse for bad UI. But by trying to embed all
information into the UI, you easily overload it. This is especially true since
there are users with different levels of knowledge (and users quickly
"transform" into another group). A help text might be very useful the first  1
or 2 times, but after you saw it 100 times, it is distracting and this
counter-productive.

Extreme example: What do you do with user who doesn't know what a mail server,
or even a server, is?
Another example: While wizard are said to be helpful for new users (propably
because of the embedded extensive texts), the new account wizard in Mailnews is
bad UI for me. I have to do much more clicks than necessary (for all those Next
buttons), and it doesn't offer all options I need (most notably the "mail server
dir"), so I have to go to the account details anyway later, or Mailnews will try
to "download" all files in my home dir on the server, not just the mail folders.

So, I do think that Help buttons are good for background info or more extensive
help for newbies without harming more experienced users. Kind of "hyperlinking"
- more details on request.

> The online help should simply be a set of questions users can ask about 
> *tasks*

You are mixing up 2 types of help here. Context-sensitive help is destinctively
different from the help manual. They are not exclusive.

BTW: I don't know the MacOS (unfortunately, because I don't have a Mac
*machine*), so please describe anything important you reference.

Comment 9

[verah (gone)]

Ben, you are confused. Online help does *not* equal "the help manual." I'd 
suggest a "Help 101" course. And, when responding to people's comments, don't 
use the word "crap" -- it tends to end the conversation, which is (in any event) 
ending now.

Comment 10

[Ben Bucksch (:BenB)]

huh?

> don't use the word "crap"

I didn't mean to suggest that any part of your comment were crap. I'm sorry that
I gave this impression.

(Why do people always hop on the negative parts and oversee the postive ones,
like "appreciated"?)

> Online help does *not* equal "the help manual."

What did you mean with "Online help", then?

Comment 11

[Matthew T (active 1999-2002)]

I agree with everything Ben has has said here. Putting help text in the UI itself 
is just annoying, once the users become advanced enough to want to use that 
screen real estate for something else. And if it was possible in the real world 
to design any dialog to be `crystal clear' enough that no user ever needed help 
with it, then there would be no reason not to apply the same standard to the rest 
of the UI too -- in which case we wouldn't need user help at all.

Mac OS uses Help extensively in its modal dialogs, and there is nothing stopping 
Windows from doing so either. Why? Simple. The help viewer is a separate app (on 
the OS level), and as such is not affected by the app-modality of the dialog. 
Unfortunately XPToolkit doesn't allow for this -- yet. See bug 54356.

Comment 12

[Ben Bucksch (:BenB)]

> See bug 54356.

This is not really the right bug. A bug specific about changing the meaning of
"modal" would be better (see  one of my posts to .xpfe), and this bug could
depend on it. I might file it some time, if nobody else does earlier.

Comment 13

[Ben Bucksch (:BenB)]

Changing personal priorities. Giving away most of my bugs :-( (reassigning to
default owner).

I will still track these bugs closely. If you need my input, feel free to ask me.

New owner: Please do *not* close these bugs (as WONTFIX or whatever you may
find) unless they are fixed. Rather, reassign to <[e-mail]>, if you
don't want to work on them.

Comment 14

[Ian Oeschger (gone)]

Accepting bug. We are discussing and working on context-sensitive help.
Brian, cc'ing you on here for lack of a better [e-mail]. 

Comment 15

[Ian Oeschger (gone)]

taking this bug on c-s-help. See spec-in-progress at
www.mozilla.org/projects/help-viewer/cshelp_specification.html

Comment 16

[Ian Oeschger (gone)]

Adding dependency to 80745: new bug to track problems with chrome:// urls that
include targets (#) do not resolve correctly.

Comment 17

[Ian Oeschger (gone)]

Attachment: sample of some code to call context-sensitive help from pref.xul

Comment 18

[Ian Oeschger (gone)]

Note that the patch above is a sample. It will not work if you use it right now, because the function is uses to open Help, openHelp(URI), is not yet available in help.js

Comment 19

[Ian Oeschger (gone)]

Attachment: update to the patch above

Comment 20

[Ian Oeschger (gone)]

Attachment: update to help.js: openHelp() function to be called from cs help

Comment 21

[Ian Oeschger (gone)]

Context-sensitive help is in danger of not making it in! Help!

The last couple of patches I have submitted here (to pref.xul and to help.js, respectively) show the code I need to have reviewed and checked in on the UI side (pref.xul) and on the help side so we can load special content from a button. 

It's less elegant than we planned, it doesn't include selection in the TOC (b/c we don't have time to retool with XUL right now, without which we don't have the content model in the toc to get to with selection), and it's a little hacky on the preferences panel side (where there is no ready-made help button of the kind I suggested in 52278), but we really need to get something working right away.

Please, if you have some expertise on the UI side, if you can review or super-review this code (cc'd a couple extra likely candidates for this: blake? smfr? ben?), or if you can help out with some of the implementation stuff--like in the platform specific looks to the Help button, in the localization, or whatever--let me know so we can get _something_ going this week. Thanks.

In short, the patches here suggest that dialogs that want contextual help should: import the help.js script, put their own help button at the bottom, and call openHelp(chrome://help/content/help.xul?special_context), where "?special_context" is a key that you, me, or maybe a help author have put at the top of the help.js file and that will resolve to some particular HTML file.

I will post a document describing this in greater detail here.

Comment 22

[Ian Oeschger (gone)]

Attachment: brief explanation of proposed context-sensitive help system, such as it is

Comment 23

[Ian Oeschger (gone)]

OK. Talked this over with smfr some (thanks again, Simon!). The following patch
replaces the other ones. It's the uber-patch. Describes a new set of buttons
available from the dialogOverlay, "okCancelHelpButtons", which call "onHelp()"
back on the parent dialog, in this case pref.xul. In pref.xul, onHelp() figures
out which preferences panel is loaded and passes along a particular context to
openHelp(), which is defined in help.js and imported into the parent dialog
pref.xul.

I am proposing this as a general way to do context-sensitive help. The patch, if
accepted, would take care of this for pref.xul, where context-sensitive help
needs to be called for each pref panel.

Every other dialog that wants to use the Help button has to implement an
onHelp() in their own script. They can import chrome://help/content/help.js and
have their onHelp() pass context to the openHelp() function defined there.

I have only done the dialogOverlay for win. I need help with the other
platforms. Also need to finish the list of context "keys" in pref-help.js. Also
need a super review and an r=someone or two. Thanks a lot. -i.

Comment 24

[Ian Oeschger (gone)]

Attachment: patch for adding context-sensitive help and help buttons to dialog overlay

Comment 25

[Ben Goodger (use ben at mozilla dot org for email)]

Make sure to create a *Right variety, as most of our dialogs on windows and mac
at least have right-aligned buttons. Be careful when doing any dialog
conversions that dialogs that have right aligned buttons should have right
alined OK/Cancel buttons after your change ;) 

I agree with blake that we could do something in XBL, but that can come with my
scheduled <dialog/> work post 0.9.3. 

Comment 26

[Ian Oeschger (gone)]

Attachment: full patch for adding help button(s) to dialog overlays and cs-help to pref.xul

Comment 27

[Simon Fraser [no longer active]]

Attachment: Better patch for Mac platformDialogOverlay.xul

Comment 28

[Simon Fraser [no longer active]]

Attachment 37276 [details] [diff] provides a better patch for Mac, with left-aligned Help buttons 
like this:

 [Help]               [Cancel]  [OK]

Ian's last patch is missing an entity in platformDialogOverlay.dtd for Mac:

Index: mozilla/xpfe/global/resources/locale/en-US/mac/platformDialogOverlay.dtd
===================================================================
RCS file: /cvsroot/mozilla/xpfe/global/resources/locale/en-US/mac/
platformDialogOverlay.dtd,v
retrieving revision 1.2
diff -b -u -2 -r1.2 platformDialogOverlay.dtd
--- platformDialogOverlay.dtd	2000/02/12 03:33:38	1.2
+++ platformDialogOverlay.dtd	2001/06/06 00:01:30
@@ -4,4 +4,5 @@
 <!ENTITY okButton.label			"OK"> 
 <!ENTITY cancelButton.label		"Cancel"> 
+<!ENTITY helpButton.label		"Help"> 
 
 <!-- Key labels, for mousewheel prefs -->

Comment 29

[Ian Oeschger (gone)]

Attachment: second take: this one includes DTDs for all plats and replaces my earlier patch

Comment 30

[Simon Fraser [no longer active]]

r=sfraser

Comment 31

[Ian Oeschger (gone)]

Attachment: sorry. one more. This one combines my latest and simon's mac update. It is _the_ patch.

Comment 32

[Blake Ross]

It's possible that some of those unchecked parentNode's could throw warnings in 
some cases (unlikely).

Remove the deadly tabs, and sr=blake, with the assurance that this will be 
converted to xbl.

Comment 33

[Blake Ross]

Forgot to mention: align= is deprecated, should be using orient=

And won't opening a non-modal dialog from a modal one cause problems on some 
platforms (mac?)?

Comment 34

[Ian Oeschger (gone)]

Modality issue: in the help.js's openHelp() function, which is the way we'd like
people to open the help window from their dialogs, we replaced the ordinary
window.open(blah blah, dialog=no, blah) with Folger's Instant Crystals:
window.opener.open(blah blah, dialog=no, blah).

This makes the Help window non-modal to the browser window, so you can move back
and forth between help & preferences+browser, but preferences is still modal to
the browser. Still not very pretty. But this is as loose as we can get barring a
change to the modality of preferences. I'd like to see how this works on mac
(smfr? you there?) and whether this is something we ought to implement (if we
can get this checked in!)

Comment 35

[Simon Fraser [no longer active]]

I suspect that Mac may be unhappy trying to open a non-modal window in front of a 
modal one (help over prefs dialog). Maybe danm can reassure us? I'll test.

Comment 36

[Simon Fraser [no longer active]]

using window.opener.open() in the help.js kinda works OK on Mac. When you hit the 
Help button in prefs, the Help window opens in the front. But after clicking on 
the prefs dialog, it comes to the front, and you can no longer interact with the 
help window.

However, I think that using window.opener.open() is bad, because you cannot 
guarantee that you are always invoking help from a dialog; we might have help 
invoked from the menubar or a main window, so window.opener() would be null.

The help window also has issues; it has no menu bar, yet, on Mac, the top-level 
menus remain active (view source has the same issue). And it has no key 
shortcuts, so I can't close it with the keyboard.

Comment 37

[Ian Oeschger (gone)]

Well, can the r=smfr and sr=blake stick if I do?: 

if (window.opener)
 { 
    window.opener.open(blah blah); 
 } else { 
    window.open(blah blah); 
}?

The issues you mention, Simon, are issues about the Help window generally
(though I suppose they may be exacerbated by the layering of windows in
context-sensitive help). I believe there is a bug for them...hmmm can't find it
now. May be over on the bugscape side.

Comment 38

[Dan M]

(attempt to reassure sfraser; comment at 11:43) I can't check right now but modal 
in front of modal should work. We do it all over the @##%* place. Even nonmodal 
in front of modal should work (the nonmodal window is forced to be modal).

Comment 39

[Asa Dotzler [:asa]]

a= [e-mail] for checkin to the trunk.
(on behalf of drivers)

Comment 40

[Ian Oeschger (gone)]

context-sensitive help support was checked in yesterday afternoon (6/19). It
provides a help button in the preferences panel that loads appropriate content
in the help viewer...pretty much. 

I put a doHelpButton() function in pref-help.js (newly loaded in the pref.xul)
that calls openHelp() from help.js (now also loaded there).

I have some updates to the pref-help.js file where the "keys" to the content are
defined. The Advanced panels, some of the security panels, and the Smart
Browsing panel were not loading content. The patch for this follows.

Comment 41

[Ian Oeschger (gone)]

Attachment: additions to the panel-->help keys

Comment 42

[Ian Oeschger (gone)]

blake: if you get a sec...TIA

Comment 43

[Ian Oeschger (gone)]

These panel->key updates went in with content updates this afternoon. All or 
almost all of the items should be hooked up to help content, or else fail to the 
basic "Preferences Help" page.

Comment 44

[Ian Oeschger (gone)]

Attachment: patch for adding help buttons to os2 plat as well

Comment 45

[Asa Dotzler [:asa]]

we can't do this to os/2 a= [e-mail] for checkin to 0.9.2 branch pending
review.
(

Comment 46

[Christopher Blizzard (:blizzard)]

rs=blizzard

Comment 47

[Mike Kaply [:mkaply]]

r=mkaply on the OS/2 patch

Comment 48

[Ian Oeschger (gone)]

Marking FIXED. F1 feature to be added is tracked in 88739, the full
extensionalizing of the help system is in 89603, and various other bugs have the
rest. The context-sensitive help buttons exist in dozens of dialogs, are
available in the global overlay for use elsewhere, and the pesky modality issue
was resolved.

Comment 49

[Brant Gurganus]

v