This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.

Bug 155275 - Help viewer update umbrella
Summary: Help viewer update umbrella
Status: NEW
Alias: None
Product: platform
Classification: Unclassified
Component: Help System (show other bugs)
Version: 6.x
Hardware: All All
: P3 blocker with 1 vote (vote)
Assignee: Jaroslav Havlin
URL:
Keywords: UMBRELLA, USABILITY
Depends on:
Blocks:
 
Reported: 2008-12-11 20:39 UTC by _ wadechandler
Modified: 2011-09-01 16:05 UTC (History)
5 users (show)

See Also:
Issue Type: ENHANCEMENT
Exception Reporter:


Attachments
Bad link fomatting (8.53 KB, image/png)
2008-12-11 22:01 UTC, timdudgeon
Details

Note You need to log in before you can comment on or make changes to this bug.
Description _ wadechandler 2008-12-11 20:39:22 UTC
I have been meaning to file something like this for some time, and some recent nbusers questions has pushed me to get it
done. The NB help system needs some updates to make it more usable. Some of the issues right off that would have a good
impact to me are:

1) Not show a number beside search entries unless they have meaning and are usable, and if they have meaning, then users
needs to know what that is. Perhaps some tooltips or something. Nobody knows what they mean when using the help system.
2) A user should be able to right click on the help view and have some options:
   a) select in contents (which either highlights the document or its parent if it has no node in contents) Yes, done
already through search, but this can make it more obvious.
   b) make sure when a search item is clicked it is highlighted in contents, currently this doesn't always happen, and
painting isn't consistent in the content view after going to the tab after having done so. If there is no Node for
contents then at least choose an acceptable parent document or chapter or something.
   c) search/find within help view text
   d) next - go to the next page in the help system after the one you are on and show it in contents..highlight the node
and display the tab keeping any search results there if there are any in the search tab.
   e) previous - opposite of next
3) In the top of the window there are back and forward buttons which work like a web browser, and that is good, but too
there need to be buttons which take care of 2d and 2e. This allows the user to easily navigate through chapters and read
the help system documents.
4) In contents and in the search results, on the Nodes and list, a user should be able to type in quick search like they
are in other parts of the IDE and find things in the list or tree faster

Any other things can be added later. Obviously there will be sub-issues as this is an umbrella, so those will need to be
created at some point, and linked in if they already exist or as they are created.
Comment 1 _ tboudreau 2008-12-11 21:01:45 UTC
Most of this will sort of end up under the umbrella of JavaHelp enhancements.  Personally, I wouldn't mind seeing us
move away from using JavaHelp, as it's appearance is a bit long in the tooth and something browser based would probably
work just as well.
Comment 2 _ wadechandler 2008-12-11 21:06:59 UTC
What do you mean by browser based? A help system in the browser? Do you envision it having panels, search etc? That
wouldn't seem very integrated though. I know from an RCP perspective folks really wouldn't like that; I wouldn't. Too, I
think with the browser bits you wind up having a bunch of pieces such as some kind of an embedded server or applets or
something to perform the search and retrieval bits. How do you envision this all working and being integrated?
Comment 3 timdudgeon 2008-12-11 21:59:56 UTC
So, assuming this a feee-for-all on current JavaHelp, one things the really bugs me about the current JavaHelp based
implementationis handling external links.
Links with a relative URL to a document within the help system work fine.
But as soon as you need to link to external links and open that in external browser there is no good way of doing this.
<object classid='java:org.netbeans.modules.javahelp.BrowserDisplayer'> tags allow this, but the formatting is horrible
(links appear with high base line, and if used in line with other text cause huge formatting problems). I will attach
screenshot with example.
Surely a more HTML friendly approach is called for.
Comment 4 timdudgeon 2008-12-11 22:01:05 UTC
Created attachment 74870 [details]
Bad link fomatting
Comment 5 _ tboudreau 2008-12-11 22:34:49 UTC
Cc'ing Jesse since he's had an interest in the past, and Patrick because a doc-writers perspective on this is very
important.

