Closed Bug 67376 Opened 24 years ago Closed 15 years ago

Tracking bug for help system for Mozilla

Categories

(SeaMonkey :: Help Documentation, defect)

Product:
SeaMonkey
Component:
Help Documentation
Type:
defect
Priority:
Not set
Severity:
normal

Tracking

(Not tracked)

Status:
RESOLVED FIXED

People

(Reporter: rudman, Assigned: neil)

References

Details

(Keywords: meta)

Attachments

(5 files, 3 obsolete files)

jag's updates to help.js/help.xul
161.48 KB, application/octet-stream
Details
backing out ns help (this + 'rm -Rf tpubs/ns6/helpchrome)
1.87 KB, patch
Details | Diff | Splinter Review
[example] mini-nav.xul
4.78 KB, patch
Details | Diff | Splinter Review
catch the help system trunk up to the branch
25.57 KB, patch
Details | Diff | Splinter Review
update per hewitt's suggestions.
229.11 KB, patch
Details | Diff | Splinter Review 
Checkin planned prior to M9.

This bug tracks the known issues for the Help system---general problems to solve
(prior to checkin).

1. Make HTML help content files part of the individual component installs
(affects RDF overlay items).
2. Need to build help.jar (and register it).
3. Set up commercial build so that it overwrites the mozilla help content.
4. Await XBLification of browser (dependency on what bug?).
5. Remove existing NS chrome.
[need to set target milestone andn keywords appropriately...working on that]
Priority: -- → P1
Accepting, adding dependency: I have a basic help viewer to check-in, but I am
waiting for the browser to be fully "XBL-ified" per bug 65412

Also adding samir to the cc: list because I believe he has offered some extra
help on the check-in and install process. Thanks, Samir :)
Status: NEW → ASSIGNED
Depends on: 65412
Note that you can do everything you need by using code like in navigator.js
instead of the code I sent you. Once I land 65412, you can optionally switch to
the new code, but the old code should still work...
jag: Thanks. Does that mean that <browser/> is alrady partially xbl-ified?:
  return getBrowser().webNavigation;

And is your landing bound to happen soon, or is it a maybe? You're just waiting
in the sr= queue, right?
Yeah, browser is already in xbl, but it's only got a couple of properties.

http://lxr.mozilla.org/seamonkey/source/xpfe/global/resources/content/xulBinding
s.xml#549
Yep, and those few are currently enough to get where Ian wants to go.

Ian: it could take a while actually... It's in hyatt's "comments" queue, after
which I'll probably have to do some rewriting, then get r= and sr=. I wouldn't
wait for it.
I can't really diff-n-show this, but I need approval on the following "first
stage" of getting the help into Mozilla. Ben, I thought you might give me the
word on this or point me to someone else who should:

