Community
Participate
Working Groups
I'm going to attach a patch with minor changes to many of the html pages in the Java Development User Guide. The goal of these changes is to add links that execute commands that tie the help to something the help is describing in the workbench. A typical example would be a help topic with text like this: Use the General > Appearance preference page to blah blah blah.... Where "General > Appearance" will now appear as a link and will actually open that preference page when the link is clicked. The most common use of command links in this patch is to open preference pages, but there are also some that open views, perspectives, new/import/export wizards and a few random dialogs. For more details see bug 123921, bug 129270 and bug 130055.
Created attachment 35653 [details] patch described in the initial bug comment
Thanks for the patch. What I find confusing is that now some links just switch to another help page, where as others open some dialog. And you can only find it out through clicking on it. Shouldn't we be more explicit, e.e change the text to The Java > Compiler preference page (<a>Open Page in Eclipse</a>) lets you configure... Or instead of a text 'open in Eclipse' maybe an image? What's also a problem is the feedback. Eclipse doesn't seem to get the focus (I had the help page opened in n extrenal browser). Do you want me to release the changes anyway? I really think we need a better solution here. Let me know if you preferr that I file these issues as bugs.
Martin, you are right that a small image in addition to the link would visually separate the Eclipse active help from other links. Alternatively, we can introduce a special style for Eclipse links and use a different color (e.g. green). Focus issue is solved with a workarbound provided by SWT but you don't have the latest code (it will be in the next I build). I suggest you release the links now. We will work with visual designers and usability people to find out the best way to distinguish them from regular links, but that can go under 'polish'. For now we want to make sure all the links work and do what they claim to do.
FYI, bug 130206 tracks the focus issue.
Bug 130834 was just created to track the issue of making command links appear different from ordinary HTML hyperlinks. I'm going to attach a new patch that makes the all the links specify the css class so that the technique decribed in bug 130834 will work.
Created attachment 35878 [details] alters links to specify CSS class for tuning link appearance In the first patch the command links all had this form: <a href='javascript:executeCommand("org.eclipse.ui.help.aboutAction")'>About Eclipse SDK</a> In this new patch they will look like this: <a class="command-link" href='javascript:executeCommand("org.eclipse.ui.help.aboutAction")'>About Eclipse SDK</a> The addition of the class="command-link" attribute allows the appearance of the link to be fine-tuned as described in bug 130834
Martin, you can apply this patch. We will tweak the presentation of Eclipse links to be sufficiently different from navigation links in the coming days and weeks. Since all JDT docs are affected by book.css in org.eclipse.sdk, we can do that without any further changes in JDT.
Thanks for the update. Is this how you want it to be in the final result, or is this just for proving the concept and testing? If this is the final result, can I still make some suggestions? I looked at this with Erich and Tom, and we all agreed that some more polish is required. Depending on who continues from this point on (you or us), I can either release and you send me updates, or we do it before releasing. We found the these issues: - About 80% links now contain mixed styles (for example <a><b>Java > Editor</b> preference page</a>), but some just do <a><b>Java > Editor</b></a>. Mixed style look really strange. We suggset to only use 'Java > Editor' as link. - Sometimes we still have documentation links at exactly these places. I assume we should remove these and replace them with the Open UI link. Wouldn't the user want both? - Obviously we haven't seen the new style sheet in action yet. But we still not sure if the user get's the idea what's happening when looking at the text. I like the way things are done in the style sheets, where you have the description text (no links) but a 'play' image at the end of the paragraph. As mentioned above, the user probably has two needs. Either more help about a particular preference page, or he wants to open that dialog in the help page. I rather would use the link for the first, and a play 'button' for the second.
Agreed about mixed styles. We should follow one convention for describing menu bar paths. Note though that Chris simply turned existing text into a command link, and this text had <b> to begin with. If you have documentation links, you should leave it as-is. We only wanted to create new links in places where you had no link to begin with. There is nothing special about the style - I am just injecting the 'run' icon in front of the 'command-link' links. The icon is part of the link and clicking on it produces the same result as clicking on the link text itself. As said above, the command links are added for menu bar paths that used to be static text, so there is no navigation link to coexist with the icon and do a different thing. Personally I would try to not be too clever in the docs - all we want to do is add some Eclipse links in places that were static text before and use an icon and/or different CSS style to differentiate them from navigation links.
What do you think about using this 'Play' image as in the cheat sheets? I would rather have the links in text to always link to the documentation of the preference page, and have the 'Play' image at the end of a paragraph.
Please stand by - I think it would be best to involve a visual designer at this point. I will follow up.
The markup for command links has now been hashed out in bug 130834. Command links should look like this: <a class="command-link" href='javascript:executeCommand("org.eclipse.ui.help.aboutAction")'> <img src="PLUGINS_ROOT/PRODUCT_PLUGIN/command_link.png"> Open the About dialog</a> Things to note: 1) class="command-link" - allows for CSS tuning of the link appearance 2) <img ...> - standard image indicating a command link appears just before link text Martin, do you want me to make another pass over my earlier patch and apply these changes? Or do you want to do this yourself to get the link text exactly as you would like? My suggestion would be to allow me to first do the "grunt work" of fixing up the markup as described above. Then you can make an "editorial pass" (like you mentioned doing before with Erich and Tom) and fine tune any places where you think the link text doesn't read well.
ok, go ahead!
Created attachment 38660 [details] new patch with images and other cleanup Ok, here is a new patch for the Java Development User Guide. It has these changes from previous patches: * Added images to all the links. * Changed to use PLUGINS_ROOT where that is supported. For instance the <script> tag in the HEAD section of the files now looks like this: <script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"> </script> (where PLUGINS_ROOT replaces something like .. or ../.. or ../../..) * I tried to be much more consistent about the wording and which words go inside vs. outside the link text. The style I adopted is like this: <a class="command-link" href='javascript:executeCommand("org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.jdt.ui.preferences.ClasspathVariablesPreferencePage)")'> <img src="PLUGINS_ROOT/PRODUCT_PLUGIN/command_link.png"> <b>Java > Build Path > Classpath Variables</b></a> preference page. So note that "preference page" (or "wizard", etc) appears outside the link text. Also note that the link text is bolded (using <b> or <strong> - I actually just left what markup was already there and it was pretty evenly split between <b> and <strong>).
Note that since the entire command link is registered as a CSS style, we can fine-tune many aspects of the presentation, including disabling the 'bold' emphasis if we want to. If we decide to do so, it will be consistent across all the SDK docs.
Created attachment 39379 [details] updated patch without PRODUCT_PLUGIN I've updated the patch to move away from using PRODUCT_PLUGIN in the image path because it doesn't work when not in a product (you get the broken image link picture). Instead, we are treating the image as content and not allowing products to change the image.
released patch from comment 16 > 20060425. In my debugging workspace I currently don't see the image, also when running as product.
I synced with HEAD and I do not see the changes from the patch. Are you sure you applied the right one?
You're right, I ran in a conflict. Fixed now.
Note: I had forgotten to add the image in org.eclipse.help to build.properties; I just added it and it will be in the build tomorrow. If you check out org.eclipse.help, you should be able to see the image. Also note this is not the final image, and you will not have to change anything when we get the final image.
