Eclipse Community Forums: Platform - User Assistance (UA) » creating a nested table of contents structure

Home » Eclipse Projects » Platform - User Assistance (UA) » creating a nested table of contents structure(problems using the <link> element in a table of contents)

Show: Today's Messages :: Show Polls :: Message Navigator

creating a nested table of contents structure [message #648256]

Wed, 12 January 2011 05:54

jcb

Messages: 12
Registered: September 2010

Junior Member

Hi.
I am attempting to create a nested toc structure in my help plugin. I want my main toc.xml bring in the nested, modular toc.xml files that exist within the structure of my plugin directory tree.

In my top-level toc.xml I have this:

<topic label="Reference" >
  <topic label="my-lib">
    <topic label="Version X" href="html/reference/my-lib/version-x/index.html">
      <link toc="html/reference/my-lib/version-x/toc.xml"></link>
    </topic>
    <topic label="Version Y" href="html/reference/my-lib/version-y/index.html">
      <link toc="html/reference/my-lib/version-y/toc.xml"></link>
    </topic>
  </topic>
</topic>

Then, the nested toc.xml files look like this (for example, Version X):

<toc label="Version X">
  <topic label="foo function" href="html/reference/my-lib/version-x/foo.html"/>
...
</toc>

(there are more <topic> elements, too many to include here.)

The help table of contents does show the structure correctly down to Reference/my-lib/Version X, but instead of making Version X into a book with subtopics from its linked toc.xml, it only shows Version X as a single topic page (i.e. a page icon), with nothing underneath. When I click on Version X in the tree it does locate the index.html specified in its href attribute. (Same behavior goes for Version Y.)

So it looks like the <link> elements don't do anything. There is no error logged when the help loads.

I have seen this working in a different help plugin. The toc was not nested as deeply, but the mechanism and directory structure is exactly the same.

What are some probable causes for <link> to fail, or at least not work as I'm expecting it to in this case? Is there someplace else to look for debugging output besides the error log?

Thanks for any assistance,
John

Report message to a moderator

Re: creating a nested table of contents structure [message #648436 is a reply to message #648256]

Wed, 12 January 2011 22:26

Chris Goldthorpe

Messages: 815
Registered: July 2009

Senior Member

I'm guessing that your paths are incorrect. From reading the toc it appear that if the top level toc is at the top level the child toc is at "html/reference/my-lib/version-x/toc.xml. The topics in the child toc have a path of html/reference/my-lib/version-x/foo.html relative to the child toc, or html/reference/my-lib/version-x/html/reference/my-lib/versio n-x/foo.html relative to bundle.

There are some flags that you can turn on to enable more tracing. The easiest way to do this is as follows

Run/Run Configurations
Create a new configuration under Eclipse Application
Select the Tracing Tab
Select and check org.eclipse.help
Check the 4 checkboxes on the right corresponding to org.eclipse.help.
Hit Run to launch Eclipse with tracing

[Updated on: Wed, 12 January 2011 22:26]

Report message to a moderator

Re: creating a nested table of contents structure [message #648461 is a reply to message #648436]

Thu, 13 January 2011 00:29

jcb

Messages: 12
Registered: September 2010

Junior Member

Hi Chris thanks for the help..

I think you are right, it must be the paths. But in the plugin where this nesting mechanism works, I have the paths expressed in the same way as they are in the "broken" plugin.

Sooo...you said:

Quote:

The topics in the child toc have a path of html/reference/my-lib/version-x/foo.html relative to the child toc, or html/reference/my-lib/version-x/html/reference/my-lib/versio n-x/foo.html relative to bundle.

Which way are the paths in the child toc supposed to be? I thought all the paths in a toc.xml (even in a linked toc.xml that resides in a subdirectory) were supposed to be specified from the root of the bundle, so in my case that would be:

html/reference/my-lib/version-x/foo.html

Likewise, the <link> element in my top-level toc.xml (which resides at the root of the plugin) has:

html/reference/my-lib/version-x/toc.xml

Note the actual directory structure for the html looks like this:

html/reference/my-lib/version-x

NOT like this:

html/reference/my-lib/version-x/html/reference/my-lib/version-x

When I use Eclipse to edit these toc.xml files, I can browse to the location of each topic. The path Eclipse itself puts in is exactly like I have it (but note, the linked toc still does not display properly).

Incidentally, when I package this help plugin up as a jar file instead of a plain directory, my table of contents doesn't show up in the help at all..

Tracing did not show any other information that could help.

Thanks again...

Report message to a moderator

Re: creating a nested table of contents structure [message #648477 is a reply to message #648436]

Thu, 13 January 2011 05:04

jcb

Messages: 12
Registered: September 2010

Junior Member

This has something to do with how the plugin is being exported and/or installed.

When I run the plugin from Eclipse (with a run configuration like Chris suggested), the table of contents behaves properly.

But if I export the plugin (as a deployable plugin) to a directory, and drop the exported plugin into the plugins directory of an eclipse installation, I get the behavior described, where the linked toc is not merged in with the tree.

I think it is something about how the linked toc.xml is specified in the plugin.xml file. I have it as:

<toc
            file="html/reference/my-lib/version-x/toc.xml"
            primary="false">
 </toc>

This is how Eclipse added it from the Extensions tab of the plugin editor.

Aren't help plugins deployed simply by exporting them??

Report message to a moderator

Re: creating a nested table of contents structure [message #648674 is a reply to message #648477]

Thu, 13 January 2011 22:14

Chris Goldthorpe

Messages: 815
Registered: July 2009

Senior Member

Help files are indeed deployed by exporting them. It's possible that not all files in your plug-in are being exported. You can check this by editing build.properties and looking in the binary build column.

Report message to a moderator

Re: creating a nested table of contents structure [message #648678 is a reply to message #648674]

Thu, 13 January 2011 23:57

jcb

Messages: 12
Registered: September 2010

Junior Member

Chris, this whole thing is getting weirder and weirder.

I have the plugin exported to a directory. Today I dropped it into the Eclipse plugins folder and when Eclipse started, I had this error in the log:

!ENTRY org.eclipse.equinox.p2.engine 4 4 2011-01-13 14:20:07.929
!MESSAGE An error occurred while installing the items
!SUBENTRY 1 org.eclipse.equinox.p2.engine 4 0 2011-01-13 14:20:07.929
!MESSAGE session context was:(profile=SDKProfile, phase=org.eclipse.equinox.internal.p2.engine.phases.Install, operand=null --> [R]net.mycompany.myplugin 11.1.0.1, action=org.eclipse.equinox.internal.p2.touchpoint.eclipse.actions.InstallBundleAction).
!SUBENTRY 1 org.eclipse.equinox.p2.touchpoint.eclipse 4 0 2011-01-13 14:20:07.929
!MESSAGE The artifact file for osgi.bundle,net.mycompany.myplugin,11.1.0.1 was not found.

I don't even know what this means. What is an artifact file?

So I shut down Eclipse, and I removed the plugin from the Eclipse installation (by deleting the directory). Launched Eclipse with just the basics, and started the help. Alls well, my help isn't in there. There is some sanity in the world. Or is there?

I then took the exact same plugin directory, and copied it again into the same Eclipse installation. Start Eclipse and...whoa what's this? NO ERROR in the log. AND, the table of contents now works perfectly.

I know I sound like a crazy person who has tons of issues but here are the facts: I started eclipse with my plugin installed and got an error in the log. I shut down Eclipse. I removed the plugin. I recopied the exact same, unchanged plugin back into Eclipse. I restart Eclipse and this time it works.

So I still have no idea what caused the original problem, and it looks like it's some kind of spurious unreproducible star alignment conundrum. Utterly bizarre.

Thanks again,
John

Report message to a moderator

Re: creating a nested table of contents structure [message #649162 is a reply to message #648678]

Mon, 17 January 2011 23:12

Chris Goldthorpe

Messages: 815
Registered: July 2009

Senior Member

I don't know exactly what would have caused the inconsistent behavior loading the plug-in but my guess is that there was a problem in data in the cache used by p2, which is the part of the Eclipse runtime responsible for managing plug-ins. If that is the case it sounds as though you have run into an obscure bug which apparently is not easy to reproduce.

Report message to a moderator

Re: creating a nested table of contents structure [message #649595 is a reply to message #649162]

Wed, 19 January 2011 20:42

jcb

Messages: 12
Registered: September 2010

Junior Member

Hi Chris I think you are right about the p2 thing. That's the only thing I can think of.

Recently a colleague installed the same help plugin on her machine -- exactly the same plugin that now works fine on my machine. On her machine, the help doesn't even appear in the table of contents at all. Nothing, not even the top-level book appears. She has no messages in the error log.

Is there a way to reset p2's cache?

Report message to a moderator