Post on 16-Apr-2017
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Getting Up To Speed on Eclipse™ User Assistance
Dr. Lee Anne KowalskiTelleltis Consultinglee_anne_kowalski@yahoo.com
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
About me 16 years experience as a
technical writer and information architect
Working with Eclipse since V2.0 (2002)
Project lead for development team enhancing standalone Eclipse help system/infocenter for use within IBM (2003 – 2007)
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
What is this talk about?
Boss says: “We’re going to do an Eclipse version of our product. When can you give me a plan for delivering the online help?”
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
What pops into your mind How can I be successful in this? Why are we doing this? What output form is “Eclipse help”? Can I reuse my source files? Can I
reuse my CHM files? Can I use my same authoring tools? If
not, what can I use? Who can I ask? Should I start looking for a new job?
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
First time out
Seek simplicity!
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Eclipse is…
An open-source integrated development environment (IDE)
A community
An open platform for buildingAn open platform for buildingany type of applicationany type of application
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Why Eclipse is attractive to decision makers?
Minimizes costs (short & long term) “Open source”
Free/low cost Unfettered (simple licensing)
Extensible Vibrant, growing community
Maximizes opportunities Many platforms/devices, native look &
feel Modularity (plug-ins/bundles) Ecosystem driven
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
The UA features (live demo)
Eclipse 3.4 Software Developers Kit (SDK) (Eclipse “Workbench”)
Help Contents tri-pane window
Contextual (embedded/F1) help
Welcome pages Cheat sheets Eclipse SDK displaying the embedded help
view
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Getting and starting the Eclipse Workbench (Windows)
1. Download package from www.eclipse.org
“Classic” package good to start with
2. Unzip using zip tool (issues with XP native extraction)
3. Double-click eclipse.exe in the eclipse directory
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
The Workbench
Eclipse 3.4 (“Ganymede”)
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Make conscious choices
Base UA choices on your “Going to Eclipse”
scenario Target audience
expectations and requirements
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Typical “going to Eclipse” scenarios
Scenarios ExamplesExtend the Eclipse Workbench (IDE) MyEclipse Enterprise
WorkbenchCreate Workbench plug-ins <oXygen/>® XML AuthorCreate desktop app Actuate BIRT Report
DesignerProject owner/member Data Tools Project (Sybase)
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Observed pairingsScenarios Exploited UA mechanismsExtend the Eclipse Workbench (IDE)
Help Contents (topics, ToC, index)Contextual helpTypically: Welcome pagesOptionally: Cheat sheets
Create Workbench plug-ins
Help ContentsContextual help (audience dependent)Optionally: Cheat sheets
Create desktop app
Help ContentsOptionally: Contextual help, cheat sheets, Welcome pages
Project owner/member
Depends on the nature of the project
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
What you’ll create
“doc” plug-ins Loosely = a chm Packaged in a “plug-in
archive file” (.jar file) Unjar’d directories
can work (e.g., when testing)
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
About Eclipse plug-ins Eclipse apps consist of
modular “plug-ins” “…plug-ins are the
fundamental unit for packaging function” (source: Platform Plug-in Developer Guide)
Also called “OSGi™ bundles” (Eclipse 3.1 onward)
Primarily in eclipse/plugins directory
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Typical doc plug-in anatomy
Contents of plug-in: Help Contents topics
(HTML, XHTML files) Table of Contents files
(“toc.xml”) Keyword index files
(“index.xml”) Contextual help content
(“contexts.xml”) plugin.xml file MANIFEST.MF file
plugin.xml and MANIFEST.MF files describe the plug-in
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Doc plug-in creation Some authoring tools generate doc
plug-in’s files (or most of the files) as part of their work flow
Or you assemble and package the doc plug-in
a. Create the files for the doc plug-inb. Collect the files into the defined directory
structure.c. Jar it up into a .jar filed. Deploy into Eclipse environment
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Using Eclipse PDE to create a doc plug-in (demo)
In PDE environment, use File -> New -> Other, and choose Plug-in Project to create a new plug-in.
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Using Eclipse PDE to test a doc plug-in
1. Right-click on your plug-in project and select Run As -> Eclipse Application.
2. New instance of Eclipse Workbench will start up.
3. Go to Help -> Help Contents in the new instance to open the help window and see your doc plug-in in the ToC.
4. After checking your plug-in, shut down the newly opened windows.
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Plug-in id conventions
Organization
Bundle-SymbolicName (id) Examples
Public company
com.<companyname>.<abc>
com.oxygenxml.editorcom.ibm.eou.tmtool
Non-profit/open source
org.<orgname>.<abc> org.eclipse.pde.uiorg.objectweb.asm
Conventions for plug-in id/Bundle-SymbolicName
The plug-in id (Bundle-SymbolicName) is how the runtime environment identifies the module among all other plug-ins
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Plug-in .jar naming conventions
Before Eclipse 3.2
<plugin-id>_<plugin-version>.jar
After Eclipse 3.2 <Bundle-SymbolicName>_<Bundle-Version>.jar
Valid plug-ins:org.eclipse.platform_1.0.3.jar jar fileorg.eclipse.pde.doc.user.jar jar filecom.lak.test1.doc directory
Recommended, not required
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Some tools for generating doc plug-in files Frame -> Omni Systems Mif2Go Word, Frame, DITA -> WebWorks
ePublisher XMetal® Author Enterprise DITA Open Toolkit IXIASOFT’s DITA CMS solution Eclipse Plug-in Development
Environment (PDE)
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Another methoda. Author XHTML topic files in
XHTML/HTML toolb. Author toc.xml files in XML-aware tool
or in PDEc. Author index.xml file in XML-aware toold. Create plugin.xml and MANIFEST.MF
files in PDEe. Assemble and package jar
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Yet another methoda. Create TOC and index files in a
well-formed format (ideally XML)b. Transform into Eclipse toc.xml
and index.xml files via script or search and replace
Example: JavaHelp toc.xml and index.xml files
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Working with your development teams
Contextual help contexts.xml maps context IDs to brief descriptions
and links to help topics Programmer’s code plug-in defines context ID Evangelize creating context IDs during
design/develop activity Cheat sheets
Development will usually program these Review task flow for them Provide links into help topics
Welcome pages Determine plan for whether and how to exploit
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Asking questions in the community Yahoo!Group: eclipse_tw
Primarily technical writers Since 2004 http://groups.yahoo.com/group/eclipse_tw/
Newsgroup eclipse.platform.ua Since 2007 For instructions on how to access, see
Eclipse NewsPortal (www.eclipse.org/newsportal/index.php)
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Seek simplicity! Provide doc plug-ins for
Help Contents Have a way to generate
the doc plug-in files Assess your scenario’s
contextual help needs and plan accordingly Dynamic help section of
the Help View can help here
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Thank you! You can be
successful in delivering Eclipse help
You can be a hero to your team!
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Bonus Section Help Contents tips & gotchas Looking under the hood To learn more and locate expertise Useful references Using Eclipse Bugzilla to report bugs
and request new features Eclipse is… Why is Eclipse attractive to developers
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Help Contents tips & gotchas Search is "tied" to ToC contributions
(toc.xml) Only files referenced in toc.xml are indexed for
search, or those from extradir attribute Search results displays topic’s <title> text
(not <h1> or <topic> label) Consider using <title> text distinct from the
<topic> label text for that topic Use <meta name="keyword"
content="…"/> tag in topics to add synonyms for user searches
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Help Contents tips & gotchas (cont.) Avoid using anchors in toc.xml
Breadcrumb trail gets broken “Show in TOC” breaks when it can’t match right
hand frame’s URL#anchor with a ToC topic href Example: Index word has one anchor and ToC
topic has a different anchor Be sensitive to case-sensitivity (Win vs
Linux) <topic href="My_Guide.htm" /> ≠ <topic
href="my_guide.htm" />
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Help Contents tips & gotchas (cont.) Use HTML "wrapper" topics for non-
HTML content When you want to include PDFs, Flash,
PPT content in the help system Have an HTML topic that has brief
description and anchor to non-HTML file Use <meta name="keyword"
content="…"/> tag in HTML file to specify search terms
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Help Contents tips & gotchas (cont.)
Presentation of non-HTML contentPDF bookmarks open next to help system table of contents looks weird.
Solution:Open PDF in a separate window by using the <body onload> event (JavaScript) to open a new window outside the help system frameset.
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Looking under the hood Useful for debugging Configuration markup for
MANIFEST.MF plug-in.xml toc.xml index.xml contexts.xml
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Basic MANIFEST.MF structure
Manifest-Version: 1.0Bundle-ManifestVersion: 2Bundle-Name: Bear GuideBundle-SymbolicName: com.lak.test1.doc;singleton:=trueBundle-Version: 1.1.2Bundle-Vendor: Lee Anne Kowalski
Before 3.1, plugin.xml holds 3.1+, MANIFEST.MF holdsnameidversionprovider-name
Bundle-NameBundle-SymbolicNameBundle-VersionBundle-Vendor
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Basic plugin.xml structure (3.1+) for doc plug-in
<?xml version="1.0" encoding="UTF-8"?><?eclipse version="3.2"?><plugin><!– extension points this plug-in plugs into --><extension point="org.eclipse.help.toc"> <toc file="toc.xml" primary="true" /></extension></plugin>
MANIFEST.MF file holds other plug-in identifying info (e.g., id, version)Extension points are well-defined places where other plug-ins can add (“plug in”) functionality.
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Basic plugin.xml structure (3.0) for doc plug-in
<?xml version="1.0" encoding="UTF-8"?><?eclipse version="3.0"?><plugin name=“Bear Guide” id=“com.lak.test1.doc” version=“1.1.2” provider-name=“Lee Anne Kowalski”><!–- extension points this plug-in plugs into --><extension point="org.eclipse.help.toc"> <toc file="toc.xml" primary="true" /></extension></plugin>
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
toc.xml structure<?xml version="1.0" encoding="UTF-8"?><?NLS TYPE="org.eclipse.help.toc"?><toc label="Guide to Bears" topic="html/welcome.html"> <topic href="html/intro/intro.html" label="Introduction to bears"> <topic href="html/intro/whatis.html" label="What is a bear"> </topic> <topic href="html/intro/where.html" label="Where do bears live"> </topic> <topic href="html/intro/food.html" label="What do bears eat"> </topic> </topic>...</toc>
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
index.xml structure<?xml version="1.0" encoding="utf-8"?><?NLS TYPE="org.eclipse.help.index"?><index><entry keyword=“bear types"> <entry keyword=“polar”> <topic href=“html/types/polar.html"/> </entry> <entry keyword=“grizzly"> <topic href=“html/types/grizzly.html"/> </entry></entry></index>
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
contexts.xml structure<?xml version="1.0" encoding="UTF-8"?><?NLS TYPE="org.eclipse.help.contexts"?>
<contexts><context id="toc_editor"><description>This editor creates a Help table of contents, which allows you to organize how documentation is displayed to users of an Eclipse product.</description><topic label="Table of Contents Editor" href="guide/tools/editors/toc_editor/editor.htm"/></context><context id="ctx_help_editor" title="Context Help Editor">…</context>…</contexts>
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Doc plug-in’s plugin.xml structure (one ToC, one index)
<?xml version="1.0" encoding="UTF-8"?><?eclipse version="3.0"?><plugin><!-- Define primary TOC --> <extension point="org.eclipse.help.toc"> <toc file="toc.xml" primary="true" /></extension><!– Define index file --> <extension point="org.eclipse.help.index"> <index file="index.xml" /></extension></plugin>
primary =“true” makes this ToC appear as a ‘book’ on the main level in the ToC view
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Doc plug-in’s plugin.xml structure (multiple ToC, index files)<?xml version="1.0" encoding="UTF-8"?><?eclipse version="3.0"?><plugin><!-- Define primary TOC --> <extension point="org.eclipse.help.toc"> <toc file="toc.xml" primary="true" /> <!-- Define secondary TOCs --> <toc file="topics_GettingStarted.xml" /> <toc file="topics_Reference.xml" /> </extension><!– Define index file --> <extension point="org.eclipse.help.index"> <index file="Getting_started_idx.xml" /> <index file="Reference_idx.xml" /></extension>
Here, secondary ToCs are ones contained in this doc plug-in, that can be displayed in nested branches of the ToC
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Doc plug-in’s plugin.xml structure with index, contextual help
<?xml version="1.0" encoding="UTF-8"?><?eclipse version="3.0"?><plugin><!-- Define primary TOC --> <extension point="org.eclipse.help.toc"> <toc file="toc.xml" primary="true" /></extension><!– Define keyword index file --> <extension point="org.eclipse.help.index"> <index file="index.xml" /></extension><!– Define F1 context files --> <extension point="org.eclipse.help.contexts"> <contexts file="contexts.xml" plugin="com.lak.ui" /> </extension>
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
To learn more and locate expertise eclipse_tw Yahoo!Group Eclipse NewsPortal (
www.eclipse.org/newsportal/index.php) UA newsgroup: eclipse.platform.ua Also see eclipse.newcomer, eclipse.platform
Eclipse for Total Beginners (http://dev.eclipse.org/blogs/wayne/2007/07/25/eclipse-and-java-for-total-beginners/)
Eclipse Live! webinars (live.eclipse.org) Eclipse training (www.eclipse.org/users/)
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Official Eclipse pages Eclipse.org (www.eclipse.org) Eclipse.org Wiki (http://wiki.eclipse.org/Main_Page) Eclipse docs on the Web (www.eclipse.org/documentation/) Eclipse UA development team’s page (
www.eclipse.org/eclipse/platform-ua/main.html) Eclipse Documentation (when you’re a member of an Eclipse
open-source project. http://wiki.eclipse.org/index.php/Eclipse_Documentation)
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
You might be interested in “Adding Help Support to a Rich Client Platform (RCP) Application”
by Goldthorpe and Archer (Based on Eclipse 3.3, Written Oct. 2005. At Eclipse Corner Articles: http://www.eclipse.org/articles/)
“Writing Documentation and Help for Eclipse Projects and Plug-ins” (can be a little dated, good walk through of doc plug-in elements. www.keycontent.org/tiki-index.php?page=Eclipse%20Help%20System)
“An introduction to Eclipse for Microsoft® Visual Studio® users” (www.ibm.com/developerworks/opensource/library/os-eclipse-visualstudio/)
“The Heart of Eclipse” by Dan Rubel (Based on Eclipse 3.2. Written Oct. 2006. www.acmqueue.org/modules.php?name=Content&pa=showpage&pid=425&page=1)
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Reporting bugs/requesting new features Eclipse Bugzilla
For both reporting bugs (defects) and filing feature requests
Bugzilla home: https://bugs.eclipse.org/bugs/
Need to have a Bugzilla account to report bug/request feature
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Using Bugzilla
Create Bugzilla account
Report a bug Request something new
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Reporting a bugAs you go through the Bug Wizard’s questions, for reporting an Eclipse UA bug, choose: I am reporting a bug with = “Eclipse itself” Select the plugin/component = “Platform” On the final step page, Component = “User Assistance”
If reporting an Eclipse help doc bug, choose Component = “Doc”
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Entering a feature request1. Choose “Enter an
enhancement/feature request” on the Bugzilla home page.
2. Choose “Platform” link on the subsequent page.
3. Choose Component = “User Assistance” in the final request form.
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Eclipse is…
“Eclipse is an open source community whose projects are focused on building an extensible development platform, runtimes, and application frameworks for building, deploying and managing software across the entire software lifecycle.” (source: “New to Eclipse”, Eclipse Foundation, www.eclipse.org)
© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0
Legal notices Eclipse is a registered trademark of the Eclipse
Foundation. <oXygen/> is a registered trademark of SyncRO Soft Ltd. Sybase is a registered trademark of Sybase, Inc. OSGi is a trademark, registered trademark, or service
mark of the OSGi Alliance in the United States and other countries.
XMetal is a registered trademark of JustSystems, Corp. Microsoft, Windows, and Visual Studio are registered
trademarks of Microsoft Corporation in the United States, other countries, or both.
Other company, product, or service names may be trademarks or service marks of others.