Chapter 5: Dig and Klook

5 Dig and Klook

The Dig and Klook modules are Emacs interfaces to the dig program and the Klook database system. Dig searches Discuss meetings for transactions matching a specified regular expression, and is used by consultants to find old questions and answers which may shed light on current questions. Klook performs keyword-based look up through its database of stock answers and other information, and is a useful efficiency tool for the fast retrieval of documentation. They are discussed jointly because even though they are completely separate modules, their use is almost identical due to the nature of their functionality.

5.1 Using Dig and Klook

Dig and Klook are invoked by typing M-x dig or M-x klook respectively. Both initially ask for a regular expression (Dig) or set of keywords (Klook), then spawn an asynchronous process which does the search.

Dig accepts the following arguments controlling its search, which are typed into the minibuffer at the initial prompt:

-n n
The number of transactions to search in the discuss meetings, starting from the last transaction. The default is 50.
-e regexp
The regular expression to use. The default is ``.*'', which matches everything. Regular expressions are in the style of egrep.
-i
Ignore case in comparisons.
-a
Search the text of the transactions, in addition to the titles.

The meetings a Discuss user views are kept in the file $HOME/.meetings. The following arguments control which meeting file is used:

-f file
The meetings file to use; default is $HOME/.meetings.
-l
This option is mutually exclusive with -f. It says to use a special meetings file which contains only the meetings archiving previously answered OLC questions. When Dig is used to search old OLC questions, this option is included.

The rest of the arguments are the names of the actual meetings to search, for example ``oemacs'' or ``ozephyr''. If none are specified, all the meetings in the meetings file are searched.

Klook takes only one argument, -m n, besides the necessary keywords. Klook returns only those matches in which the title matched at least n of the keywords specified. This prevents receiving every entry in the database that matches only some of the keywords, rather than all of the keywords. If omitted, all entries matching any of the keywords are returned.

Once matches have been found, a buffer listing the matching entries is displayed; see Figures 5-1 and 5-2. Dig shows the title, meeting, and transaction number of each entry, Klook the title, associated keywords, and number of the entry in its database. Entries from this list can be selected with n and p, or by title with m. (In Figure 5-1, the first entry is selected.) If only one entry is listed, it is automatically selected.

------------------------------------------------------------------ |ozephyr[3858]: neslihan: can't zlocate someone outside of Athena| ------------------------------------------------------------------ ozephyr[3906]: htung: zlocate and finger question ozephyr[3914]: damartin: zlocate query checks

Figure 5-1: Sample Dig Matches Buffer

274(3): "Tcsh FUNCTION KEY bindings" [olcstock unix tcsh function keys tcsh function key bindings] 71(3): "How to use the FUNCTION KEYS in Emacs" [olcstock emacs func keys how to use the function keys in emacs]

Figure 5-2: Sample Klook Matches Buffer

Typing RETURN views the currently selected entry by displaying it in a separate buffer. In this buffer, n and p work analogously to n and p in the matches buffer, except that they view the previous and following entries. As in the OLH and CRef menu browser, s saves the buffer text in the Emacs kill ring, and C-o writes it to a file. Typing RETURN prompts for arguments for another search. The arguments of a search are stored in the Emacs kill ring, so the previous arguments may be reused by typing C-y and editing them in the minibuffer.

5.2 Implementation

The actual implementation of Dig and Klook is very simple. It consists chiefly of running the dig or klook program with appropriate arguments, and parsing the output.

To retrieve the actual discuss transactions, dig can be used. Klook however relies on a separate program, shans, which retrieves the actual entry (given its number) in the Klook database.

The Klook database deserves some more careful attention.^[1] The standard OLC stock answers are stored by Klook in a single file called stock-answer-tree, which is generated automatically by a program called gettree. The other Klook answers added by consultants for their own use are in the file ans.txt, which consultants edit directly. Each file is composed of entries which contain the title of the entry, the keywords relevant to the entry, and the text of the entry itself. Each entry has a unique number associated with it.

When the Klook database is built, the ans.txt and stock-answer-tree files are merged into a single file called ans.compiled, which represents all the answers available via Klook. From this file, two additional files are generated: ans.index and ans.key. ans.key contains a line for each keyword in all of the entries in ans.txt and stock-answer-tree. For each keyword, it lists the numbers of all the entries which contain it. ans.index contains the numbers of all the entries, and for each entry, the offset in ans.compiled at which the entry is found.

Now, given the answer file ans.compiled and the index files ans.key and ans.index, retrieval of an answer can be done quickly and efficiently. All entries matching the given keywords are found by searching through ans.key. To retrieve an actual entry, given its number, its offset in ans.compiled is found by looking in ans.index.

5.3 Analysis

The Klook and Dig interfaces present a simple Emacs front end to the klook and dig programs. They are presently two distinct modules. However, their basic functionality is so similar that thought of somehow abstracting their common elements into an underlying retrieval interface deserves some attention.

In particular, the following functions are performed by both Klook and Dig:

Prompt the user for arguments, using the minibuffer.
Run an asynchronous process with those arguments.
Parse and display the output of the process when it terminates, and in effect make a menu from the output. Allow the user to select an entry from the menu.
Run a second asynchronous process to view the specified entry.

Examination of the Dig and Klook code attests to the need for a common interface to bind the two programs, similar to the menu browser module used by OLH and CRef. Such an interface has not been built mostly due to time constraints, but its basic similarity to other very simple Emacs commands such as M-x occur and M-x grep hints at the possibility of a straightforward implementation.