Home » Eclipse Projects » Platform - User Assistance (UA) » How to host Eclipse help on a server
|
| Re: How to host Eclipse help on a server [message #655262 is a reply to message #655256] |
Fri, 18 February 2011 20:29   |
 Jennifer Skiendzielewski
Messages: 35
Registered: January 2010
Location: Boulder, CO |
Member |
|
|
Wow. This is a very big question.  It's very close to how I use Eclipse Help though, so here are some places to start:
1. Download the Eclipse IDE and trim it down to just the help system. (There are instructions for this in the Eclipse documentation online).
2. You will need to create all of the required files (plugin.xml, helpdata.xml, maybe plugin_customizations.ini and fragment.xml), and modify some of the files that are in the Eclipse package (config.ini, bundles.info).
There's information about doing most of that here: http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse. platform.doc.isv/guide/ua.htm
(this is the section I found most useful, but it was still a bit opaque sometimes...) One extremely important point that it took days of trial and error to discover: Save all of the files you create as UTF-8. That little point might be obvious to a Java developer, but it escaped this writer for quite some time...
3. You'll probably want to run in Information Center mode, which seems to have the least documentation available-- but don't let that deter you! Most of the information carries over pretty well. We run that sort of implementation in several products, so I'll try to answer questions based on our experiences.
So I guess that's the place to start. Read that section of the help center and start experimenting. Post more questions as you come up with them.
|
|
| | |
| Re: How to host Eclipse help on a server [message #655280 is a reply to message #655270] |
Fri, 18 February 2011 23:00 |
Jennifer Skiendzielewski
Messages: 35
Registered: January 2010
Location: Boulder, CO |
Member |
|
|
Hi Thomas-
OK. Here are a couple of important answers:
1. When I say "trimming it down," Here's what I mean:
If the only part of the SDK that you want to use is the help system, you can delete the majority of the files in the SDK package, because you don't use them at all. I remember finding a topic online somewhere that explained how to carve the help system topics out of the SDK, but it involved setting up two project areas and a lot of manipulation inside eclipse.
I gave up on that method very quickly. Somewhere else I found a list of the files that you need for the help system, so I just went into the eclipse/plugins directory and deleted everything that wasn't on the list. It took a little work, but it was much easier. Apparently, I can't attach a screen capture here to show you the files I included... But I'll figure out a way to send it to you.
2. Based on #1 above, you shouldn't ever have to run the eclipse.exe and create a project at all.
Let me figure out a good way to send you the list of files you need and I'll respond again.
|
|
| | | | | |
| Re: How to host Eclipse help on a server [message #655562 is a reply to message #655296] |
Mon, 21 February 2011 18:56 |
Jennifer Skiendzielewski
Messages: 35
Registered: January 2010
Location: Boulder, CO |
Member |
|
|
Hi Thomas-
Once you have the file system set up that way, there are a few more files that you have to update and create. Here's my list, what the files do (as far as I can tell), and how to update them:
1. At the top of the directory structure, in the same directory as /eclipse: start.bat
-----This is a batch file that you can double click to start the eclipse help system (or that your developer can run when they start up their program, so the help starts at the same time). I usually copy this file and edit the copy. For me, the file includes one command that looks like this:
java -classpath eclipse/plugins/org.eclipse.help.base_3.4.0.v200909170800.ja r org.eclipse.help.standalone.Infocenter -eclipsehome eclipse -plugincustomization plugins\com.infoprint.aiw.base\plugin_customization.ini -port 15888 -refresh -command start -noexec -consoleLog
pause
You might need to update the version number after help.base. The -eclipsehome value should be ok.
The -plugincustomization value should point to the plugincustomtization.ini file that you include in your plugin. (explained later)
The -port value should be the port that you want to run the help system on. By default it's 8888.
The rest of the values should be OK.
2. /eclipse/configuration/config.ini
This is one of the configuration files for the help framework.
Update or add this line:
eclipse.product=plugin_name.helpProduct
Replace plugin_name with the directory name of the plugin you're adding for your help (for example: com.company.product) and keep .helpProduct at the end.
3. /eclipse/configuration/org.eclipse.equinox.simpleconfigurato r/bundles.info
My best understanding is that this file tells eclipse the names of all of the plugins that it's supposed to recognize. I think that, when you run the help system inside the eclipse platform, the "provisioning" system builds this file, but I've never had time to figure out how to make that work automatically for me. So I just edit this file and add a line for my plugins. So add a line that looks like this at the bottom:
com.company.product,1.1,file:plugins/com.company.product,4,f alse
Again, replace both occurrences of "company.product" with the name of the directory that you put your plugin in. The "1.1" is the version number of your plugin. I have NO idea what the "4" and "false" are for, but they seem to work, so I just leave them.
4. /eclipse/plugins
Create a directory to hold your plugin. The directory name should follow the eclipse naming conventions. So it should start with com, then should have your company name, division (if you're a large company), product name, and maybe an identifier.
For example, I use: com.infoprint.aiw.base for my base product (that's com.company.productID.base) and com.infoprint.aiw.rpt for one of the optional features that we provide.
5. /eclipse/plugins/[your new directory:
This is where you'll put your HTML files, your plugin.xml, and your toc.xml. You'll also create the plugin_customization.ini here.
After you copy the plugin.xml here, open it up and look for the <plugin> tag. Here's mine:
<plugin id="com.infoprint.aiw.base" name="InfoPrint ProcessDirector Information Center"
provider-name="InfoPrint Solutions Company"
version="2.1">
The value for "version" must match the version number that you put in the bundles.info file.
Next, look for an <extension> tag like this:
<extension id="helpProduct" point="org.eclipse.core.runtime.products">
<product name="InfoPrint ProcessDirector" application="" />
</extension>
The value of "name=" is what shows up in the title bar of the browser when you start the help system (with "Help - " in front of it), so you can put whatever you want here).
Save plugin.xml and close it. Remember, if you had to make changes to what came out of your CMS, you'll need to make them again...
Now, create a new text file called plugin_customization.ini and save it as UTF-8. There's a good amount of information in the online information that I sent to you about the different options you can include here. I find it a little difficult to decode sometimes, but it's possible.
Here are the contents of one of my plugin_customization.ini files. You can copy it and change the values to match yours:
# plugin_customization.ini
# sets default values for plug-in-specific preferences
# keys are qualified by plug-in id
# e.g., org.eclipse.ui/RECENT_FILES=10
# java.io.Properties file (ISO 8859-1 with "\" escapes)
# "%key" are externalized strings defined in plugin_customization.properties
# This file does not need to be translated.
# org.eclipse.ui/defaultPerspectiveId=org.eclipse.ui.resourceP erspective
org.eclipse.help.base/banner=/com.infoprint.aiw.base/banner. htm
org.eclipse.help.base/banner_height=30
org.eclipse.help.base/windowTitlePrefix=true
org.eclipse.help.base/linksView=false
org.eclipse.help.base/help_home=/com.infoprint.aiw.base/aiw0 000.html
org.eclipse.help/HELP_DATA=helpdata.xml
org.eclipse.help.base/locales=en de es fr it ja ko pt_BR ru zh zh_TW
org.eclipse.help.base/banner-- This is the html file that you want to use for the banner in the top frame of the help system. I just wrote a simple HTML page myself, with a background color and an image for our product name. So you can create a similar thing and put the file in your plugin directory. Then change this path to point to your file in your plugin directory. Interestingly, this path only needs to start with your plugin name-- it doesn't need to include any path information above that.
org.eclipse.help.base/banner_height-- the height of your banner, in pixels, I think. We wanted ours to be pretty narrow.
org.eclipse.help.base/windowTitlePrefix=true
Set this to True to make your product name show up in the title line of the browser.
org.eclipse.help.base/help_home
This is the path to the "title page" of your help system-- the page that you want to display when a user first opens the help. Again, this path only needs information starting with the directory name for your plugin, nothing above that.
org.eclipse.help/HELP_DATA
This is only useful if you have more than one toc.xml file. For example, my help system has a master ditamap that the plugin.xml comes from, then it has 8 ditamaps that generate the sections of my help (Overview, Configuring, Troubleshooting, Reference, etc). Each section displays as a separate "book" in the TOC panel.
I use this file to set the order that the books in the TOC panel display in. If you only have one toc.xml, you can remove this line.
org.eclipse.help.base/locales
Identifies the languages that my product is translated into and that I have help translations for. If you're going to have translations, we can get those set up once your eclipse help is up and running in one language. Just let me know-- that's a whole other set of instructions!
I think that's all you need for now... When you have all of those files in place and edited, go up to your start.bat file and double click it. Then, open your browser to this, inserting the port number that you chose in the start.bat file in place of [port_number]:
http://localhost:[portnumber]/help/index.jsp
You should see a frameset with your banner, your TOC, and the file you specified for the help home page. If you don't... well, that's where they debugging comes in.
To do any debugging, you'll have to stop the help system with the end.bat script. It doesn't need to be edited, just double click.
One last thing for now-- If you make any changes, go into /eclipse/configuration and delete EVERYTHING except config.ini and org.eclipse.equinox.simpleconfigurator/bundles.info. That forces the help system to update its configuration.
Whew. That's a lot of stuff, but hopefully, it'll get you going pretty quickly. Let me know if you get stuck.
Good luck!
Jennifer
|
|
| |
| Re: How to host Eclipse help on a server [message #655591 is a reply to message #655579] |
Mon, 21 February 2011 20:45 |
Jennifer Skiendzielewski
Messages: 35
Registered: January 2010
Location: Boulder, CO |
Member |
|
|
Hi again Thomas-
You are correct-- you do NOT have to create a plugin project in eclipse. You just have to create a directory in /eclipse/plugins and copy the output of your CMS into it.
As for help modes... Here is my understanding (with a liberal amount of opinion included):
1) Workbench mode
Used when your product can essentially be incorporated into the Eclipse workbench as a plugin-- meaning that users open the eclipse development environment and import your product into it. In that case, your product's help plugin gets added to the eclipse workbench's help system.
My guess is that this is not what you want, though it's the mode that has the most documentation and the most functionality.
2) Standalone help mode
Used when your product is a standalone product that's installed on individual user systems (like MS Word or Adobe Acrobat). The help system starts up when the product starts up and shuts down when the product is closed, and it too runs on the user's system. Only one person accesses the help system, and it's only available from inside the product.
In this case, when you launch the help, it launches in a browser window, but it doesn't have a menu bar or any button bars at the top. It's just a title bar and the help system frames.
This might be the model you're looking for.
3) InfoCenter mode
Used in a couple of different situations:
A) When you only want to provide an online documentation library, without a product being involved at all. We do this on our corporate Web site, because it seemed to be a good way to provide our most up-to-date user documentation to our customers.
B) When your product is server-based, so it's installed in a central location and users access it from different places. In this case, you want to install the help on that centralized server with the product and let all of the users access it from there.
3B is how my product works. Our product is server-based and has a Web UI as the front end. The Web UI has a Help link that opens another window/tab to display the help. I believe the Help link is generated dynamically, so it uses the same hostname/IP address that our product UI uses (not localhost).
The command that starts our product starts the help system too, so the help system is running whenever the product is active. Users can bookmark the help system in their browsers and open it whenever they want-- they don't have to have the product UI/web page open. The help is displayed in a full browser, with all of the bars at the top, so it looks like any other web page.
This might also be the option you're looking for.
The command in start.bat changes whether you want to use option 2 or option 3. The one I gave you is for option 3. If you want to use option 2, you change this:
org.eclipse.help.standalone.Infocenter
to this:
org.eclipse.help.standalone.Help
As for accessing the help from the help menu... I'm pretty sure you can access either 2 or 3 from the help menu. Your developers just need to know where to find the help and create the link between the menu and the help system correctly.
Good luck again... and I'm glad this information is useful to someone! It was hard-won.
Have a good afternoon!
Jennifer
|
|
| | | | | | | | | | | | | | | | | | | | | | | | | |
Goto Forum:
Current Time: Mon Dec 30 14:32:40 GMT 2024
Powered by FUDForum. Page generated in 0.04142 seconds |
] 
Search
Help
Register
Login
Home
