The ]HELP Command

Transcribed from the printed issue; not yet reviewed. Read it in the PDF of the issue, page 80

This article could have been called "Useful information retrieval from structured documentation via user commands". It discusses some of the problems of providing intelligently selected information extracted from an on-line documentation system and a solution which has been partially implemented at a large mainframe site.

The Problem¶

Finding the right question you have to ask to get the answer you need. As an example, "What question do I ask if I wish to find out the name of the utility function used to convert a delimited text vector into a matrix?"

The Solution¶

Asking an imprecise question needs to produce a useful answer, or a set of more precise alternative questions that you might ask. For the above example, I could ask for help on TEXT, from its reply select the sub-topic TEXT MANIPULATION, and from its reply ask for help on MAKEMAT, VTOM, BOX or whatever.

The solution as implemented, involves User Commands to ask the imprecise question; a text data base (in the form of a well structured documentation system complete with relevant documents) to hold the answers; and a set of look-up methods to match them.

The Text Data Base¶

The key to data is its structure.

Let me call the data the Library. The library consists of Books (or alternatively Documents) and an Index to them. In the index, each book is cross-referenced by its Author; Title; Subject matter; Formal fixed reference; and Abstract.

Documents also have an internal structure. The document is divided into 3 sections and each section sub-divided into units.

The first section is the control section and it contains all the formal units such as the title and contents.

The title page contains a formatted copy of the information used in the library index.

The contents page contains a list of all the units in each section and controls the layout and ordering of them. Each unit is defined by 3 items, the unit number (which controls order and significance), the unit title (topic) and an external reference (a unique key).

The middle section contains the main text of the book split up into chapters which themselves can be divided up into smaller parts.

The last section is the appendices which can also be divided into smaller parts.

The parts are the units defined on the contents page.

A unit consists of one or more paragraphs. Parts of a unit may be tagged by markers for subsequent selection (a quote). The full address of some tagged text would be given by a 3 level reference, the Book reference (unique to the book within the library), the unit reference (unique within the book) and the tag reference (unique within the unit).

For example, the syntax of a user command FOO could be held in a book with a subject of USER COMMANDS, within a unit with a reference of FOO marked with the tag SYNTAX.

The Look-up Methods¶

In this context, we are trying to match a defined search string with a set of strings. Near misses may be useful. Perfect matches are the exception rather than the rule.

You need to be able to search for sub-strings, key-words, strings with wild-cards (pattern matching), and incomplete or incorrectly spelt strings (best match). A sub-string look-up must be able to find, for example, the sub-string FMT embedded within all the function names used as external references to the units documenting the functions. A key-word search must be able to find, for example, the word PRINTER from all the topics.

Pattern matching is normally used to show groups of results, for example a list of all commands starting with ARCH.

Lastly there is Best Match. This is the type of thing that spelling checkers use. However in this context, it needs to work with phrases not just individual words. For example, the selection text PRINT should match up with: print, printing, printers, PRNT, PRT, ]PRINT, Laser Printing, line-printer etc., as used within topics.

The User Commands¶

User commands are required both to ask the final question and to ask the questions used to find out what the final question is. One command could be created to handle them all, but its syntax would probably become too difficult to use with ease. That is why I implemented several related commands (which all use the above look-up algorithms) to:

List selective document titles and references: ]DOCS selection

List selective user commands and descriptions. ]CMDS selection

List selective topics in a document. ]HELP topic-seln /LIST

Return the content of a unit or quote from its topic. ]HELP topic

Return the document or part thereof, from its formal references. ]DOCTEXT

Display help from a specific command. ]cmd /HELP

Return help on a specific command. ]HELP ]cmd

Notes on User Command Syntax as Implemented at this Site.¶

To simplify the use of user commands, they have all been written to use a standard syntax as follows:

]<cmd-name> <parameter string> <key word options>

Command names are standard APL-type names and are terminated by a space.

Parameter strings may be enclosed in quotes (normal APL rules about quotes in quotes apply). They may not contain the / character unless in quotes.

Key-word options all start with a /. They can take two forms: flags, for example /PRINT; and assignments, for example /MSG=OFF.

Certain key-word options are standard and apply to almost all user commands. These are:

Like )SYSTEM COMMANDS, ]USER COMMANDS cannot be called directly from within functions. However, the system function ⎕UCMD can be used to action a user command.

User commands can display messages, return results and action processes. For example, a user command might be asked to read 3 functions from file. The message produced might be that only 2 functions were found, the result could be the names of the functions found, and the action would be the reading and fixing in the workspace of the functions found. Alternatively, the message might be that the command failed as the file system was down, the result was empty, and no action was performed.

Note that ]HELP returns, by default, help on the command ]HELP as does ]HELP ]HELP. On the other hand ]HELP /HELP requests help on how to use the user command ]HELP, as does ]HELP ]HELP /HELP. Alternatively, ]HELP HELP /DOC=HELP would return the unit whose topic was called (or contained the best match to the word) HELP from the document with the name HELP. By coincidence, the text displayed or returned in these cases is all the same.

So what is "The ultimate imprecise question"?

Answer: ]HELP