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.

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

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)

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.

[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?

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

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

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

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.

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.

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?

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.

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

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 <nobody@mozilla.org>, if you don't want to work on them.

Accepting bug. We are discussing and working on context-sensitive help. Brian, cc'ing you on here for lack of a better name@ActiveState.com.

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

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

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

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.

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.

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.

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

r=sfraser

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.

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

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

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.

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.

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.

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

a= asa@mozilla.org for checkin to the trunk. (on behalf of drivers)

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.

blake: if you get a sec...TIA

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.

we can't do this to os/2 a= asa@mozilla.org for checkin to 0.9.2 branch pending review. (

rs=blizzard

r=mkaply on the OS/2 patch

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.

v