showme

Display a specified part of a document using a WWW browser

Description:

This command takes the name of a document and (optionally) the name of a cross-reference label within it, and displays the requested part of the document using a WWW browser. It may also be used to display local files or any other WWW page for which a URL is available.

Invocation

showme [switches] doc [label]

Parameters

doc
The name of the document. If no directory information is supplied, the document will be located using the HTX_PATH search path (see §2.3). If directory information is given, no search will be performed. In either case, a “.htx” extension to the document name is optional.

If the -f option is used, this parameter is interpreted as the name of a local file which is to be displayed. If the -u option is used, it is interpreted as a general URL.

label
An optional cross-reference label. If given, this specifies which part of the document is required. If omitted, it is assumed that the entire document is required and the appropriate “top” page is displayed(see §3.3).

This parameter is ignored if the -f or -u options are used.

Switches

-f
Specifies that the document name supplied is the name of a local file (e.g. in HTML format) which is to be displayed. If this option is used, the label parameter and the -l and -r switches are ignored.
-l
Specifies that a local document should be displayed and that it should not be fetched from a remote document server. In this case, if the document cannot be found locally an error will result.
-n
Specifies that the document is not to be displayed. In this case, no WWW browser will be used and the URL that would otherwise have been passed to it is simply written to standard output. This provides an interface for use by other software that will handle document display itself.

Note that the URL generated is suitable only for local use by a WWW browser running on the same machine as the showme command. It may not be suitable, for instance, for embedding in an HTML document that will be interpreted by a remote WWW browser.

-r
Specifies that a remote document is required. In this case, a reference to a remote document server will be generated and passed to the WWW browser, even if a local copy of the document exists.
-u
Specifies that the document name supplied is a URL which is to be passed directly to the WWW browser for interpretation. Any form of URL which the browser can handle may be given. If this option is used, the label parameter and the -l and -r switches are ignored.
-warn
Indicates that any warning messages issued by the WWW browser (e.g. when it is started up) are to be suppressed. By default, these warnings are written to standard error along with any other warning or error messages.

Notes:

Examples:

showme sun188
Displays the document called “sun188”. The local copy is used, if available, otherwise it is fetched from the remote document server.
showme sun188 showme
Displays the part of document “sun188” identified by the cross-reference label “showme” (i.e. the section you are reading now). As before, the local copy of the document is used, if possible.
showme -l quantum-theory
Searches for a local copy of the document “quantum-theory” and displays it. If the document cannot be found locally, an error results.
showme -r quantum-theory speculation
Displays the section identified by the “speculation” cross-reference label in a remote copy of the document called “quantum-theory”. Any local copy is ignored.
showme mydocs/help available_commands
Displays the section identified by the “available_commands” label in a local document stored in the directory mydocs/help.htx. Because explicit directory information is given, the document is not searched for using the HTX_PATH search path. If the document doesn’t exist, a copy will be fetched from the remote document server.
showme -n -l mydocs/help available_commands
Performs the same function as the previous example, except that the document is not actually displayed. Instead, its URL is simply written to standard output. The -l switch specifies that a local document is required, so an error will result if it cannot be found.

Environment Variables Used

HTX_BROWSER
The command which will be used to invoke the WWW browser (see §B.1).
HTX_PATH
A colon-separated list of the library directories in which to search for hypertext documents (see §2.3).
HTX_SERVER
The URL of the document server to be used for serving remote documents (see §6.1).
HTX_TMP
The name of the directory in which to create temporary communication files. If this variable is not set or is null, then $HOME/.htxtmp is used instead (see §B.3).