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
