Introduction

The programs in the Starlink software collection consist of a few million lines of source code, mainly in Fortran 77 and C. Finding the source code of interest given the name of a user task, a function, or even a source file can be non-trivial; the name of the file containing a routine definition, the package/directory/tar archive in which the file resides, and the position in the file at which the routine is defined may all be difficult pieces of information to obtain if one is unfamiliar with the package in question.

This package seeks to enable fast navigation around the Starlink source code in two ways. In the first place it can locate a routine or file based on an explicit user query (giving the exact or approximate name of the routine or file and optionally the Starlink package in which it resides). In the second place, it can present the source code as HTML, suitable for viewing with any WWW browser, with references to external routines presented as hyperlinks so that call chains can be followed conveniently. This second mode of use is clearly much more powerful than the first.

There are two principal components of the system: an indexing program which is run once to locate and store all the files and routine definitions, and subsequently only when the source code is changed, and an extractor program which interrogates the index to locate and output a requested file.

Typically the index will be generated by the system manager and stored centrally, and the extractor installed as a CGI script to serve HTML over the network (if security is a concern it is possible to restrict access to local users in the usual ways). Simultanously, local users will be able to locate or extract source files from the command line without using the WWW interface. There are other possibilities however: the extractor need not be installed as a CGI script at all so that only command-line use is available, and users may have their own private indexes which combine some or all of the main source code collection with their own development versions of packages.

The remainder of this document describes installation and use of the package, and some details of its internal workings. Its operation should be fairly intuitive however, and it is perfectly possible to learn to use it just by playing around, perhaps with reference to section 4.2.1.