Using CSH API to switch between online and offline help

Many a times technical writers have a requirement to provide both the online and offline help content with their application. While offline content has the advantage of being available even if user has no network connectivity, online content has a lot of other advantages. Technical writers can keep updating online help content and incorporate fixes in documentation. Also, usage of online help content by users can be tracked and used to enhance the quality of documentation.

So to get the best of both the worlds, technical writers would like their application help to check for network connectivity and then launch online/offline help accordingly.

This way of integrating offline/online help is popularly known as “Airplane Help”.

Using RoboHelp, technical writers can achieve this very easily with following configuration:

• Online WebHelp Pro hosted on RoboHelp Server, acting as the primary help system
  RoboHelp Server logs usage of help content and provides many useful reports, e.g.:
  • Frequently Viewed Topic
  • Frequently Searched Terms
  • Frequently Accessed CSH
• Offline WebHelp installed with application, acting as the backup help system in case of no network connectivity
• CSH API to launch context sensitive help from application

C++ CSH API provided with RoboHelp is installed with RoboHelp at <RoboHelp Install Location>\CSH API\C++. To enable context sensitive help calls from your application, technical writers need to provide this VC++ project to the application developers who need to include it in their application.

Let’s consider following configuration:

• Online WebHelp Pro hosted at http://myhelpserver/robohelp/server?project=myApp
• Offline WebHelp available at C:\Program Files\myApp\help\help.htm

Before making any help calls from the application, application need to define the association between the offline and online help content. CSH API stores this association and when actual help call is made, it checks to see if the primary/online help system is available and if yes then help is served from primary/online help system. Otherwise help is served from backup/offline help content.

CSH API provides an API for associating primary/online help with backup/offline help:

// [in] a_pszPrimaryHelpSource - primary server-based help system
// [in] a_pszBackupHelpSource  - backup help system
void RH_AssociateOfflineHelp(const _TCHAR * a_pszPrimaryHelpSource, const _TCHAR * a_pszBackupHelpSource);

So for the above example, application developer will need to make the following call:

RH_AssociateOfflineHelp("http://myhelpserver/robohelp/server?project=myApp", "C:\Program Files\myApp\help\help.htm");

Now, to launch context sensitive help for any ID(for example 5), developer should make a call like this one:

RH_ShowHelp(GetSafeHwnd(),"http://myhelpserver/robohelp/server?project=myApp", HH_HELP_CONTEXT, (DWORD)5);

This API first checks the availability of help system provided in the RH_ShowHelp API (i.e. http://myhelpserver/robohelp/server?project=myApp) and if it’s available, shows context sensitive help from there. If the online help system is unavailable, then the API checks if any backup help system was associated with this help system and in our case it was (C:\Program Files\myApp\help\help.htm). In that case, the help is displayed from backup help system.

Tulika Garg, Adobe RoboHelp Team