Community
Participate
Working Groups
Dejan made a change to book.css in org.eclipse.sdk to make command-links in help documentation show up different than ordinary links. His change makes an icon show up next to the command-links I'm opening this bug so we can discuss whether this should be fine-tuned a bit more before release. I'm noticing a problem with the way the icon is drawn when the link text wraps to the next line. I'll attach screenshots below... Also we might want to consider changing the icon and/or changing the color of the link underline or link text too.
Created attachment 35876 [details] here's what the icon looks like when the link text doesn't wrap (good)
Created attachment 35877 [details] here's what the icon looks like when the link text does wrap (bad) Notice how the icon is showing over by the 'T' in "Type" instead of before the word "Open". I don't know if this is somehow specific to my machine/configuration or a general problem.
The problem is real, but I would not worry much about it. The point was to associate Eclipse links with a unique CSS style so that we can tweak it and affect all links in the Eclipse SDK docs. I am assigning this to me and moving to the doc component.
I have moved the image to 'top left' and made the link 'nowrap'. There is less of a problem now. The only remaining issue is that sometimes the image will not show up (when the entire link is wrapped into the next line and the padding on the left is collapsed). I will study CSS more to see if I can make this space significant.
Chris, I have revised the conention for adding command links. We will still be using command-link CSS style, but I decided against injecting the image from CSS. It does not work well for inlined content like links when they wrap because the bounding box of the element is non-rectangular and 'top left' means different things depending on how it was wrapped. Instead, please make a pass over the command links in Eclipse SDK so that the following is added inside the <a> tag just before the text: <img src="../images/command_link.png"/> Example: <a class="command-link" href='javascript:executeCommand("org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.ui.preferencePages.ColorsAndFonts)")'> <img src="../../images/command_link.png"><b>General > Appearance > Colors and Fonts</b></a> Note that the actual image path is not a constant. The place where images are is different for different plug-ins, and depending on the location of the document, you may need more or less '../' segments to get to the 'images' directory. User docs (both platform and JDT) have one 'images' folder at the plug-in root, while ISV docs (again, both platform and JDT) have images inside the 'guide' folder (in this case, 'src' attribute would be "images/command_link.png"). I have included the image as an attachment to give to the JDT team with the patches (I don't have access to their doc). I have dropped the image in platform and PDE docs so you don't have to. Note that we still need the class attribute because I want to tweak the image styles and the layout of the image relative to the text. The image I am attaching is temporary. I will work with the visual designers to get the final image but we will use the same name so there will be nothing for you to do at that point.
Created attachment 37794 [details] Image to drop in the 'images' directory in the target doc plug-in.
OK, final revision (honest :-). But you are going to like this one. We have added support for PLUGINS_ROOT so that we can avoid duplication of the command link image and the markup you need to insert in the docs is stable. Just add the following inside the <a> tag before the text: <img src="PLUGINS_ROOT/PRODUCT_PLUGIN/command_link.png"> This will correctly resolve regardless of where the topic is. I will update this one image with newer one I get from the designers. I will also tweak the CSS to control how both the link and the image fit together.
Created attachment 38128 [details] patch for Workbench User Guide This patch fixes all the links in the user guide to include the image. Note: This patch DOES NOT include the command link image file!!! All of the image tags here look like this: <img src="PLUGINS_ROOT/org.eclipse.platform.doc.user/images/command_link.png"> So the command_link.png file needs to be committed too. I'm not including it with the patch because binary files mess up the patch tooling.
Chris, sorry for making you work more, but the 'img' statement should have been exactly as specified above: <img src="PLUGINS_ROOT/PRODUCT_PLUGIN/command_link.png"> This was not a typo - help system knows how to handle 'PRODUCT_PLUGIN' variable - it resolves into the plug-in where the active product is defined (in Eclipse's case, it is org.eclipse.sdk). I already placed 'command_link.png' in org.eclipse.sdk so this URL would resolve correctly - I tested it already.
Created attachment 38169 [details] fixed patch for Workbench User Guide Ok, I was confused because that exact <img ...> tag didn't work for me. But I see now that my nightly build wasn't quite new enough (didn't have the command_link.png in org.eclipse.sdk). In any case, this is easy to fix with global search/replace. Here's another patch with the right <img> tags. Also note I have cleaned the ../.. stuff from the the livehelp.js inclusion <script> tag too (and it works fine for me). These now all look like: <script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"> </script>
Created attachment 38438 [details] Fix documentation in PDE guide about authoring command links This patch updates several pages in the PDE guide (org.eclipse.platform.doc.isv) that describe how to author command links in help topics. There is also a little fixup for the page about authoring active help links.
Dejan, was the patch in comment 10 applied yet? The new patch in comment 11 needs to be applied too. Comment 10 is for Workbench User Guide and comment 11 is for PDE guide.
Note where I say "PDE guide" in last few comments, I really meant to say "Platform Plugin Developer Guide".
Don't forget JDT User Guide and ISV guide, as well as PDE user Guide (the real one :-).
I am going to close this defect because all the patches were applied. Separate defects should track JDT and PDE contributions.
Bug 130244 is for the Java Development User Guide. I'll comment more there.
I'm seeing a problem with the use of PRODUCT_PLUGIN. It won't work for infocenter or standalone help because they're not products, they're applications. It also won't work if you're just running the platform application as opposed to the sdk product. The browser shows the "icon is missing" icon when you try to view it. Is there another way we can do this without relying on a product being there?
PRODUCT_PLUGIN is used for resources that provide product-level 'glue' for documentation. For example, book.css is defined in PRODUCT_PLUGIN (in our case, org.eclipse.sdk) so that we can control the appearance of documentation from one central place. Using the same logic, we want to control how Eclipse links are rendered from one central place, allowing other products to use other images for that. The subtle difference here is that missing book.css (due to the missing PRODUCT_PLUGIN) results in documentation that is still readable (since topics are still rendered in an acceptable although clunky way without our CSS). In contrast, missing image is shown as a broken link i.e. not as nice. Perhaps we can resolve PRODUCT_PLUGIN to org.eclipse.help if we are actually not running as a product. We can place a fallback image there so that we can avoid the broken image problem.
As discussed with Dejan, I moved away from using PRODUCT_PLUGIN in favor of org.eclipse.help. We are treating the images as content rather than style so they cannot be customized by products. Dejan, can you remove the image from org.eclipse.sdk? I don't have access to it.
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.
I assume this is the cause of all the broken image links in today's help doc (N20060425-0010)?
It is.
Updating milestone for unfinished doc work
Actually this one was completed. Marking as fixed.
