7 GAINING ACCESS TO DOCUMENTS

 7.1 Displaying Documents by Name
 7.2 Displaying Parts of Documents by Label

In previous sections we have concentrated on how to write hypertext documents and organise them into an inter-linked documentation set. In this section, we turn our attention to accessing those parts of the documentation set that we want to read.

7.1 Displaying Documents by Name

The simplest form of document access is provided by the showme command, which simply displays the document you name. For instance:

  showme sun188

would display the “top” page of the document called “sun188” (i.e. the one you are reading now). Using this command is normally easier than entering a full URL for the document.

The showme command displays the document using a WWW browser and will make use of one you already have running if possible. You can specify which browser to use, if required (see §B.1).

If you do not give any directory information, showme will search for the document using the HTX_PATH search path (see §2.3), but you can specify explicitly where the document is if you prefer, as in:

  showme ~/mydocs/galaxy_survey

If showme cannot find the document locally, it will try and fetch it from the remote document server instead(see §6). You can suppress this behavior using the -l switch if you prefer:

  showme -l document

in which case failure to find the document locally will simply result in an error. You can also specify that a remote copy of the document is required using the -r switch, in which case any local copy will be ignored and the remote document server will be asked to supply the document.

7.2 Displaying Parts of Documents by Label

The showme command also allows you to read selected parts of documents, specified using the cross-reference labels they contain(see §3.1). To do this, you simply add the label as an extra argument. Thus:

  showme sun188 hlink

will display the description of the hlink command in this document.

Using this feature requires that you know the names of the cross-reference labels present in the document, or at least requires that they be easily guessable. If this is not the case, you may prefer to select which parts of documents to view by means of a document search instead(see §8).