Producing Eclipse User Assistance with Technical Communication Suite 3
Editor's Note: The author, fellow STC member and current STC Chapter President Fei Min Lorente, was kind enough to pen this guest blog entry for us. Her initial inquiries related to EclipseHelp are what led her to investigate the options available with FrameMaker and RoboHelp. We at roundpeg appreciate her taking the time to document this for us and our clients. If you find this information valuable, please show her a little love by commenting below, and by connecting with her via her contact info below!
Eclipse is an open development platform comprising extensible frameworks, tools and runtimes for building, deploying and managing software across the lifecycle. Adobe® Technical Communication Suite 3 is a complete single-source authoring toolkit with multichannel, multidevice publishing capabilities. You can develop standards-compliant content with Adobe FrameMaker® 10 software, publish in various formats with Adobe RoboHelp® 9 software and Adobe Captivate® workflows, collaborate with reviewable PDF files, incorporate images using Adobe Photoshop®, and add demos and simulations using Adobe Captivate.
Can you generate Eclipse help (aka Eclipse user assistance) using TCS3? The answer is a qualified “yes”.
You can get basic Eclipse help from your FrameMaker book simply by choosing File > Publish in FrameMaker 10. On the Publish Settings dialogue box, choose EclipseHelp from the drop down list. Specify where you want the generated Eclipse help file to be saved, and click Publish. Although RoboHelp converts the files for you, you don’t even have to start it yourself; TCS3 runs RoboHelp for you during the conversion process. These are the results:
- Each chapter of the FrameMaker book is converted to HTML and placed in separate folders
- A toc.xml file is created that conforms to the Eclipse help standard, and it has links to subsections of the chapters that match the FrameMaker table of contents.
However, if you want something other than these out-of-the-box results, you have to customize the EclipseHelp.jsx ExtendScript file, which is found in $FMHOME\fminit\. For example, you might want to produce your Eclipse help as follows:
- Specify other attributes and provide a customized label on the toc element in the toc.xml file. Examples of other attributes are link_to which refers to an anchor in a higher-level TOC file, and topic which links to a specified page if a user clicks on the title of the manual.
- Specify a path to the HTML files; TCS3 assumes the toc.xml file is in the same folder as the HTML files.
- Change the name of the toc.xml file.
I hard-coded some changes to the EclipseHelp.jsx file, and they showed up in the toc.xml output. I didn't go so far as to pass it parameters, but Scott Prentice of Leximation tells me that it will accept input from a text file, so you could, for instance, give each toc.xml file a different link_to attribute value.
I didn't explore a lot of the customizing features of RoboHelp, but I think it would be safe to assume that any templates or configurations you can do in RoboHelp will apply to Eclipse help output. For example, Nancy Halverson, a proficient RoboHelp user, tells me that you can configure RoboHelp to split the FrameMaker files on a specific paragraph style. That allows you to break up each FrameMaker chapter into smaller HTML files and presumably, the toc.xml file will provide links to all the files.
One feature of the TCS3-generated Eclipse help that I like is that the heading numbers are preserved in the TOC file. My current help output system does not have this feature, so referring to a particular page can be cumbersome; you have to duplicate the breadcrumb trail to explain where to find something.
For those who are curious, the Evaluation and Development Board Manual for BelaSigna 300 is a sample of the Eclipse help that was produced with TCS3.
I would like to thank Rajat Bansal of Adobe for extending my trial period so that I could complete my investigations, and Amit Agarwal of Adobe for pointing me in the right direction so that I could generate some output. I have added my feature requests to the wish list, and hopefully in the near future, Adobe will provide more robust support for Eclipse user assistance.
by Fei Min Lorente
Senior Technical Communicator
Fei Min Lorente has been a technical writer for over 20 years in the software, hardware and defense industries. She has been using FrameMaker on and off since 1991. She has savored the challenges of new technology, including pioneering the production of Eclipse Help at ON Semiconductor. As a lone writer in her business unit, she is embedded in a software development group, and she has picked up some of their habits. In her spare time, she is the president of the Southwestern Ontario chapter of the Society for Technical Communication (STC).