Subject: POW - populate help menu
bob@abisource.com
Date: Wed Jun 21 2000 - 13:14:07 CDT
POW -- Help Menu
We've been so busy with the 0.7.10 release that we haven't had time to organize a POW in a while. This one should be relatively easy: populate the help menu.
Christophe Caron, Pierre Abbat, and Ash have done a great job creating the help file contents. Now we need to implement the help menu functions that go with them. There are two major reasons for this push to populate the help menu. First, it's the place that most normal users go when they need help. Second, it gives the AbiSource project a place to do a little marketing. :-)
Of course, we want to do this in a cross platform way. HTML appears to be the best fit for the job, and the existing work is already formatted in HTML. The help menu should consist of menu items which will launch various URLs in the user's preferred web browser. Some of these URLs will point to documents on the local machine (these documents are installed with AbiWord), while others will direct people to the AbiSource web site. The AbiSource web site currently only has placeholders for the help content, which we will host in time for the next release.
To complete this POW, you need to familiarize yourself with how AbiWord launches a web browser to handle URLs. Sample invocation code to do this is available in the About... dialog box (abi/src/af/xap/[unix,win]/xap_[Unix,Win32]Dlg_About.cpp). These implementations call the xap_[platform]Frame class's "openURL" function to handle the browser dispatch. The current Unix implementation is less-than-desirable, and should be replaced with a more appropriate browser launch.
Specific steps for this dialog:
===============================
1. You will have to figure out where AbiWord is installed (we'll refer to this as the "AbiSuiteLibDir"). On Unix, this is the "prefix" you gave to the "make install" target. AbiWord defaults to installation in /usr/local/AbiSuite/. If you've installed the Red Hat package of AbiWord, this location will be /usr/share/abisuite/. If you're running your own builds of AbiWord from a development source tree, this location will be determined by the $ABISUITE_HOME environment variable. On Windows, this location is simply where you directed the AbiWord installation program to install AbiWord.
2. Add the following menu items to the AbiWord help menu, and name the edit method functions that will invoke the following URLs ("About AbiWord" remains the same):
Contents <AbiSuiteLibDir>/help/en-US/comindex.html
Index <AbiSuiteLibDir>/help/en-US/index.html
Search http://www.abisource.com/users/search.html
Check Version http://www.abisource.com/users/check_version.phtml?[version_number]
------------- (menu separator)
About AbiWord (Remains Unchanged)
About Open Source <AbiSuiteLibDir>/help/en-US/aboutos.html
To do so, you'll need to update the usual set of menu files:
abi/src/wp/ap/xp/ap_Menu_ActionSet.cpp
abi/src/wp/ap/xp/ap_Menu_Id.h
abi/src/wp/ap/xp/ap_Menu_LabelSet_*.h
abi/src/wp/ap/xp/ap_Menu_Layouts_MainMenu.h
3. Implement the edit method functions to invoke the URLs named in step 2. These functions will reside in the ap_EditMethods class (in abi/src/wp/ap/xp/ap_EditMethods.[cpp,h]). As of the writing of this POW, ap_EditMethods.cpp, line 1536, contains the beginning of the "dlgAbout" menu item implementation. You might copy this function for each new item you've added, and change its implementation to invoke the frame's "openURL" function.
Remember, when building any local URL strings, you'll need to resolve "AbiSuiteLibDir" to its actual run-time value. XAP_App::getAbiSuiteLibDir() will return the local path to this directory (in the format of your current filesystem).
Extra Credit
===============================
If you are really on the ball, your implementation of these menu items would take a look at the current language AbiWord is running in, by examining the current preferences settings. You can use that string to build local and remote URL strings that point to documentation for that language. For example, if the current menu string language setting is "fr-FR", the Help menu's Index item would reference "<AbiSuiteLibDir>/help/fr-FR/comindex.html". There exists a problem with this simple implementation when a help text translation is not available for the current language setting. Perhaps a quick "directory-exists" check could be performed for local resources (using the value of "AbiSuiteLibDir") before falling back to "en-US" in the case of "not found."
Enjoy!
Bob
PS: For more background on the whole POW / ZAP / SHAZAM concept, see the
following introduction:
http://www.abisource.com/mailinglists/abiword-dev/99/September/0097.html
This archive was generated by hypermail 2b25 : Wed Jun 21 2000 - 13:14:08 CDT