[news.eclipse.platform.rcp] Re: Need help with the eclipse standalone he

[Lee Anne <nospam_kowalskilee@xxxxxxxxx>]

Hi Jenny,

Thanks for explaining more. In this case that you described:
a. You put the same href in two different toc files.
b. The help window shows the right page and opens the tree at the right 
position.
c. The HTML path that's in the top of the HTML is wrong.

Do you mean that the HTML path is not showing the right order of titles 
for one of the hrefs, while it does show the right order for the other?

That HTML path is sometimes called a "bread crumb trail" or "bread 
crumbs". It was added in 3.3 under this Bugzilla entry:
https://bugs.eclipse.org/bugs/show_bug.cgi?id=166391

If you read comment #7 and comment #8 at that Bugzilla URL, you'll see 
metioned "non-unique hrefs". That is the situation that you have: two 
hrefs that are not unique.

In comment #8, it states that the Eclipse team recommends avoiding that 
type of duplication in the table of contents, because it leads to this 
problem with the bread crumbs and trying to fix it in the code seems to 
be extremely difficult to do:
https://bugs.eclipse.org/bugs/show_bug.cgi?id=166391#c8

Two suggestions to work around this situation are:
1. If you think your users won't care about the bread crumbs (HTML path) 
in the help page, you can disable them. In Eclipse 3.4, there is a help 
preference to disable them from appearing.

2. If you want to keep the bread crumb path, the suggestion in comment 
#8 is to use the "include" capability of the help system, and have 
something like a wrapper topic file for the second, unique, href, and 
then include the text from the first topic file into the second file.

With suggestion 2, you'd have an extra HTML file for the second instance 
of the topic, but you wouldn't have to duplicate all of the text. That 
file would use the <include> mechanism to get the text from the first file.

Includes are described in this page of the Eclipse help system:
http://help.eclipse.org/stable/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/ua_dynamic_includes.htm

Best regards,
Lee Anne

Jenny wrote:
> Hi Lee Anne,
>
> I try to explain it ;)
>
> to keep my programm small and easy to update, I would like to avoid 
> duplicated html-help-pages and use linking instead. To do that, I put 
> the same href in two different toc files. If I do so, the help window 
> shows the right page and opens the tree(i know, its not really a tree 
> but it looks like a tree) at the right position, but the path on top of 
> the html page ist wrong.
> Thats why I tried "link_to". With link_to the path is not right but it 
> would be okay, but it does not open the tree.
> In a documentation I was reading, that displayHelpResource can hand 
> keywords like "key=value&amp;key=value" over.
> Maybe I can tell the help system to search for the html page with this 
> unique toc and not just to open the first fitting html page.
>
> I hope you can understand now what I mean and my problem...
>
>
> Lee Anne wrote:
>
> > Hi Jenny,
>
> > I'm adding the eclipse.platform.ua newsgroup to this thread.
>
> > That newsgroup includes a focus on the Eclipse help system, and folks 
> > who hang out there might see ways to help you.
>
> > What do you mean by "tried to use the same href twice"? The hrefs in 
> > your code snippet below look unique. Do you mean the same HTML file is 
> > in two different toc.xml files?
>
> > I'm not sure that your displayHelpResource parameters are proper. Can 
> > you describe what you expect to see displayed in the help system from 
> > executing that command?
>
> > Best regards,
> > Lee Anne
>
>
> > Jenny wrote:
> > > Hi,
> > >
> > > I use the eclipse native help system and encountered a problem:
> > > i want to use a html page at two different places, but don't know how 
> > > to do this.
> > >
> > > yet i tried to use the same href twice but the help don't show the 
> > > right path and i tried link_toc but than he don't show the actual 
> > > tree on the left; so neither one with satisfying success
> > >
> > > For Example:
> > >
> > > <toc label="gettingstarted" link_to="toc.xml#gettingstarted">  <topic 
> > > label="maintopic"  href="html/gettingstarted/maintopic.html">   
> > > </topic>   <topic label="subtopic"> <link toc="tocreference.xml"/>  
> > > </topic> </toc>
> > >
> > > <toc label="reference" link_to="toc.xml#reference">   <topic 
> > > label="subtopic" href="html/reference/subtopic.html">   </topic> </toc>
> PlatformUI.getWorkbench().getHelpSystem().displayHelpResource("toc=/HelpBook/tocgettingstarted.xml&topic=/HelpBook/html/reference/subtopic.html"); 
>
> > > Can anybody help me?