| Anchor/linkTo fails with custom TocProvider [message #470574] |
Tue, 30 October 2007 20:37  |
Eclipse User |
|
|
|
Originally posted by: bwhite.skywaysoftware.com
I have subclassed AbstractTocProvider and have managed to create a working
TocProvider that converts RoboHelp ToC files "on the fly" and contributes
them to the Help system.
[Definition: Toc = Table of Contents]
There are three ways to contribute a ToC:
1. As a primary (or top-level) topic.
2. By pulling the Toc into another Toc underneath some other primary topic.
This works by embedding a <link> element in the parent Toc to pull the
nested Toc into the tree. The <link> element references the <id> element of
the nested Toc.
3. By pushing the nested Toc into another Toc underneath some other primary
topic. This works by embedding an <anchor> element in the parent Toc. Then
the nested Toc refers to the "id" attribute of that anchor element inside
its "linkTo" attribute.
My project works so long as I use internal eclipse classes:
org.eclipse.help.internal.toc.TocContribution and
org.eclipse.help.internal.toc.Toc.
I tried to eliminate this discouraged access and uncovered a failure. I
rewrote my project using only the public interfaces: specifically
ITocContribution, IToc and ITopic. After doing so, I discovered that the
anchor/linkTo feature no longer worked.
The reason is that the user-contributed ITocContribution objects returned by
the implementation of AbstractTocProvider's getTocContributions() method are
actually discarded by its caller,
org.eclipse.help.internal.TocManager.getTocContributions(). This method
creates a new instance of the internal class TocContribution and copies
almost all of the information from the user-contributed ITocContributions.
If it were to copy all of the information before discarding the
user-contributed ITocContribution object, the anchor/linkTo feature would
continue to work, but alas it does not. For some reason, the getLinkTo()
method of ITocContribution is not called. I presume this is because they
are copying the embedded IToc object and they probably assume that this
embedded IToc object is actually an instance of an internal Toc. If it is
not, they construct a Toc and copy the contents of the IToc into it.
Unfortunately, IToc does not have a getLinkTo() method.
Moreover, the way AbstractTocProvider actually works, it is more likely that
the linkTo path is an attribute of the ITocContribution. At least, that is
how I implemented my project. I implemented an extension point that accepts
all of the attributes that a TocProvider needs to describe an
ITocContribution ("linkTo", "contributorId", "id", "isPrimary", "locale",
etc).
Be that as it may, the way TocManager.getTocContributions() is currently
written and given the absence of a getLinkTo() method on the IToc interface,
the only way to get the anchor feature to work is to actually embed an
org.eclipse.help.internal.toc.Toc object in the ITocContribution and make
sure that its linkTo field gets set properly. This Toc object has to be
returned by the getToc() method of the ITocContribution. If one does this,
then the linkTo path will be preserved by TocManager.getTocContributions().
As I said at the beginning, I have a working version of this project and my
company is preparing to open source it for those who would like to see an
example of a working TocProvider. This would be of special interest to
those who want to use RoboHelp to build their eclipse html Help files, but
do not like manually transforming the toc file each time. BTW, we also have
an XSLT transform that will do this, but clearly the TocProvider is more
convenient.
Contact http://www.skywaysoftware.com for more info.
|
|
|
|
|
|
|
|
| Re: Anchor/linkTo fails with custom TocProvider [message #470588 is a reply to message #470586] |
Thu, 01 November 2007 17:12  |
| Eclipse User |
|
|
|
Originally posted by: nospam_bwhite.skywaysoftware.com
I think I made things more complicated than necessary by breaking out the
code the way I did. The orginal line 201 does not need to change:
contribution.setToc(
toc instanceof Toc ? (Toc)toc : (Toc)UAElementFactory.newElement(toc));
does the same thing as
Toc cloneToc;
if (toc instanceof Toc)
cloneToc = (Toc)toc;
else
cloneToc = (Toc)UAElementFactory.newElement(toc);
I just broke this out to make the cloning process more obvious.
The key is just to add one line between 201 and 202:
200: IToc toc = contrib[j].getToc();
201: contribution.setToc(
toc instanceof Toc ? (Toc)toc :
(Toc)UAElementFactory.newElement(toc));
NEW: contribution.setLinkTo( contrib[j].getLinkTo() );
202: contributions.add(contribution);
|
|
|
| Re: Anchor/linkTo fails with custom TocProvider [message #592721 is a reply to message #470574] |
Wed, 31 October 2007 15:43 |
| Eclipse User |
|
|
|
If you are able to file a bug report and attach the TocProvider where
the anchor/linkto feature is not working I'll look into it.
I was writing an example for testing purposes which created a Toc
Provider without relying on internal classes and I noticed that it was
somewhat inefficient in the way it was copying the elements. This
process also seems like it could be error prone - see
https://bugs.eclipse.org/bugs/show_bug.cgi?id=207880 for an example of
how information can be lost during the copy process.
|
|
|
| Re: Anchor/linkTo fails with custom TocProvider [message #592754 is a reply to message #470574] |
Thu, 01 November 2007 11:07 |
| Eclipse User |
|
|
|
Originally posted by: nospam_kowalskilee.gmail.com
Hi Bob,
It would be really great to see an example of a working TocProvider. I
know of some folks on the eclipse_tw Yahoo!Group who would be interested
in using RoboHelp to create their Eclipse help files.
If you don't subscribe to the eclipse_tw group, please let me know when
you've got the example posted and I can post a note to that group.
Thanks!
Lee Anne
(to email, remove the nospam_ portion of my email).
Bob White wrote:
> As I said at the beginning, I have a working version of this project and my
> company is preparing to open source it for those who would like to see an
> example of a working TocProvider. This would be of special interest to
> those who want to use RoboHelp to build their eclipse html Help files, but
> do not like manually transforming the toc file each time. BTW, we also have
> an XSLT transform that will do this, but clearly the TocProvider is more
> convenient.
>
>
|
|
|
| Re: Anchor/linkTo fails with custom TocProvider [message #592820 is a reply to message #470578] |
Thu, 01 November 2007 14:48 |
| Eclipse User |
|
|
|
Originally posted by: nospam_bwhite.skywaysoftware.com
My boss is reviewing the code to see whether and how we can release it.
As I may have mentioned, it is a plug-in that exports and extension point
so that other plug-ins can specify the location of their RoboHelp files
and how they would like them to appear as TocContributions. I have also
written up an explanation of how to use it. I'm just waiting on
management approval.
|
|
|
|
| Re: Anchor/linkTo fails with custom TocProvider [message #592851 is a reply to message #470576] |
Thu, 01 November 2007 16:34 |
| Eclipse User |
|
|
|
Originally posted by: nospam_bwhite.skywaysoftware.com
I will file a bug report. It will be my first, but we have to start
sometime. :)
The bug you mentioned, the context id not getting copied properly, seems
to me to be a different problem (although, I did not examine the code).
In Anchor/LinkTo failure, the problem occurs when the TocManager assumes
that the LinkTo path is being stored in the Toc object embedded in the
ITocContribution. The TocManager should not presume anything about where
the LinkTo path is stored and should just copy this attribute as it does
all of the others.
It is all well and good that the internal TocContribution relies on its
embedded Toc object to store the LinkTo path. But if the TocManager is
going clone an internal Toc from the ITocContribution's embedded IToc, it
will have to attempt to set the linkTo path on that clone. I do not
believe there is any way to avoid having TocManager call
ITocContribution's getLinkTo() method and passing that value to the cloned
Toc object. IToc does not have a getLinkTo() method. It has to come from
ITocContribution.
The linkTo path would be preserved if we do the following (starting at
line 200 of org.eclipse.help.internal.toc.TocManager.java):
IToc toc = contrib[j].getToc();
Toc cloneToc;
if (toc instanceof Toc)
cloneToc = (Toc)toc;
else
cloneToc = (Toc)UAElementFactory.newElement(toc);
contribution.setToc(cloneToc);
contribution.setLinkTo(contrib[j].getLinkTo());
contributions.add(contribution);
|
|
|
| Re: Anchor/linkTo fails with custom TocProvider [message #592875 is a reply to message #470586] |
Thu, 01 November 2007 17:12 |
| Eclipse User |
|
|
|
Originally posted by: nospam_bwhite.skywaysoftware.com
I think I made things more complicated than necessary by breaking out the
code the way I did. The orginal line 201 does not need to change:
contribution.setToc(
toc instanceof Toc ? (Toc)toc : (Toc)UAElementFactory.newElement(toc));
does the same thing as
Toc cloneToc;
if (toc instanceof Toc)
cloneToc = (Toc)toc;
else
cloneToc = (Toc)UAElementFactory.newElement(toc);
I just broke this out to make the cloning process more obvious.
The key is just to add one line between 201 and 202:
200: IToc toc = contrib[j].getToc();
201: contribution.setToc(
toc instanceof Toc ? (Toc)toc :
(Toc)UAElementFactory.newElement(toc));
NEW: contribution.setLinkTo( contrib[j].getLinkTo() );
202: contributions.add(contribution);
|
|
|
Powered by
FUDForum. Page generated in 0.07533 seconds
Home