Personally my main objections with JavaHelp are just that the viewer is ugly, has "border build up" problems and
generally looks like something a Windows 3.1 programmer would love, so it's kind of an embarrassment from the UI
perspective.  It is, for whatever it's worth, controlled by a set of UI delegates just as regular Swing components are,
so some of that could be done from the NB side if anybody deemed it worth doing and wanted to maintain the result in
perpetuity or get it into the JavaHelp source tree (a scary place - I projectized it for the OpenJDK launch).
Comment 6 nickbeare 2008-12-12 10:02:50 UTC
Thanks for filing this Wade. The help system has bugged me for a while (I put it down to me being a dumb user) and I 
have often resorted to Google search in preference, so perhaps the browser based solution would be appropriate 
(although it would be useful if it could be (optionally) available off-line).
Incidentally, the number relates to the number of matches in the corresponding document-nothing to do with 
chapter/book, etc (the more matches, the higher up the pecking order).
Comment 7 Alexei Mokeev 2008-12-12 12:06:54 UTC
Current Help Window UI looks 'outdated'. And we either should get rid of JavaHelp or invest much in changing its UI in
order to have some improvement.

One of major problems with current HelpSystem is search/sort algorithm: it just looking on number of matches and this
may not correlate with the real article subject.
There is an intention to change this for 7.0 (#155111) by providing tags for help topics and ranking them higher.

Comment 8 Alexei Mokeev 2008-12-12 12:24:07 UTC
Browser solution looks interesting and questionable as well ;). What do you think about these 2 aspects:

1. Reliable solution to provide content to the browser while user is not on internet. This should not be sensitive to
user network/loopback/fw configuration

2. Browser control from IDE. Obvious approach is 'open' and 'forget'. Could this be better ?
Comment 9 vieiro 2008-12-12 12:41:47 UTC
I learned today that JavaHelp has intermitent severe problems in Solaris:

Javahelp bug report
https://javahelp.dev.java.net/issues/show_bug.cgi?id=22

NB Related issue (P1, WONTFIX)
http://www.netbeans.org/issues/show_bug.cgi?id=127368

The end result is that some solaris users won't be able to open the help window.

So maybe an HTML based alternative is a good idea. The IDE has a built-in HTTP server (used for javadoc help) that could
probably be used to render JavaHelp HTML. 

I wonder if using this internal web server could solve the internal-external link problem you're talking about.

Comment 10 _ wadechandler 2008-12-12 15:01:48 UTC
The problem I have with this idea is getting rid of the help system when NB isn't just an IDE. It is an application
framework which an IDE is built atop. Seems a better idea would be to take the sources for JavaHelp, and make a version
for NB where patches could be ported to the openjdk after things are made better. Then it can help everyone. If folks
need to run other media or do things from their RCP applications help they can use a link to kick off an external
browser. Sure, a browser solution which could work like MSDN would be good for NB things at large for folks to browse
through, but I don't find that an alternative. It doesn't integrate, and it doesn't look the same. To me that would be
another feature. Too, maybe it shouts more that a web component, a real one, is needed for Java, but that is another
story unless part of taking JavaHelp and improving it to give back is a sub-project to make a real HTML/browser
component that actually follows standards. FireFox is open source after all.
Comment 11 Jesse Glick 2008-12-12 17:32:28 UTC
JavaHelp bug #22 does not seem to be Solaris-specific. The exceptions report page lists all different OSs.

JavaHelp is not part of OpenJDK. It is an independent project.
Comment 12 _ wadechandler 2008-12-12 18:23:54 UTC
>JavaHelp is not part of OpenJDK. It is an independent project.

Even better :-D Seems that would make it easier to get just a branch of that code, a released branch, add some fixes,
send the patches, and use the patched release in NB. Of course I guess some of it can go back to having a better web
component for Java so other things such as Flash etc can be embedded maybe. I don't know, but it seems most of the
things in this umbrella could be fixed right in JavaHelp without a full blown rewrite, and if someone needs, a port of
Firefox/Gecko to Java could be a hole other thing in and of itself for a better future of working with HTML in Java. Not
saying that will be a cake walk, just saying it is a workable path.
Comment 13 Alexei Mokeev 2009-03-05 13:57:44 UTC
Moving JH issues to Victor.