A. Sources of Routine Info

In 4.2 Routine Info and 4.4 Completion we showed how IDLWAVE displays the calling sequence and keywords of routines, and completes routine names and keywords. For these features to work, IDLWAVE must know about the accessible routines.

A.1 Routine Definitions		Where IDL Routines are defined.
A.2 Routine Information Sources		So how does IDLWAVE know about...
A.3 Library Catalog		Scanning the Libraries for Routine Info
A.4 Load-Path Shadows		Routines defined in several places
A.5 Documentation Scan		Scanning the IDL Manuals

A.1 Routine Definitions

Routines which can be used in an IDL program can be defined in several places:

1. Builtin routines are defined inside IDL itself. The source code of such routines is not available.
2. Routines which are part of the current program, are defined in a file explicitly compiled by the user. This file may or may not be located on the IDL search path.
3. Library routines are defined in files located on IDL's search path, and will not need to be manually compiled. When a library routine is called for the first time, IDL will find the source file and compile it dynamically. A special sub-category of library routines are the system routines distributed with IDL, and usually available in the `lib' subdirectory of the IDL distribution.
4. External routines written in other languages (like Fortran or C) can be called with CALL_EXTERNAL, linked into IDL via LINKIMAGE, or included as dynamically loaded modules (DLMs). Currently IDLWAVE cannot provide routine info and completion for such external routines.

A.2 Routine Information Sources

To maintain the most comprehensive information about all IDL routines on a system, IDLWAVE collects data from many sources:

1. It has a builtin list with the properties of the builtin IDL routines. IDLWAVE 4.15 is distributed with a list of 1324 routines and 6129 keywords, reflecting IDL version 5.5. This list has been created by scanning the IDL manuals and is stored in the file `idlw-rinfo.el'. See section A.5 Documentation Scan, for information on how to regenerate this file for new versions of IDL.

2. It scans all buffers of the current Emacs session for routine definitions. This is done automatically when routine information or completion is first requested by the user. Each new buffer and each buffer which is saved after making changes is also scanned. The command C-c C-i (idlwave-update-routine-info) can be used at any time to rescan all buffers.

3. If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will query the shell for compiled routines and their arguments. This happens automatically when routine information or completion is first requested by the user, and each time an Emacs buffer is compiled with C-c C-d C-c. Though rarely necessary, the command C-c C-i (idlwave-update-routine-info) can be used to update the shell routine data.

4. IDLWAVE can scan all or selected library source files and store the result in a file which will be automatically loaded just like `idlw-rinfo.el'. See section A.3 Library Catalog, for information how to scan library files.

Loading routine and catalog information is a time consuming process. Depending on the system and network configuration it can take up to 30 seconds. In order to minimize the waiting time upon your first completion or routine info command in a session, IDLWAVE uses Emacs idle time to do the initialization in 5 steps, yielding to user input in between. If this gets into your way, set the variable idlwave-init-rinfo-when-idle-after to 0 (zero).

User Option: idlwave-init-rinfo-when-idle-after (10)

Seconds of idle time before routine info is automatically initialized.

User Option: idlwave-scan-all-buffers-for-routine-info (t)

Non-nil means scan all buffers for IDL programs when updating info.

User Option: idlwave-query-shell-for-routine-info (t)

Non-nil means query the shell for info about compiled routines.

User Option: idlwave-auto-routine-info-updates

Controls under what circumstances routine info is updated automatically.

A.3 Library Catalog

IDLWAVE can extract routine information from library modules and store that information in a file. To do this, the variable idlwave-libinfo-file needs to contain the path to a file in an existing directory (the default is "~/.idlcat.el"). Since the file will contain lisp code, its name should end in `.el'. Under Windows and MacOS, you also need to specify the search path for IDL library files in the variable idlwave-library-path, and the location of the IDL directory (the value of the !DIR system variable) in the variable idlwave-system-directory, like this(7):

(setq idlwave-library-path '("+c:/RSI/IDL54/lib/" "+c:/user/me/idllibs" )) (setq idlwave-system-directory "c:/RSI/IDL54/")

Under GNU and UNIX, these values will be automatically inferred from an IDLWAVE shell.

The command M-x idlwave-create-libinfo-file can then be used to scan library files. It brings up a widget in which you can select some or all directories on the search path. If you only want to have routine and completion info of some libraries, it is sufficient to scan those directories. However, if you want IDLWAVE to detect possible name conflicts with routines defined in other libraries, the whole pass should be scanned.

After selecting directories, click on the `[Scan & Save]' button in the widget to scan all files in the selected directories and write the resulting routine information into the file idlwave-libinfo-file. In order to update the library information from the same directories, call the command idlwave-update-routine-info with a double prefix argument: C-u C-u C-c C-i. This will rescan files in the previously selected directories, write an updated version of the libinfo file and rebuild IDLWAVE's internal lists. If you give three prefix arguments C-u C-u C-u C-c C-i, updating will be done with a background job(8). You can continue to work, and the library catalog will be re-read when it is ready.

