9.1 Providing Hypertext Help
 9.2 Using HTX to Control a WWW Browser
 9.3 Performing Document Searches from Other Software

9.1 Providing Hypertext Help

An important application of the showme command is to provide hypertext help for other software packages.

In this situation, the help information would be contained in one or more hypertext documents and the controlling software would invoke the showme command to display the required part of it on demand, the information being selected by giving an appropriate cross-reference label (see §3.1). The person reading the displayed information can then explore any hyper-links within it to gain further information. These could point at other documents you have linked the help documents against or, indeed, anything else on the WWW.

When designing a graphical user interface, help information can easily be made “context sensitive” by setting the cross-reference label according to the task being performed (e.g. which window is active) and invoking showme when a “help” button is pressed. In fact, with a dedicated WWW browser, one might even consider displaying the information automatically as the task in hand changed, without waiting to be asked.

By going via this HTX interface, the controlling software is insulated from changes in the way the help documentation is organised and indexed. It also need not concern itself with how to communicate with the WWW browser. In some cases, however, you may want your software to handle the display of help information yourself. You can do this by using the -n switch on the showme command, thus:

  showme -n help_document subject_label

This prevents showme from displaying the document. Instead, it simply writes the URL for the part of the document you requested to its standard output. Your software can then read this and handle it in whatever way you choose.

9.2 Using HTX to Control a WWW Browser

If you have used the showme command to obtain a URL for a document (see above), one possible way of using this might be to save it and pass it back to showme later on, using the -u option for displaying a document by URL:

  showme -u url

Of course, the URL you give need not have come from showme in the first place – any URL that your WWW browser can handle would be acceptable.

You can also supply the name of a local file using the -f switch, thus:

  showme -f filename

Because you can give relative file names to showme, this is often an easier way of viewing a file interactively than typing its full path into the browser.

These examples illustrate how showme provides a convenient and uniform interface for “remotely controlling” a WWW browser, permitting you to display any WWW document for which you have a URL or file name.

9.3 Performing Document Searches from Other Software

You can use the findme command from within other software to implement document searches with a user interface of your own design. This is done by using the -html switch, as follows:

  findme -html -q keyword

This switch prevents findme from displaying its list of results via a WWW browser, and it instead writes them to its standard output in HTML format.6 In this mode, a “naked” output list is produced that lacks the surrounding HTML document and this allows it to be embedded in any other HTML context where it may be needed.

An example of this might be a WWW forms interface for performing local document searches. Typically, a Common Gateway Interface (CGI) script would be written to be invoked by your WWW server and perform the search, generating a page of HTML as its output. Such a script could invoke the findme command in the form above to implement the search and then embed its output in the page it generates.

Alternatively, a script invoked from the command line or a graphical user interface might build an HTML document, including search output from findme, in a local file. It could then use the showme command with its -f flag to display the result.

You can test for the success of a search by examining the return status from findme which is set to the number of documents that were matched.

6In this case the -q switch has also been used to suppress messages about the progress of the search.