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:
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.
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:
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:
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.
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:
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.