A note of caution: Depending on your local installation, the IDL library can be very large. Parsing it for routine information will take time and loading this information into Emacs can require a significant amount of memory. However, having this information available will be a great help.

User Option: idlwave-libinfo-file

File for routine information of the IDL library.

User Option: idlwave-library-path

IDL library path for Windows and MacOS. Not needed under Unix.

User Option: idlwave-system-directory

The IDL system directory for Windows and MacOS. Not needed under Unix.

User Option: idlwave-special-lib-alist

Alist of regular expressions matching special library directories.

A.4 Load-Path Shadows

IDLWAVE can compile a list of routines which are defined in several different files. Since one definition will hide (shadow) the others depending on which file is compiled first, such multiple definitions are called "load-path shadows". IDLWAVE has several routines to scan for load path shadows. The output is placed into the special buffer `*Shadows*'. The format of the output is identical to the source section of the routine info buffer (see section 4.2 Routine Info). The different definitions of a routine are listed in the sequence of likelihood of use. So the first entry will be most likely the one you'll get if an unsuspecting command uses that routine. Before listing shadows, you should make sure that routine info is up-to-date by pressing C-c C-i. Here are the different routines:

M-x idlwave-list-buffer-load-path-shadows

This commands checks the names of all routines defined in the current buffer for shadowing conflicts with other routines accessible to IDLWAVE. The command also has a key binding: C-c C-b

M-x idlwave-list-shell-load-path-shadows.

Checks all routines compiled under the shell for shadowing. This is very useful when you have written a complete application. Just compile the application, use RESOLVE_ALL to compile any routines used by your code, update the routine info inside IDLWAVE with C-c C-i and then check for shadowing.

M-x idlwave-list-all-load-path-shadows

This command checks all routines accessible to IDLWAVE for conflicts.

For these commands to work properly you should have scanned the entire load path, not just selected directories. Also, IDLWAVE should be able to distinguish between the system library files (normally installed in `/usr/local/rsi/idl/lib') and any site specific or user specific files. Therefore, such local files should not be installed inside the `lib' directory of the IDL directory. This is also advisable for many other reasons.

Users of Windows and MacOS also must set the variable idlwave-system-directory to the value of the !DIR system variable in IDL. IDLWAVE appends `lib' to the value of this variable and assumes that all files found on that path are system routines.

Another way to find out if a specific routine has multiple definitions on the load path is routine info display (see section 4.2 Routine Info).

A.5 Documentation Scan

IDLWAVE derives it knowledge about system routines from the IDL manuals. The file `idlw-rinfo.el' contains the routine information for the IDL system routines. The Online Help feature of IDLWAVE requires ASCII versions of some IDL manuals to be available in a specific format (`idlw-help.txt'), along with an Emacs-Lisp file `idlw-help.el' with supporting code and pointers to the ASCII file.

All 3 files can be derived from the IDL documentation. If you are lucky, the maintainer of IDLWAVE will always have access to the newest version of IDL and provide updates. The IDLWAVE distribution also contains the Perl program `get_rinfo' which constructs these files by scanning selected files from the IDL documentation. Instructions on how to use `get_rinfo' are in the program itself.

One particularly frustrating situation occurs when a new IDL version is released without the associated documentation updates. Instead, a What's New file containing new and updated documentation is shipped alongside the previous version's reference material. The `get_rinfo' script can merge this new information into the standard help text and routine information, as long as it is pre-formatted in a simple way. See `get_rinfo' for more information.