$Id: idl_acrobat_plugin.README,v 1.1 2003/03/17 20:07:47 ali Exp $ This file explains the Unix IDL plugin for Adobe Acrobat Reader, gives information on customizing its behavior, and troubleshooting advice. ------------------------------------------------------------------------------ TABLE OF CONTENTS ------------------------------------------------------------------------------ 1) What is an Acrobat Reader Plugin? 2) What is the IDL Acrobat Reader Plugin? 3) How Does The IDL Acrobat Reader Plugin Work? 4) The Role Of The idl_acrobat_plugin.conf File 5) Plugin Versions, and the "Plugin Version Heuristic" 6) Troubleshooting The Acrobat Reader Plugin ------------------------------------------------------------------------------ 1) What Is An Acrobat Reader Plugin? ------------------------------------------------------------------------------ The Adobe Acrobat Reader is a free program distributed by Adobe that renders documents in the Portable Document Format (PDF). Acrobat Reader has been designed by Adobe with an extension mechanism called "plugins". A plugin is a sharable library (also called a DLL by Microsoft Windows users) that is loaded by Acrobat Reader when it starts. Such plugins communicate with Acrobat Reader via a series of APIs supplied by Adobe Reader, which collectively are known as the Acrobat SDK (Software Development Kit). Plugins can supply arbitrary new abilities to Acrobat Reader, and allow third parties to customize it for their own purposes, without Adobe's direct involvement. There are business that specialize in the development and sales of Acrobat plugins. IDL users may recognize this use of shared libraries as the same general principle underlying IDL's CALL_EXTERNAL, LINKIMAGE, and DLM facilities. ------------------------------------------------------------------------------ 2) What Is The IDL Acrobat Reader Plugin? ------------------------------------------------------------------------------ Unix IDL uses the free Adobe Acrobat Reader to supply online help via the ? executive command and the ONLINE_HELP procedure. The stock Acrobat Reader is a standalone application that operates only in response to direct user interaction via its user interface. This is sufficient for displaying documentation. However, IDL's online support becomes much more convenient given the ability for IDL to cause Acrobat Reader to load specified files, and to position them to desired pages. The IDL Acrobat Reader Plugin is a plugin for the free Acrobat Reader, written by Research Systems for IDL, and included as a standard part of a Unix IDL distribution. It allows IDL to tell a copy of Acrobat Reader started by the '?' or ONLINE_HELP procedure which file(s) to display, and which page within those files. When you type a command such as: IDL> ? FFT it is the IDL Acrobat Reader Plugin that causes the correct pdf file (refguide.pdf) to be loaded by Acrobat Reader, and to be positioned on the page describing the FFT function. You can tell which platforms IDL has plugin support for by looking in the platform specific bin directories of your IDL distribution for files named idl_acrobatX_plugin.api, where X is a number giving the Acrobat Reader version supported by the plugin (e.g. 4, or 5). These files are the IDL Acrobat plugins for that platform, and their presence means that IDL supports the plugin on that platform for those specific versions of Acrobat Reader. If an IDL Acrobat Reader plugin is not present, the plugin is not available on that platform. IDL still uses Acrobat Reader to display help on such platforms, but without the ability to change the loaded file or displayed page. ------------------------------------------------------------------------------ 3) How Does The IDL Acrobat Reader Plugin Work? ------------------------------------------------------------------------------ When you execute the ? executive command or the ONLINE_HELP procedure under Unix IDL, IDL takes the steps discussed in this section in order to use the IDL Acrobat Reader Plugin. Please note that many of these steps can be modified or disabled by altering parameters found in the idl_acrobat_plugin.config file, found in the help subdirectory of the IDL distribution. This discussion assumes that the contents of idl_acrobat_plugin.config have not been modified locally, and are as they were shipped by Research Systems. The IDL plugin config file is described in more detail in Section 4 (The Role Of The idl_acrobat_plugin.conf File), below. 1) Determine the version of Acrobat Reader in use on the system. This is a heuristic operation, described in more detail in Section 5 (Plugin Versions, and the "Plugin Version Heuristic") below. 2) Check in the platform specific bin subdirectory of the IDL distribution for an IDL Acrobat plugin of the correct version. If no such plugin is found, then IDL will run Acrobat Reader without a plugin. 3) Ensures that the user has a directory named "plug_ins" in their home directory (~/plug_ins), and that a copy of the IDL plugin is found in that directory. The plugin is copied it from the IDL bin directory if necessary. A file named README_RSI_IDL is also created in this location, giving the user information on what has been done. 4) IDL creates a Unix pipe to use as a command channel to the IDL plugin. It then starts a copy of the Acrobat Reader. 5) To establish whether the IDL plugin is working in the new Acrobat Reader process, IDL sends a handshake request to the Acrobat Reader plugin via the command pipe. If it receives a positive response from the plugin within 30 seconds, it knows that the plugin is active and ready for use. 6) Acrobat Reader starts. During initialization, it attempts to load all plugins in the users ~/plug_ins directory. Upon loading the IDL plugin, the IDL plugin reads the handshake request sent by IDL, and answers it. If the IDL plugin should fail to load for any reason, this handshake is not completed, and IDL's handshake request will time out and fail. 7) If the IDL handshake with the plugin is successful, IDL proceeds to send file and position requests to Acrobat Reader. If not, IDL issues an error ("IDL Acrobat plugin did not respond as expected"), and kills the Acrobat Reader process. In general, this is a reliable process and IDL's use of the plugin to control Acrobat Reader is transparent to the user. Those problems that do occur are almost always due to the heuristic process used to determine the version of Acrobat Reader in use, as discussed in Section 5 (Plugin Versions, and the "Plugin Version Heuristic") below. ------------------------------------------------------------------------------ 4) The Role Of The idl_acrobat_plugin.conf File ------------------------------------------------------------------------------ The idl_acrobat_plugin.conf file found in the help subdirectory of a Unix IDL distribution is used to configure IDL's use of the IDL Acrobat Reader plugin. Specifying these parameters in a text file rather than being hardwired in the IDL program allows the end user to modify how things work, should that become necessary. In general, the default values of the config file should not be altered by end users. One important exception to this advice is that modifying the config file can be important when resolving problems with the plugin. For a more detailed explanation of the parameters set by idl_acrobat_plugin.conf, please read the comments found in that file. The options found in idl_acrobat_plugin.conf fall into one of the following categories: [Command Used To Invoke Acrobat Reader] When IDL wants to start Acrobat Reader, it uses the command given by the ACROREAD parameter. On most Unix systems, this command is "acroread". However, some platforms (e.g. Mac OS X) use a different command. The ability to alter this command can be useful in certain circumstances, but in general the value set by Research Systems should not be altered. [Controlling Plugin Use] There are parameters that control how IDL uses the Acrobat Reader Plugin. In general, the default values supplied by RSI should be satisfactory for most uses. However, there may be situations in which you need to alter them in order to make the plugin work reliably on your system. See Section 6 (Troubleshooting The Acrobat Reader Plugin) below for more details on this. The parameters that control plugin use are: TIMEOUT - When IDL starts Acrobat Reader, it immediately sends a handshake request to the IDL plugin via their shared command pipe. TIMEOUT specifies the number of seconds that IDL should wait for a response before it decides that the plugin has failed. This number needs to be long enough to allow Acrobat Reader to get started, even on a slow machine, but small enough that IDL does not appear to be hung. You should not need to adjust the default value unless your system is extremely slow. DISABLE_PLUGIN - An option of last resort. If you are completely unable to get the IDL plugin working, you can uncomment this line in the config file to tell IDL not to even try to use the plugin. Acrobat Reader will function in this mode, although IDL will not be able to load files or change the displayed page. If you resort to this, please file a bug with Research Systems so that we can resolve the underlying problem and fix it for a future release. Please note that there are some platforms for which the IDL Acrobat plugin is not supported. There is no need to set DISABLE_PLUGIN for these platforms. The lack of a plugin file in the IDL platform specific bin directory is sufficient to tell IDL not to attempt to use a plugin. DISABLE_PLUGIN_HOMEINSTALL - In rare cases, you may wish to disable IDL's efforts to copy a plugin into your ~/plug_ins directory. In this case, you can uncomment the DISABLE_PLUGIN_HOMEINSTALL line in the plugin config file. Note that this does not disable IDL's attempts to use the plugin --- only the copying of the plugin before trying to use it. If you uncomment DISABLE_PLUGIN_HOMEINSTALL, you must manually arrange for the correct plugin to be copied from the IDL platform dependent bin subdirectory, to one (not both) of the following locations: [~/plug_ins] The plug_ins subdirectory of the user's home directory. Each IDL user must do this independently of the others. [Acrobat Plugin Directory] Within the Acrobat Reader installation on your system, there is a plug_ins subdirectory where Adobe installs their own plugins. If you copy the IDL plugin here, it will be available to all of your users. In general, you should allow IDL to set up your ~/plug_ins directory for you. PLUGIN_DEFAULT_VERSION Before IDL starts, it must decide which version of Acrobat Reader is going to be used. To do this, it uses the process, described in Section 5 (Plugin Versions, and the "Plugin Version Heuristic"). If this heuristic is successful, the version it determines is used. If not, then IDL does the following: 1) Issues a warning message informing the user that it has failed to figure out the version of Acrobat Reader in use. 2) Use the value of PLUGIN_DEFAULT_VERSION as the version of Acrobat Reader to use. Hence, PLUGIN_DEFAULT_VERSION provides a last chance guess at the Acrobat Reader version in use. You may need to change this default, as described in Section 6 (Troubleshooting The Acrobat Reader Plugin) if this guess is wrong for your system. DISABLE_PLUGIN_VERSION_HEURISTIC Uncomment this parameter to disable IDL's heuristic attempt to figure out the version of Acrobat Reader in use. In this case, the value of PLUGIN_DEFAULT_VERSION determines the version IDL will attempt to support, and you must ensure it is set correctly for your system. [PDF File Defaults] There are parameters that specify defaults for the the files that Acrobat Reader should load under certain circumstances, such as the default pdf file to display if a requested topic is not found. These parameters should not be modified locally, as IDL's help system depends on them being as set by RSI. These items are parameters so that RSI does not have to rebuild the plugins in order to alter these defaults when new versions of IDL are released. They are not expected to be changed otherwise. ------------------------------------------------------------------------------ 5) Plugin Versions, and the "Plugin Version Heuristic" ------------------------------------------------------------------------------ Normally, IDL users need not be concerned with plugin versions. However, if you are encountering "IDL Acrobat plugin did not respond as expected" errors when you try to display online help, the information in this section should provide you with the information necessary to understand the troubleshooting advice given in Section 6 (Troubleshooting The Acrobat Reader Plugin). The IDL Acrobat Reader Plugin must be matched to the version of Acrobat Reader in use on your system. The plugin for a given version of Acrobat Reader cannot be used with other versions of Acrobat Reader. Attempts to do so will not work, and often cause Acrobat Reader to issue undesirable error message dialogs on the user's screen. The task of determining which version of Acrobat Reader is in use is complicated by the following: - IDL cannot assume Acrobat Reader is installed in any specific location (e.g. /usr/local). The only assumption is that the command used to start Acrobat Reader (usually acroread) is found via the user's PATH environment variable, in the same manner used by the Unix shell to locate commands. IDL cannot, therefore, examine the Acrobat Reader installation in order to determine its version. - The Acrobat Reader command does not have any command options for querying its version (i.e. "acroread -v"). - The Acrobat Reader ~/plug_ins directory has no version structure (i.e. A different location for plugins designed for different Acrobat Reader versions). Hence, the IDL plugin copied here *must* be the correct one for the version of Acrobat Reader being used. These constraints eliminate the most obvious ways in which IDL might determine the version of Acrobat Reader. There is, however, something that IDL *can* use: The "acroread" command used to start Acrobat Reader is always a shell script wrapper around the real binary executable, the this shell script always contains a line starting with "ver=", such as: ver=5.0.6 IDL therefore locates the Acrobat Reader command (given by the ACROREAD parameter in the idl_acrobat_plugin.config file), reads it, and locates the "ver=" line. If this works, the version specified by the script is used. If it fails, IDL issues a warning message saying so, and takes the value of PLUGIN_DEFAULT_VERSION from the plugin config file as the version of Acrobat Reader to use. We call this the "Plugin Version Heuristic", because it almost always gives the correct answer, but it is not guaranteed to. Adobe has been very consistent about the format of their shell script for years (we have verified this for versions 3, 4, and 5 of Acrobat Reader), and the tasks carried out by this shell script are complex enough that the possibility of a user running the underlying Acrobat Reader executable directly instead of via the shell script are nil. Hence, the "Plugin Version Heuristic" works reliably for those sites that install Acrobat Reader in the usual way, without local modifications. A problem arises at user sites that use their own locally supplied wrapper shell scripts in front of the Adobe supplied one. There are many reasons why a site might do this, the most obvious being that they have a heavily networked environment with different types of Unix computer (Solaris, Linux, HP, Irix, etc), and they want a common "acroread" command that takes care of running the correct one for the user's current system. The problem these wrapper scripts pose for IDL is that it cannot tell that this is not the Adobe supplied script. IDL parses the file, fails to find the "ver=" line, and therefore fails to determine the version of Acrobat Reader. This causes it to print a warning message. If the value of PLUGIN_DEFAULT_VERSION is the right one for your system, the plugin will work. If the value of PLUGIN_DEFAULT_VERSION is wrong, you will get the "IDL Acrobat plugin did not respond as expected" error 30 seconds later. ------------------------------------------------------------------------------ 6) Troubleshooting The Acrobat Reader Plugin ------------------------------------------------------------------------------ If you are having problems with the IDL Acrobat Reader Plugin, this section provides advice on things to try in order to solve them. Following are some common issues, and possible answers for them. If these suggestions fail to help, please contact IDL support for help in diagnosing the problem. 1) Online Help Works Without Error, But The Plugin Is Not Used. This means that IDL did not try to use the plugin on your system. Here are some things to check: - Check the idl_acrobat_plugin.config file found in the help subdirectory of the IDL distribution. In that file, make sure the DISABLE_PLUGIN and DISABLE_PLUGIN_HOMEINSTALL parameters have not been uncommented. - Check the platform dependent bin subdirectory of the IDL distribution for files named idl_acrobatX_plugin.api, where X is a number giving the Acrobat Reader version supported by the plugin (e.g. 4, or 5). These are the IDL plugin files. If your IDL installation lacks these files, the IDL Acrobat Reader plugin is not supported on your platform. - If in the above step, you found IDL plugin .api files, check the version of Acrobat Reader you are using (available from the Acrobat Reader Help menu) and make sure an IDL plugin of the correct version exists. If not, then the IDL plugin is not supported for the version of Acrobat Reader you are trying to use. Possible workarounds might be to use a different version of Acrobat Reader. New releases of IDL track new Acrobat Reader, versions so another possibility might be to upgrade to a newer version of IDL. 2) Online help issues an "unable to determine version" error, after which the IDL plugin may or may not work correctly. The "Unable to determine the version of Acrobat Reader in use on this system" error occurs when the "Plugin Version Heuristic" fails to determine the version of Acrobat Reader in use on your system. This process is discussed above in Section 5 (Plugin Versions, and the "Plugin Version Heuristic"). If IDL is unable to determine the version of Acrobat Reader it is using, it is forced to use a default, given by the PLUGIN_DEFAULT_VERSION parameter in the idl_acrobat_plugin.config file found in the help subdirectory of the IDL distribution. Since this amounts to nothing more substantial than a guess, IDL issues the warning message to alert you to the situation. It then attempts to use the IDL plugin corresponding to the version of Acrobat Reader given by the PLUGIN_DEFAULT_VERSION parameter. If the value of PLUGIN_DEFAULT_VERSION is correct, the IDL plugin will work despite the warning message. If the value of PLUGIN_DEFAULT_VERSION is wrong, you will receive a second "IDL Acrobat plugin did not respond as expected" error 30 seconds later, and IDL will kill the Acrobat Reader program. The solution in this case is to edit the idl_acrobat_plugin.config file found in the help subdirectory of your IDL distribution, as follows: - Uncomment the DISABLE_PLUGIN_VERSION_HEURISTIC line. This tells IDL not to try and figure out the version, but to simply use the value given by PLUGIN_DEFAULT_VERSION. - If necessary, change PLUGIN_DEFAULT_VERSION so that it agrees with the version of Acrobat Reader you are using. Please note that if you disable the version heuristic, IDL will be unable to gracefully detect and use different versions of Acrobat Reader, but only the version that you hard wired in idl_acrobat_plugin.config. The easiest solution to this is to standardize on a single version of Acrobat Reader.