Community
Participate
Working Groups
Authoring context help is a sore point for many people because context help authoring requires adding an extension, editing an XML file, listing 'see also' links for each context id and associating the id with a widget in Java code. A PDE tool similar to 'Externalize Strings' that introspects Java code and locates constructors where 'setHelpId' can be inserted would be heaven, but certainly hard. A context help file editor may be more realistic. A benefit here would be seeing contexts in a form with a text area for adding description and a lookup to choose topics for the 'See Also'. A great tool would also be a validator that would check broken references (topics that do not exist) and references in Java code that point at the missing context Ids.
Anything that helps make the creation and validation of helpIDs would be very appreciated, especially the TOC links. I have yet to find a tool that can help me find problems in my TOC files. Valid links in the rest of the manual can be verified extensively, but not my TOCs. Some simple way to view or discover the currently focused helpID for a view, dialog, or window would also be helpful. For example, right now it the engineer has not told me a helpID exists for the item I have no way to see if I need to remind them to add it unless I review the source code or if I've defined my portion of the chain wrong. Also, the ability to view the chain between the engineers helpID definition and assignment and the authors link in the plugin.xml file to the actual help content itself (helpID -> plugin.xml -> helpID.xml) would help narrow down why the help content is not appearing as it should.
Frank, in bug 203451, there's a patch that will allow you to spy help context ids as part of the Plug-in Spy work. I think that should help as a verification mechanism on your end. I haven't dropped the code yet because there are some issues I think still and would like more community testing first. Sniffing the context ids from SWT controls isn't as easy as I'd like.
(In reply to comment #1) > Valid links in the rest of the manual can be verified extensively, but not my > TOCs. Frank, we actually added tools to validate your TOC links a while back. Take a look at "org.eclipse.help.internal.validation.TocValidator" (in the "org.eclipse.help.base" plug-in). An excellent way to use this tool is in a JUnit test. For a reference implementation, take a look at the user assistance test suites ("org.eclipse.ua.tests" plug-in). The test that uses this class is "org.eclipse.ua.tests.help.toc.TocLinkChecker". It should be noted, of course, that the class is flagged as internal, so it is by no means guaranteed to exist forever, nor is its functionality set in stone. This doesn't solve the actual point of the bug, but may help you out a bit with your tocs. ;)
Chris -- haven't had a chance to look at Plug-in Spy yet but now you've given me a real big incentive to do so. LOL, thx Adam -- will look into those validation tools too. We are doing some Junit tests here but I have not tried doing anything for my docs with Junit. Thx for the pointer.
Setting to 3.4
We are going to see what we can do for M5 though some more advanced features will probably have to wait until M6.
We shipped a basic context help editor. I'd open enhancements for the rest of the issues if you wish.
btw, thank you very much for this Curtis ;)
I'm keeping this bug open as an enhancement request for a wizard or tool that can validate context help id references (checking for unused entries, etc.). Something to make it easy to assign context help to the SWT controls would be awesome as well, but a validator is more realistic. I opened Bug 224892 for a small enhancement I will do for M7. I'm marking this bug as helpwanted and bugday because there won't be time in M7 for me to do it.
Moving back to the PDE box.
Created attachment 136892 [details] Patch to find broken links It wont go until 3.6 but for sure it'll help in 3.5 doc work, specially like bug #277506.
*** Bug 176715 has been marked as a duplicate of this bug. ***
This bug hasn't had any activity in quite some time. Maybe the problem got resolved, was a duplicate of something else, or became less pressing for some reason - or maybe it's still relevant but just hasn't been looked at yet. If you have further information on the current state of the bug, please add it. The information can be, for example, that the problem still occurs, that you still want the feature, that more information is needed, or that the bug is (for whatever reason) no longer relevant.
Please remove the stalebug flag, if this issue is still relevant and can be reproduced on the latest release.