* cvs remove ns/tpubs/ns6/helpchrome/jar.mn, makefiles, & helpchrome/*
* remove link(s) to help window in ns help menu
* add a directory: src/mozilla/xpfe/components/help
* add the non-building help chrome in there: help.xul, help.js,
helpMenuOverlay.xul, etc.

	
This is so that the help will eventually be built as help.jar, a peer of
comm.jar in the chrome directory (this in contrast to the commercial version,
which was put in comm.jar).
cc:ing asa, removing dependency, and going ahead with partially-xbl-ified
browser widget per jag's suggestion.
No longer depends on: 65412
I'm having some trouble getting the webNavigation interface through XBL. This
snippet in my help.js code, used on the back button, returns something like
"getWebNavigation has no properties":

// <browser id="help-content" ... />
function getBrowser()
{
  return document.getElementById("help-content");
}

function getWebNavigation()
{
  try {
    return getBrowser().webNavigation;
  } catch (e) {
    return null;
  }
}

function BrowserBack()
{
  getWebNavigation().goBack();
  // UpdateBackForwardButtons();
}
Weird...can you e-mail me the relevant js/xul?
You loathe me, Ben. I can see that now.
Who else can approve the addition of these files (see comment on 2/6/01) to the
mozilla source? The equally intractable hyatt? Jag, can you sr= this in?

The presence of a help.jar at the root chrome level (with comm.jar, en-US.jar,
etc.) is not a small deal. And I need to get going.
Changing product to Browser for better tracking.
Component: User → Help
Product: Documentation → Browser
Target Milestone: --- → mozilla0.9
Version: unspecified → other
Keywords: nsbeta1
QA Contact: rudman → tpreston
Changing to Terri Preston for QA contact.

Adding Sean Cotter to cc list.

Adding nsbeta1 keyword. Note previous settting of m0.9 milestone.
cc'ing leaf in here: I think I am going with the help-as-extension plan. Leaf,
what do I have to do to register mozilla/extensions/help as an extension that
gets built? I see MOZ_EXTENSIONS is populated with a short list of dirs under
extensions/ in autocongif.mk, but I don't know how it gets there and what else
might need to be done. Thanks.

Thanks, too, jag for the work on the <browser>-using help.js.
?: r=leaf, sr=alecf just for the following passive, non-building additions to
src/mozilla/extensions?:

mkdir help
mkdir help/resources
mkdir help/resources/content
mkdir help/resources/locale
mkdir help/resources/locale/en-US

cp (help.xul, help.js, helpMenuOverlay.xul, contents.rdf) help/resources/content
cp (all HTML content, help-toc.rdf, images subdirectory) help/resources/locale/en-US

cvs add all
cvs commit all

These are just the basic chrome and content files, no makefiles and no jar.mn.
I'd like to get the stuff into the source so we can get the chrome updates in
(e.g., jag's xbl browser fixes) and so I can get some help on making it an
extension and getting it registered as a package (e.g., browser.jst,
packages-plat, jar.mn). Thanks.

yep, sounds like that's the right place for additions, ian. I think everyone 
agrees that having this on by default makes sense, and i can help make that so 
on unix/windows for you, but will need mac help.
Just checked in the basic (non-building) help stuff at
mozilla/extensions/help/resources. Still need an r= and some hand-holding on the
ns remove (see 2/15 attachment) 
This is a DUP of bug 16097.

Ian O., please announce this bug on the .documentation newsgroup.


How do we want to organize the help files?

It should be possible to deselect the docs for any component individually, since
the docs can be pretty large and I might have different knowledge of the
components/applications in the suite.

Should it be <chrome://component/help/bla> or <chrome://help/component/bla>? I
favor the former.
(cc'ing jatin, new writer for ns.)
Ben: What do you say we call this the main bug and let the other one--which
implied that we needed to *begin* talking about a Mozilla help strategy--slip
away. And thanks for the suggestion: I will post a mesage to the n.p.m.docs (I
thought I did, but I'm out of it :(  ), and then let's talk about these issues.

Great points already, Ben, and things I am thinking about. As for the
chrome/location, I am shooting for chrome://help (sic!) and a jar at the chrome
level called help.jar. In fact, this is what I made available in a provisional
way in that help.xpi install I sent around a little while ago. 
Ian O.: Note: I was speaking about the help *contents*, not the help system /
viewer.
*** Bug 16097 has been marked as a duplicate of this bug. ***
Eureka! With Andrew W's help, I was able to 1) put together a great way to pass
context to the window from other parts of the UI and 2) get the right part of
the toc tree selected. I will check these changes into the files in
extensions/help and update the specs on the project page shortly, but in brief:

1) toOpenWindowByType(), the single-instance window opener defined in
tasksOverlay.js that I have been using to make sure we only have a single help
window open ( windowtype=mozilla:help) at any one time, now takes a chrome url
that includes a special key at the end. For example, the url
"chrome://help/content/help.xul?mail" includes a cgi-like "search" snippet at
the end that can be retrieved with window.location.search. In the help.js, I
have a JS object with members like this
var key {
 "?mail": "chrome://help/locale/mail_help.html",
 ...
}

so that the help init can do this:

if (window.location.search) {
 _Help_LoadContent(key[window.location.search]);
} else {
 _Help_Home();
}

This will load the mail help using the special "?mail" key at the end of the
chrome url. (Note that Mozilla appears not to strip off the leading "?" on the
search string. Is this a bug?)

2) Got selection working in the tree so that when a particular HTML document is
loaded in the content subframe, the appropriate part of the toc tree will be
selected:

function _Help_TreeSelect(link_attr) {
 var items = document.getElementsByAttribute("helplink", link_attr);
 var parentRow = items[0].parentNode;
 var selectableNode = parentRow.parentNode; // helplink is an attribute
 // on a treecell, which cannot be selected
 var tree = document.getElementById("help-toc-tree");
 tree.selectItem(selectableNode);
}

Call this function (e.g., in the init function above) with the key that
corresponds to the content you want, and the viewer loads with the right part of
the tree selected.

 
Ian, will the Help Viewer be handling external http:// links or will they 
open/be sent to a browser window?
It'll handle local and remote http. I think NS plans on doing served release
notes in the Help window.

BTW, just checked in the basic prototype for doing context sensitivity in
helpMenuOverlay.xul (where there's a context-passing menuitem) and the updated
help.js, which includes a couple of keys at the top.

these are are mozilla/extensions/help/resources/content/
Spec updated as well
Does this bug depend on bug 46226?
As this bug is a catch-all, and the new system is designed for (or at least
allows) context-sensitivity, I don't think there is any dependency on bug 46226.
Ian (or anyone else), unless you think otherwise, I'd mark 46226 as a dupe of
this one.
I'm just wondering, Ian, how help for commercial-only components is going to be 
done. Is there some plan for this, or are those components going to go out 
without help docs?
We are going to use the chrome built from Mozilla and then destrutively
overwrite just the HTML content and the RDF table of contents in the help.jar
when we do the ns build. Shouldn't require any new chrome or structure, just
additions to the content...And maybe UI where those new components want to call
context-sensitive help.

for the makefile.win change, you'll need to truncate the line previous to the 
one you're removing, or substitute $(NULL) for the line you're removing 
(trailing \, i thought, were bad for nmake). Other than that, r=leaf for the 
build changes.
Got a not quite complete help.dtd into the help src this morning, posted a new
doc at the projects page about how to use context-sensitivity
(www.mozilla.org/projects/help-viewer/client_howto.html), and made a somewhat
formal request for a code review of the stuff in src now so we can get it
building ASAP
Ian, have you thought yet about how you are goign to handle the monitoring of 
the Back/Forward UI widgets.  In navigator.xul/.js, it uses broadcasters 
(canGoBack/canGoForward).  There is an 'nsXULBrowserWindow' with a function 
onLocation which calls the function UpdateBackForwardButtons() that handles the 
observers.
It would be nice if there was a way of doing this without duplicating the whole 
nsXULBrowserWindow class, and attaching an instance of it to 
window.XULBrowserWindow.

I don't quite undertand yet how it fully works but it seems the above steps are 
needed to get full back/forward functionality
kinger: jag will correct me if I'm wrong, but I think that one of the boons of
having an xbl-ified <browser /> is that you can get .canGoBack and .canGoForward
any time you want and not having to worry about managing the session history
yourself. Though as you noted I haven't hooked it all the way up yet, we ought
to be able to manage navigation and history with:
goBack, goForward, canGoBack, and canGoForward.

note also that I have eschewed the button states (disabled when there is no
history, enabled when there is). This is another update we'll have to make.

Well, I'm not sure about the session history object management. Personally I
think it would be nice if the xbl-ified browser would take care of it for you,
but there's a movement going to delay loading as many dlls as possible till
after the window shows. I haven't thought of a way yet to get the binding to do
this (other than adding an init method and explicitly calling that on a timer
started from onload).

Anyway, I'm attaching a mini-nav.xul, which is a very simplified version of our
browser. It uses a JS Object implementing nsIWebProgressListener to act as glue
between the docloader and the browser UI. Have fun :-)
jag: 
Just fixed (in my local build) the help.css for the modern.jar "refactoring". Checking this in shortly. But now, with the nav buttons present again, I get: 

JavaScript error:
 line 0: uncaught exception: [Exception... "Component returned failure code: 0x8
0004005 (NS_ERROR_FAILURE) [nsIWebNavigation.canGoBack]"  nsresult: "0x80004005
(NS_ERROR_FAILURE)"  location: "JS frame :: chrome://help/content/help.js :: goB
ack :: line 71"  data: no]

Like it's not seeing the canGoBack property on webNavigation. 
This looks related to the error I showed you with loadURI().
And as I mentioned in IRC a moment ago,
the toOpenWindowByType() from tasksOverlay is supposed to get the window-mediator datasource, but it doesn't look like it does so successfully right now. So I've had to use:

<menuitem label="Help Direct" 
  	oncommand="window.open('chrome://help/content/help.xul', '_blank', 'chrome,menubar,toolbar,resizable,scrollbars');" />   
  
But then I lose the single-instance-ing of that previous function. Do you know anything about this latter? Please advise.

-ian 


General status on help window  03/27/00: 
sr=ben, r=hyatt on chrome yesterday, but having some trouble this morning with regressions (?), webNavigation stuff, and maybe with the window-opening function in the Help menu itself, which tries to get a window-mediator datasource and is failing (?) to do so. Working with jag on these problems--n'est-ce pas, jag?

Have updates to help.css per hewitt's modern re-org to check in. Working on help build/installer tomorrow with samir's oversight, at which point we'll get, I hope, an sr=dveditz, r=samir on the install piece, and check the viewer in this week.


jag, Just wanted to let you know that I think the trouble I was having displayin
the help viewer has something to do with my calling menu item being in an
overlay rather than with any regressive trouble with the window-mediator.
Prassanna suggested using a construction like xmlterm does (also an extension,
also using an overlay into the browser menus), where the toOpenWindowByType()
function is wrapped by something in the overlay itself:

<script>
function toHelpWindow(uri){
  toOpenWindowByType('mozilla:help', uri);
}
</script>

Not sure why exactly this would improve things, but I am working on it now.
Ian: so I've got a hacked up <helpbrowser/> which supports tooltips on its
content. That's what you wanted, right? Or did you want tooltips on the chrome?
jag: content tooltips is what I was thinking of. Great! I am moments away from checking the help build stuff in (see 74132), after which point I guess you can update the XUL (and the JS, you said) to use the new widget.


what needs to be done here?  
no more features for 0.9 , moving to 0.9.1
of the work is done lets mark this ond fixed
and put back on the 0.9 radar to make sure it gets
tested...

thanks
Target Milestone: mozilla0.9 → mozilla0.9.1
*** Bug 76124 has been marked as a duplicate of this bug. ***
Status Report (to answer chofmann's question):

Help is in mozilla, built as a default extension
Netscape packaging has been updated so it builds there too
Issues:
  skin needs work: "Home" button and other cleanup
  linux installer builds still don't have help extension
  keys (ctrl + w) and broadcasters need to be hooked up
  html index needs to be done (have scripts for this)
  html content needs to be managed in commercial tree separately
  jag has <help_browser /> ready to be reviewed and checked in
  context-sensitive help buttons need to be done in the UI per spec

I will write separate bugs for these issues and string them on to this one.
There are others too, I'm sure.
Depends on: 76935
Depends on: 76948
moving tracking bugs off the 0.9.1 radar.  if there
are key blockers in the help system for 0.9.1 or
betas that come off that milestone lets get 'em on
the list.   thanks
Target Milestone: mozilla0.9.1 → ---
Blocks: 80879
*** Bug 80879 has been marked as a duplicate of this bug. ***
Adding dependency to bug 81991, in which I describe some pesky context-sensitive
and toc-selection problems I have been having. Help!
Depends on: 81991
Adding the context-sensitive help bug as a dependency. Tracking some 
problems/imminent check-ins there.
Depends on: 46226
Adding but to sanitize Help system
Depends on: 46917
Adding new bug for a help system search engine
Depends on: 83862
Depends on: 79212
Blake - I don't think the trunk ever got the fruits of our last minute labor.
Previous patch catches the trunk up, I think. You want to take a quick look.
walk84: maybe you can give it an r= too? It resolves, among many other things,
the 89754 bug you just reopened.
sr=blake
r=walk84
Updates checked into trunk.
Blocks: 104166
I just posted a proposal for some big updates to the help system at
www.mozilla.org/projects/help-viewer/proposal.html. Author: Pete Wilson. Also
going to update that project index page when I get a minute, since it's like a
million years old now.

The proposal discusses some better uses of RDF in the toc/index/search; better
searching; a better doc format (like DocBook, which has been discussed as a Big
Possibility for mozilla.org for that same million years) that we could deploy as
printed manuals, as more modular, component-specific help documents, aural help,
what have you; some updates to the navigation in the viewer, et cetera. A lot of
things.

I like many of Peter's suggestions and the document itself (except for the user
of the verb "liase", blech! ;^), especially the set of recommendations at the
end, which I think we can get to work on. Or at least put on the table. 

I think Dr. Wilson and I are going to hang out on Friday at the mozilla
developers thing in Mountain View. Maybe we could have a little doc/help BOF.
Let me know if you are interested. 



Which reminds me: what's going on with <wizard/> or with <dialog
help="[url]"../>? Anybody know? 
Just an FYI for folks.  The next version of Komodo (1.2, currently in beta) has 
search for on-line help, based in part on a public-domain indexer which was 
written in Python.  See 
http://www-106.ibm.com/developerworks/linux/library/l-pyind.html?dwzone=linux 
for details.

It works ok for us.  It's not as high-power as some, but it delivers basic 
search functionality.

Our code is all in Python, which isn't a realistic solution for Mozilla (yet!), 
but there may be open source C++ indexers that could be used instead.  Note 
that I haven't modified it to work with documents in chrome.  It currently 
indexes 'real' files only.
Attached patch big updates to the help system (obsolete) — — Splinter Review 
peter wilson's handiwork on the help system. this patch includes sidebar-like
panels, a search facility, and a much more prolific use of RDF: the index is in
RDF (but I still have to update my script to write to RDF/XML, so currently the
index is pretty bare), the table of contents is composed from module specific
files (e.g., composer-toc.rdf), the context-sensitive help has been cleaned up
and now uses RDF URIs instead of keys or pointers to the HTML itself; also, the
help window now loads a "master file" that describes which panels are
available, which sets of content, and which databases to search against
(mozillahelp.rdf is loaded by default). Also some bug fixes for selection and
initialization.

This patch prepares the help system to be used, for example, by other
applications (think myapphelp.rdf) or for specific installations of
mozilla--like ones where there is no mail component or whatever. The
context-setting stuff has been greatly optimized.

Also there are some test files in the build so you can see the different master
instances of the help system running and test context-sensitive help. I will be
updating the specs at mozilla.org/projects/help-viewer to reflect this stuff
that I hope will be checked in (after a little more cleanup) some time very
soon.
Depends on: 117567
Updated version.
Attachment #65097 - Attachment is obsolete: true
Joe Hewitt, Blake
You think you guys could take a look at this patch and r/sr it if it looks good?
It's a nice update for the help system that lets you include different content
for different instances, uses RDF URIs for the context-sensitive help, and fixes
a bunch of bugs. Thanks in advance.

Note that the patch I posted here fixes or moot-ifies the following bugs,
mutatis mutandis: 91207, 93216, 93312, 104895, 114055, 83862, 108695 and maybe
others.
Comment on attachment 65246 [details] [diff] [review]
slightly updated: added the test.xul file, cleaned out some noise

nifty, r= or sr=waterson, whichever helps.
Attachment #65246 - Flags: superreview+
The only thing that I'd be worried about is the GetDataSourceBlocking calls.
These should be fine so long as the data is local (which it probably always will
be).
I love Chris Waterson. And not just because he r/sr'd this big patch. The RDF
against which the calls are being made is local.

Hewitt, perhaps you can take a look and give the complementary sr/r? Thanks a lot.

I love Chris Waterson too. He's a good guy.  But his tendency to hate non-
English speaking cultures really gets on my nerves.  All of the English text 
needs to be localizable.

Also, align="baseline" doesn't mean anything.

And please fix the indentation/tabs.
I love Chris Waterson too, even though I never met him. I just hope his ego is
not getting too big because of this bug.
Anyway, the patch looks great Ian, but I'm not sure if my opinion counts here.
Just one thing. In help.xul why are the forward and back menu popups in a
popupset with an id of "aTooltip". Isn't this reserved for tooltips?
<popupset> is deprecated, you can put your context menu popups all by themselves.

<popup> is deprecated, use menupopup instead.

tooltip="aTooltip" - you don't need this anymore, just go with tooltiptext.  if
there is an actual aTooltip element in your doc, just remove it.

<box orient="horizontal"  flex="0"> - how about just <hbox>
Attached patch update to Big Patch (obsolete) — — Splinter Review 
Another update to mull over. This one has localized strings in the XUL, tabs
and DOS line-endings removed in all files, a new generated RDF index, and
better formatting in general.
Attachment #65246 - Attachment is obsolete: true
* popup->menupopup
* menupopups not within popupset anymore
* tooltip attributes out
* <box/> in test.xul changed to <hbox/>
Attachment #66398 - Attachment is obsolete: true
Hey, did you guys generate the RDF/XML from the help text using a tool? If so,
it'd be great if you could check that tool into the tree somewhere. Also, I
think blake may have been referring to the ``hard-coded'' text in the RDF/XML:
blake, was that what you'd wanted to see as entities?
I talked with Blake about this, and I think he was referring to the XUL, where I
had some English. AFAIAC, the RDF/XML is fine full of English. Like HTML, an RDF
file in the locale/en-US subdirectory should be *replaced* by a localized
version in a different language pack.
K, so I've done the updates that blake and hewitt mentioned in their reviews.
Does this mean I can have an r=blake or an r=hewitt now (see latest patch)? Or
do I have to do something sneaky and say this work is sr=waterson, r=oesdchger,
and author=pwilson, which in fact is the case, in order to get it in in the next
couple of days?
Please Help!

mozilla builders and interested interlocutors, please apply this patch if you
can and verify that this help system update works on your platform in at least a
rudimentary way: that the datasources load in the panels, that the panels
display correctly, that the start content loads, that the navigation buttons
work. I am
confident that these changes work and are good, but I need some more
eyeballs.

We are beginning some usability studies on the help system, and I need
to have this stuff checked in by tomorrow night. Thanks for your
attention.
Depends on: 124273
Moving back to this bug to track help issues, e.g, regular expressions for
searching, maybe a full-text search facility, setting focus on the search field,
removing dependencies and building help as an optional extension...
Depends on: 89603, 130346, 134392
Depends on: 88739, 91876, 115861, 122693, 130733, 134076
Depends on: 135607
Depends on: 122806
Depends on: 117569
Depends on: 188160
No longer depends on: 134392
Keywords: meta
Depends on: 134392
Is there a reason for this bug to still be open.  Help has its own component so
I don't see the purpose of a Help tracking bug unless it tracks bugs external to
the Help component.
Can we keep this open for now? It's been useful in the past as a way to track
things (sometimes outside of Help), and I think I smell it becoming useful again.
Yes, I agree, let's keep it open. Brant: I think you misunderstand the meaning
of a tracking bug. As you can see from the 'depends on' list, there are still
many open bugs on the Help component.
Now that the new roadmap has been announced, has there been in thought put into
how the help systems for Phoenix and Minotaur (Thunderbird).  Would it be some
sort of standalone app that the both could reference, or will it duplicated in
both programs. 
moving stuff over to an outside-the-firewall email for the time being, looking
for people to pick these Help and doc bugs up for me.
Assignee: oeschger → oeschger
Status: ASSIGNED → NEW
mass reassign of all of Ian Oeschger's bugs to me (R.J. Keller).
Assignee: oeschger → rlk
> Now that the new roadmap has been announced, has there been in thought put into
> how the help systems for Phoenix and Minotaur (Thunderbird).  Would it be some
> sort of standalone app that the both could reference, or will it duplicated in
> both programs. 

http://firebirdhelp.mozdev.org

This is the future of Mozilla Help. It's planned on being the same app in both
programs but with different documentation.
QA Contact: tpreston → stolenclover
Depends on: 218878, 220561
Moving to new Help component owner.
Assignee: rlk → neil.parkwaycc.co.uk
Product: Browser → Seamonkey
Priority: P1 → --
Closing this tracking bug. We are now using the toolkit help viewer on trunk. Any new issues should be filed in the relevant toolkit component.
Status: NEW → RESOLVED
Closed: 15 years ago
Resolution: --- → FIXED
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Creator:
Created:
Updated:
Size: