Eclipse Community Forums
Forum Search:

Search      Help    Register    Login    Home
Home » Eclipse Projects » Platform - User Assistance (UA) » Format of Help contexts XML file
Format of Help contexts XML file [message #472378] Wed, 12 March 2008 20:47 Go to next message
Eric Rizzo is currently offline Eric RizzoFriend
Messages: 2366
Registered: July 2009
Senior Member
I've found that the Help system is very sensitive about the format of
the contexts XML file and I'd like to know if this is something that has
already been documented or discussed (before I go and enter a
bug/enhancement request).
The problems seem to only crop up when using custom Help context IDs in
TrayDialogs. If the <description> node is missing or empty, the tray
dialog help fails in various ways.

Example 1 - a contexts file that is missing <description> altogether
produces NPE when trying to open the Help tray.

Example 2 - a contexts file that has empty <description> nodes (as in
either <description /> or <description></description> ) causes the tray
help to respond with the built-in message that no help topics are
defined for the context ID.

It seems that both of these tend to violate the Principle of Least
Surprise or the Leniency Principle ("be lenient in what you accept and
strict in what you emit"). I mean, without the benefit of a DTD or
schema to dictate the format, is it unreasonable for the code to have a
little more leniency?

Eric
Re: Format of Help contexts XML file [message #472381 is a reply to message #472378] Fri, 14 March 2008 19:58 Go to previous message
Eclipse UserFriend
Originally posted by: nospam_kowalskilee.gmail.com

Hi Eric,

I'm going to leave the "should be more lenient" question for the Eclipse
UA team.

Looking at Bugzilla though, I'm not sure what is making the TrayDialogs
a special case.

Bug 197250 seems to indicate that a patch was done for all of the other
reported bugs related to missing or empty <description> and a fix for 3.3.1:
https://bugs.eclipse.org/bugs/show_bug.cgi?id=197250

I did a Bugzilla Eclipse/Platform/User Assistance query for "context"
and "description":
https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advan ced&short_desc_type=allwordssubstr&short_desc=contex t+description&classification=Eclipse&product=Platfor m&component=User+Assistance&long_desc_type=allwordss ubstr&long_desc=&bug_file_loc_type=allwordssubstr&am p;bug_file_loc=&status_whiteboard_type=allwordssubstr&am p;status_whiteboard=&keywords_type=allwords&keywords =&emailtype1=substring&email1=&emailtype2=substr ing&email2=&bugidtype=include&bug_id=&votes= &chfieldfrom=&chfieldto=Now&chfieldvalue=&cm dtype=doit&order=Reuse+same+sort+as+last+time&field0 -0-0=noop&type0-0-0=noop&value0-0-0=
(TinyURL is: http://tinyurl.com/2r3u3e)

There are 8 bugs found, but most seem to be duplicates and fixed by bug
197250.

Bug 92058 has the comments about <description> being spec'd optional. I
found the history interesting (maybe because it's Friday and I'm
prepping for EclipseCon and have UA on the brain).

Best regards,
Lee Anne


Eric Rizzo wrote:
> I've found that the Help system is very sensitive about the format of
> the contexts XML file and I'd like to know if this is something that has
> already been documented or discussed (before I go and enter a
> bug/enhancement request).
> The problems seem to only crop up when using custom Help context IDs in
> TrayDialogs. If the <description> node is missing or empty, the tray
> dialog help fails in various ways.
>
> Example 1 - a contexts file that is missing <description> altogether
> produces NPE when trying to open the Help tray.
>
> Example 2 - a contexts file that has empty <description> nodes (as in
> either <description /> or <description></description> ) causes the tray
> help to respond with the built-in message that no help topics are
> defined for the context ID.
>
> It seems that both of these tend to violate the Principle of Least
> Surprise or the Leniency Principle ("be lenient in what you accept and
> strict in what you emit"). I mean, without the benefit of a DTD or
> schema to dictate the format, is it unreasonable for the code to have a
> little more leniency?
>
> Eric
Re: Format of Help contexts XML file [message #610605 is a reply to message #472378] Fri, 14 March 2008 19:58 Go to previous message
Eclipse UserFriend
Originally posted by: nospam_kowalskilee.gmail.com

Hi Eric,

I'm going to leave the "should be more lenient" question for the Eclipse
UA team.

Looking at Bugzilla though, I'm not sure what is making the TrayDialogs
a special case.

Bug 197250 seems to indicate that a patch was done for all of the other
reported bugs related to missing or empty <description> and a fix for 3.3.1:
https://bugs.eclipse.org/bugs/show_bug.cgi?id=197250

I did a Bugzilla Eclipse/Platform/User Assistance query for "context"
and "description":
https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advan ced&short_desc_type=allwordssubstr&short_desc=contex t+description&classification=Eclipse&product=Platfor m&component=User+Assistance&long_desc_type=allwordss ubstr&long_desc=&bug_file_loc_type=allwordssubstr&am p;bug_file_loc=&status_whiteboard_type=allwordssubstr&am p;status_whiteboard=&keywords_type=allwords&keywords =&emailtype1=substring&email1=&emailtype2=substr ing&email2=&bugidtype=include&bug_id=&votes= &chfieldfrom=&chfieldto=Now&chfieldvalue=&cm dtype=doit&order=Reuse+same+sort+as+last+time&field0 -0-0=noop&type0-0-0=noop&value0-0-0=
(TinyURL is: http://tinyurl.com/2r3u3e)

There are 8 bugs found, but most seem to be duplicates and fixed by bug
197250.

Bug 92058 has the comments about <description> being spec'd optional. I
found the history interesting (maybe because it's Friday and I'm
prepping for EclipseCon and have UA on the brain).

Best regards,
Lee Anne


Eric Rizzo wrote:
> I've found that the Help system is very sensitive about the format of
> the contexts XML file and I'd like to know if this is something that has
> already been documented or discussed (before I go and enter a
> bug/enhancement request).
> The problems seem to only crop up when using custom Help context IDs in
> TrayDialogs. If the <description> node is missing or empty, the tray
> dialog help fails in various ways.
>
> Example 1 - a contexts file that is missing <description> altogether
> produces NPE when trying to open the Help tray.
>
> Example 2 - a contexts file that has empty <description> nodes (as in
> either <description /> or <description></description> ) causes the tray
> help to respond with the built-in message that no help topics are
> defined for the context ID.
>
> It seems that both of these tend to violate the Principle of Least
> Surprise or the Leniency Principle ("be lenient in what you accept and
> strict in what you emit"). I mean, without the benefit of a DTD or
> schema to dictate the format, is it unreasonable for the code to have a
> little more leniency?
>
> Eric
Previous Topic:Ctrl-C, Ctrl-V, or Ctrl-X doesn't work in swt widgets
Next Topic:eclipse 3.2 system help
Goto Forum:
  


Current Time: Wed Nov 26 03:23:03 GMT 2014

Powered by FUDForum. Page generated in 0.03139 seconds
.:: Contact :: Home ::.

Powered by: FUDforum 3.0.2.
Copyright ©2001-2010 FUDforum Bulletin Board Software