14

SUN/188.6

Starlink Project
Starlink User Note 188.6

R.F. Warren-Smith & P.W Draper

20th January 2010


HTX
Hypertext Cross-Reference Utilities

Version 1.3-1

User’s Manual



Abstract

This document describes a set of “Hypertext Cross-Reference Utilities” (HTX) which are designed to help maintain large documentation sets whose constituent documents are written using the Hypertext Markup Language (HTML).

The central part of HTX is a hypertext linker, hlink. This allows hyper-links (or cross-references) to be established between related documents in such a way that it is easy to maintain their integrity as individual documents are updated. Information produced by this linking process is also used by other HTX utilities to provide document search facilities and the ability to randomly access any part of a documentation set. This latter capability forms a basis for constructing hypertext help systems for use by other software.

The expected readership of this document includes those who read hypertext documentation, those who write it, and those who maintain it, especially those who write and maintain Starlink documentation. Software developers may also be interested in the possibilities for hypertext help that HTX provides.

Contents

1 INTRODUCTION
 1.1 What Does HTX Do?
 1.2 What is a Hypertext Document?
 1.3 Why are Cross-References a Problem?
 1.4 Mixing Local and Remote Documents
2 DOCUMENT ORGANISATION
 2.1 Document Directories
 2.2 Document Libraries
 2.3 Multiple Libraries and the Library Search Path
3 ESTABLISHING CROSS-REFERENCES
 3.1 Exporting Cross-Reference Targets
 3.2 Referring to Cross-Reference Targets
 3.3 Referring to an Entire Document
 3.4 Linking your Hypertext Documents
 3.5 Using Cross-References from LATEX
4 HOW HTX LINKING WORKS
 4.1 Index Files
 4.2 Link-Editing
 4.3 Absolute and Relative Links
 4.4 References to Remote Documents
5 WHEN TO RE-LINK
 5.1 Accommodating Normal Document Changes
 5.2 Forcing a Re-Link
 5.3 Suppressing Re-Linking
6 REMOTE DOCUMENT SERVERS
 6.1 Specifying a Document Server
 6.2 The Document Server’s Role
7 GAINING ACCESS TO DOCUMENTS
 7.1 Displaying Documents by Name
 7.2 Displaying Parts of Documents by Label
8 SEARCHING FOR INFORMATION IN DOCUMENTS
 8.1 Performing Keyword Searches
 8.2 Controlling the Depth of Search
 8.3 Searching Specific Documents
 8.4 Other Search Options Available
9 USING HTX FACILITIES FROM OTHER SOFTWARE
 9.1 Providing Hypertext Help
 9.2 Using HTX to Control a WWW Browser
 9.3 Performing Document Searches from Other Software
10 CATALOGUE FILES
 10.1 Catalogue File Name and Format
 10.2 A Catalogue File Example
 10.3 How Catalogue Files are Searched
 10.4 Providing a Local Catalogue of Remote Documents
A DESCRIPTIONS OF HTX COMMANDS
findme– Search for documents by keyword and display a list of those found
hlink– Perform cross-linking of hypertext documents
showme– Display a specified part of a document using a WWW browser

B USING WWW BROWSERS WITH HTX
 B.1 Specifying a WWW Browser
 B.2 WWW Browser Communication
  B.2.1 Netscape, Mozilla and Firefox Behaviour
 B.3 Inter-Machine Browser Communication