[[page created automatically from word-processed document; conversion is imperfect -- eg reference numbers. Figures are not there.]]
A help system based on UNIX manual pages
P.J. Brown
Computing Laboratory, University of Kent at Canterbury, Canterbury, Kent CT2 7NF
and Office Workstations Ltd., 5 Abbeymount Techbase, Easter Road, Edinburgh EH7 5AN
M.T. Russell
Computing Laboratory, University of Kent at Canterbury, Canterbury, Kent CT2 7NF
.sp 7
February 1987
SUMMARY
The paper describes a help system which exploits the capabilities of a graphics workstation. The reader expands the help information simply by pointing at buttons on the screen. The system can either use specially written help-scripts or can make use of existing documentation such as the .UX manual pages. The software that invokes the help system can cause it to focus the help information according to the context in which the user asked for help. The paper discusses the mechanisms by which this is achieved.
A help system requires:
Ideally the help-script should be a specially written document, designed exclusively for on-line users who require assistance. However, for better or for worse, this ideal is frequently not achieved. Instead another document, normally the user manual, is made to serve also as the help-script. This is done partly because of the initial cost -- producing a good user manual is an expensive and energy-sapping exercise, and maybe no resources will be left for other documentation -- and partly for ease of maintenance. This second point is an important one. As we know, even if the user documentation consists only of a single manual, this often gets out of phase with the software it purports to describe. If the user documentation is supplemented with a help-script the problems multiply: the user manual says you do X whereas the help-script says you do Y; in fact if you come to use the software neither X nor Y actually works, since the software requires you to do Z.
Given that, because of these reasons, much software will not have a special help-script, but will instead make do with the user manual as a help-script, the challenge is to make the user manual as effective as possible in its dual role. This is no mean challenge since user manuals are normally written to be read from paper whereas a help-script is read from a screen by an interactive user. These two environments are totally different\*(re.
The purpose of this paper is to describe an approach to meeting the challenge. The work was done in the context of UNIX, though similar principles apply to other operating systems -- provided that user documentation is available on-line. As the reader doubtless knows, UNIX has its own house-style for user manuals: these are stored on-line as `manual pages'\*(re. A manual page (which is the user manual for a particular UNIX feature, and which often consists of many physical pages) may either be printed on paper or displayed on-line. One of the strengths of this approach is that the manual page is (normally) the single source of documentation, both on-line and off-line. Thus the problems of maintenance are reduced. (The strength is also arguably a weakness, since it is quite unrealistic to have one document to satisfy all users -- on-line and off-line, weak and strong. This is a frequent criticism of the UNIX approach, but we will not pursue it here.)
In this paper we describe how the UNIX manual pages can be adapted to serve as a help-script. The focussing tool used is Guide\*(re, and we start by outlining the main features of Guide.
Guide is a highly interactive tool for displaying documents. It is designed to run on a workstation with a graphics screen and a pointing device, which we shall here assume to be a mouse. The main aim of Guide is to escape from the constraints of paper documents -- and from the constraints of on-line documents that are merely copies of paper documents -- by providing an environment whereby the user can interact closely with an on-line document in order to tailor what is displayed to what he wants to read.
Guide has been implemented at the University of Kent at Canterbury to run on UNIX workstations such as the SUN-3. It has also been implemented by Office Workstations Ltd. to run on the Macintosh and the IBM PC. Although this paper concentrates on the UNIX implementation, the other implementations are similar in principle. Their main difference from the UNIX implementation, apart from the style of the user interface, is their enhanced facility for cross-references; this could have been used to advantage in the work described here.
The central concept of Guide is the button. There are two types of button: the replace-button and the glossary-button. Buttons are embedded in the document that is displayed, and are used in a similar way to `buttons' in a menu: in other words when the user `selects' a button (by pointing at it and clicking the mouse) something happens. These ideas are best illustrated by examples.
Figure 1 shows Guide being used to display a `help system' for a photocopier. There are three replace-buttons in the document. These are shown in bold face, i.e. the first replace-button is `copies are made but contain dirty stripes'. When the user selects a replace-button it is replaced by some more detailed material, previously prepared by the author of the document. Figure 2 shows the result of selecting the first replace-button in Figure 1.
In Figure 2 the document is now too big to fit on the screen, and some material has been scrolled off the bottom. This scrolled material consists of the rest of the replacement of the first replace-button -- including most of the picture of the copier -- together with the other replace-buttons that were seen in Figure 1. The thumb-bar (the area immediately below the menu, which is partly black and partly white) can be used to travel around the document, and thus to display parts that are not currently in view.
The replacement of one button can itself contain further buttons. In Figure 2 the replacement contains the glossary-button alter-mode , which will be explained shortly. The names of glossary-buttons are underlined.
A Guide user can select any button at any time. Replace-buttons are normally used to provide successively greater levels of detail, and since these buttons lie within the document the reader can easily see the context \*(re. Thus by selecting appropriate buttons the reader can display the document at whatever level of detail he wishes. He can, at any time, `undo' a replacement if he feels that its replacement is of no interest and he therefore does not want it to clutter up his document.
Authors of Guide documents can group replace-buttons together into a construction called an enquiry. This allows multi-way replacements. For example an enquiry might be
Are you a beginner or an expert?
The replacement of beginner and expert can then be explanations for beginners and experts, respectively.
The overall aim of Guide is to allow readers to tailor documents to what they want to read. This is largely done by the one simple mechanism that we have just described, the replace-button. It is, of course, a vital requirement of a help system that it be based on a minimal set of simple concepts -- otherwise the user will need a help system for using the help system.
We now explain the second type of button, the glossary-button. Glossary-buttons differ from replace-buttons in that, instead of providing an in-line replacement, they display material in a separate sub-window. They are useful for explaining jargon-terms, for providing the equivalent of a footnote facility, and for citations. In Figure 2 the alter-mode glossary-button is used to provide an explanation of this jargon term `alter-mode'.
Figure 3 shows the result of selecting this button. The definition of the term `alter-mode' is now displayed in a separate sub-view occupying the lower half of the screen. The original document has been automatically scrolled so that the new sub-window does not overwrite the glossary-button that the user was pointing at. Guide aims to be as uniform as possible, and hence undoing can be applied to all kinds of button. Undoing a glossary-button, like undoing a replace-button, reverts to the previous state and can be used to save screen space.
Finally, to conclude our outline of Guide, we need to mention editing. Guide offers all the facilities of a screen editor. The reader can therefore point anywhere in the document and add his own annotations, such as `The copier key is in the bottom drawer of my desk'. The reader can then save the annotated document as his personal documentation. This facility further enhances Guide philosophy that readers should be able to tailor on-line documents to their own needs.
Guide's facilities are, we believe, eminently suitable for an on-line help system, and they have been used to implement help systems for several pieces of computer software (as well as for our hypothetical photocopier). Authorship of documents is designed to be simple; indeed any Guide reader can become an author and create new text and/or new buttons. This is done in an interactive WYSIWYG manner. Further details are given in the user manual for UNIX Guide\*(re.
However, a new documentation tool cannot expect the whole world to change overnight by rewriting all existing material for the new tool. That is why the emphasis of this paper will be on using existing material, the UNIX manual pages, rather than creating new material.
A pre-processor has been written to convert manual pages to Guide format. (As we have said, most existing UNIX documentation is in the form of manual pages.) In essence the pre-processor converts each section heading within the manual page into a Guide replace-button. The replacement of the button is the body of the section. The first two sections of each UNIX manual page, the NAME and SYNOPSIS sections, give the name of the facility with a one-line description of its role, and a synopsis of the syntax for using it. Since these sections are of interest to all readers they are presented by Guide in their full expanded form.
Figure 4 shows the use of Guide to display the manual page for the UNIX ls command. Notice that, after the first two sections, each section is simply represented by a replace-button, which the user can expand if he wishes to explore that section. (In Figure 4 the document is too big to fit in the somewhat small window that has been used. Hence several sections have been scrolled off the bottom.)
Similar work involving viewing manual pages in an interactive way has been done by Witten and Bramwell\*(re. Their aim is somewhat different from that described here, but our approach could certainly benefit from some of the suggestions given in the concluding remarks of their paper.
An important property of a help system that runs on a workstation is its use of its window. Guide can run in a window of any size (above a certain minimum). It automatically fills lines of text to fit the current size of window. If the window size is changed dynamically, Guide automatically re-formats the text in order to fit the new size. This dynamic behaviour is valuable for a help system. If the user is employing one window to contain a help system for some software that is running in a second window, then he may well wish to change the relative size of the two windows, depending on which he is concentrating on.
A help system may be called directly by the user or indirectly through the software to which the help relates. In this section we concentrate on the latter. There are two possibilities here:
In either case the help system may wish to take account of the context in which the help was requested. For example if the user is trying to use the `Move' facility then the help system might be asked to focus its help accordingly. Thus the software invoking the help system will, in general, pass it
Guide has been used in this way by a software package called fs\*(re, and most of the rest of this paper is devoted to describing this usage. The fs software is, in fact, a system for displaying the UNIX file system in a graphical way; it provides the functionality of the normal UNIX commands such as cd, chmod, ls, mv, cp, rm, etc.
As the fs user sees the help system it works as follows:
Figure 5 shows the result when the fs user asks for help about its `Remove' command. Notice how the information that Guide displays contains two replace-buttons, which provide further details about retrieving files that have been removed, and a glossary-button which explains the meaning of the UNIX jargon term `unlink'.
It all too often happens that a help system is too complicated for a user to master. He may get locked into a state that he does not know how to escape from, or he may get lost into some tree-structure of information\*(re.
Guide avoids some of these problems by its modeless design and its disguising of internal data structures -- the user need not be aware that, by expanding and undoing buttons, he is walking a tree. Nevertheless it does place some demands on the user. He needs to be able to select the Guide buttons on the screen and it will help if he can use the thumb-bar to move round the screen. (However the straightforward Read-on command can be used if the need is only to read sequentially.) Although it may take only a minute to master these facilities, they do, nonetheless, provide some scope for confusing or upsetting the initial user. For this reason we have been wary about using Guide as a help system for itself. If the user had trouble using Guide, and when he asked for help was presented with a further incarnation of Guide, it would be doubly upsetting. Nevertheless such problems can be conquered, as for example in the spy editor\*(re, which successfully uses itself as a help system by loading and focussing a help-script as if it were a document to be edited.
It is worth emphasising the value of the scrolling facility. In fact Guide loads the entire help-script for fs, and focusses this on the relevant information. The user can, however, scroll to any other part of the help-script. This may be necessary in a scenario such as the following: the user wants to know how to remove some access permission from a file. He mistakenly thinks the `Remove' command will do this, so he asks for help on this. What appears is some information on how to delete files. The Guide user can escape from this wrong context by scrolling round the help-script and looking at the section headings. With luck he will find the section called `Changing filenames and permissions' and will expand this, thus finding the information that he needs.
The help-script for fs is its manual page. As well as being used by Guide, this manual page can be used in the normal way by UNIX utilities such as man. (It does, however, contain some extra Guide facilities, such as the unlink button. We shall explain the implementation of these later.)
The section headings in the fs manual page correspond to the objects that the user may ask help for. We have seen in Figure 5 the expansion of the section about removing files. When the user first asks for help, fs creates a new window and calls Guide to run in it. Fs passes parameters to Guide which cause it to convert the manual page, load it and then focus on the appropriate section. Guide supports several focussing mechanisms but the most useful one for help systems is the button-search. A button-search involves searching for a given string (in this case `Remove') among all the names of replace-buttons; the search is not case-sensitive. If the string is found (as `Remove' will be in the fs manual page, which contains the section heading `The command to remove files'), the button is expanded and the first line of the expansion is put as the first line of the display -- the state shown in Figure 5. The remaining sections (apart from NAME and SYNOPSIS) are not therefore expanded and if the user scrolls around he will just see replace-buttons representing sections, as we have intimated earlier. If the button-search fails, there is a bug in the help system in the sense that the requested topic has no help information; in this case Guide does no focussing and simply displays the manual page from the beginning, like the ls manual page in Figure 4.
At subsequent help requests, fs tests if Guide is still running and, if so, sends it a message to perform a new button-search, thus causing Guide to re-focus on the new information that the user requires.
Converting manual pages to Guide form is comparatively time-consuming. Guide therefore keeps a cache of converted manual pages so that the conversion only needs to be done once. On the SUN-3 the time taken between the help request and the appearance of the help information, assuming that the converted manual page is taken from the cache, is 5-10 seconds. Although modest, this is still an annoying delay for the user and we would like to reduce it. The main problem is, however, the sheer size of graphical programs on the SUN-3, and the consequent time spent on loading them.
An ordinary manual page, when converted to Guide form, will not exploit much of the power of Guide: the replace-buttons that represent section headings will be the only Guide facilities used. It is, however, possible to introduce further Guide facilities into manual pages, and this can be done without compromising their normal role as manual pages. In particular it is possible to introduce:
Indeed the material shown in Figure 5 exploits the first two of these.
To explain how this is done, we first need to outline the format of Guide source files. These consist of normal lines of text (and bitmaps representing pictures) with interspersed control information such as `start of button', `end of replacement', etc. This control information is represented by requests that have the same format as nroff requests. For example
.eR
means the end of a replacement. The names of the Guide requests have been chosen not to clash with the built-in nroff ones. Hence these Guide requests can be inserted into a normal nroff source file without affecting the way nroff sees the file -- this is a consequence of the property of nroff that it simply ignores requests that it does not recognize. In particular, Guide requests can be introduced into manual pages without affecting their normal use as manual pages (and without introducing a lot of complex if requests). It is possible, in fact, to take any existing Guide source file and embed it in a manual page without nroff seeing it.
Clearly some of the details that we have been discussing relate specifically to UNIX and its arrangements for manual pages. However the principles apply equally well to any other documentation system where documents have some well-defined structure (e.g. sections and sub-sections) that can be converted automatically to Guide structure.
Ideally all on-line software should have its own specially tailored help-script. We claim that, for a graphics workstation, Guide is a good medium for displaying such help. However the main purpose of this paper has been to show that, when there are not sufficient resources to provide such a help-script, it is still possible to provide a valuable help system based on an existing user manual. The key to achieving this is to present information in a way that the reader can interact with and tailor to his own needs.
We are grateful to our colleagues at the University of Kent and at Office Workstations Ltd. for several ideas that contributed to this work. The Science and Engineering Research Council supported the development of fs under its Software Tools Centre contract with the University.