View source for KwikINF (Quick Information Access into Online References)

''by [[Paul Brightly]]''

One of the most time-consuming efforts in developing code is locating and accessing the correct API Reference. These references come in both hard- and soft-copy. Yet, there are drawbacks to each. Using hard-copy, you can end up with a cluttered desk; soft-copy requires you to identify the correct information object on your desktop (most likely buried several folders deep). With softcopy, there is the additional dilemma that once you find the information object, you must then search through the contents or do a string search to find the item you need.

Enter KwikINF. KwikINF lets you look up an API, while editing source code, with the cursor sitting on the API in question. It is a utility that uses keyboard monitors in full-screen sessions and a system message queue hook in PM to detect user-defined hot-key sequences. Pressing this key, extracts the text string under the cursor (presumably an API call) and launches the appropriate online reference, displaying help on that API.

The KwikINF utility comes with the OS/2 2.1 Developer's Toolkit (that is available on your Developer Connection CD-ROM). Look for it in the online tools reference, as well as the toolkit desktop folder.

Launching online books lets your editor be run in full-screen, a VIO/AVIO window, MLE, or PM window. Unfortunately, in a graphical PM window, we can't extract the word under the cursor, because it's a bitmap and we don't have access to the string used to create it. WIN-OS2 sessions aren't monitored at all.

KwikINF determines which online reference to launch by using an index table that maps APIs to the books in which they reside. This mapping is specified by index files that are shipped with the OS/2 Developer's Toolkit as well as the C Set++ product.

==Interface==
Start KwikINF from a command prompt by typing KwikINF. If you have the 2.1 toolkit installed, a corresponding program object is created in the Toolkit information folder. Once started, the configuration menu is minimized to an icon on your desktop. You can configure the tool by double-clicking on this icon.

The configuration screen in ''Figure 1'' lets you change the behavior of KwikINF. The Activation Key Sequence (hot-key) activates KwikINF from any session. You can change the default (Alt+Q) to one of several other choices if you want. If you edit source c ode in a full-screen session, you will want to specify how many full-screen sessions KwikINF should monitor for the hot-key. You can choose a default book to be searched. Lastly, and I think most useful, you can decide what happens when you hit the hot-key. If you prefer, it will always show the search window in ''Figure 2''. This is useful if you need to choose which book to search every time you want help. But if you're getting help on an API that's specified in the index files, it's faster to bypass the search window. KwikINF determines the correct .INF file and launches it with the text under your cursor. However if you misspell the API, an error message will appear, and control will be returned to the originating window.

[[Image:KwikINF-Fig-1.png]]

''Figure 1. Configuration Screen''

The search window in ''Figure 2'' lets you specify the search-text and the book to be searched. This is less convenient than the bypass method previously described. But, it is required if you press the hot-key sequence from a graphical editor. If you use a graphical editor which has the appropriate macro support, you can write a macro that calls KWIKINF.EXE directly with the search-string as a parameter. Make sure you don't use the KwikINF hot-key to invoke this macro or KwikINF will intercept it before your editor ever sees it.

[[Image:KwikINF-Fig-2.png]]

''Figure 2. Search Window''

==Building Custom Index Files==
If you have an online book that is best used as a reference, you can create an index file to let KwikINF do the searching for you when you need information. By examining the index files shipped with the toolkit, you can see they're easy to build.

A typical line from the index file in the OS/2 2.1 Developer's Toolkit<br/>(x:\TOOLKT21\BOOK\EPMKWHLP.NDX) is (Win*, view pmref ~).

The first token on this typical line, (Win*), identifies a group of APIs that reside in a specific book. The asterisk, or wild-card character, specifies all APIs that have the Win prefix. This eliminates the need to list each individual API and greatly red uces the size of your index file. The second token, (view), is currently unused. The third token, (pmref), is an environment variable that specifies a group of books to be searched. A specific .INF file can be used as well.

Here's a simple index file demonstrating the basic syntax:
<code>
 /* C style comments and blank lines are acceptable */
 /* Specific file extensions may be specified here (for EPM editor) */
 EXTENSIONS: *
 
 /* A title may be placed here */
 
 DESCRIPTION: Any Developer's Custom KwikINF index file
 
 /* Complete help words or prefixes with wildcard (*) character may be used */
 /* to determine the proper book to open */
 
   (undelete, view cmdref.inf ~)
   (sysl*, view cmdref.inf ~)
   (wp*, view pmwkp.inf ~)
</code>
Using this sample index file, KwikINF is able to load the correct book and find the unrelated topics undelete, syslevel, syslog, and wpOpen. 

==Installing Index Files==
KwikINF determines the index files to use from the HELPNDX environment variable, installed in the CONFIG.SYS file by the OS/2 Toolkit installation program.
 SET HELPNDX=EPMKWHLP.NDX
If you write your own index file, you must add it to the end of this variable. For example, suppose you wrote an index file named CUSTOM.NDX. You modify this variable like this:
 SET HELPNDX=CUSTOM.NDX+EPMKWHLP.NDX
For KwikINF to find your index file, it must be in the BOOKSHELF environment path (in CONFIG.SYS).

==Future Work==
Though KwikINF is very useful as it is, I'm excited by the prospect of continually improving this tool. Future work on KwikINF might include making it portable to different hardware platforms (a good idea for any code), faster interface into .INF files, full 32-bit port, and an API interface for other applications.

But you're the customer. We'd like your idea and suggestions; send your ideas using CompuServe, or write us at the address shown in The Developer Connection News.

==Summary==
If you rely heavily on the OS/2 Online References when you write code, KwikINF is the tool for you. Try it! You might think twice before you clutter your desk with hardcopy books. KwikINF puts it at your fingertips.

For more detailed information on KwikINF, see the Tools Reference in the Toolkit Information folder.

{{IBM-Reprint}}
[[Category:Developer Connection News]]