HELP MKREFINDEX                                  John Williams, Oct 1990

A tool for creating an index to the identifiers described in a set of
REF files.


         CONTENTS - (Use <ENTER> g to access required sections)

  1   Introduction
  2   Using LIB MKREFINDEX
  3   Index Format
  4   Index Utilities
  5   REF File Format
  6   Tailoring LIB MKREFINDEX for other documentation formats
      6.1   Method 1
      6.2   Method 2
  7   See Also


-----------------------------------------------------------------------
1  Introduction
-----------------------------------------------------------------------

LIB * MKREFINDEX is a tool for indexing a set of documentation files, in
order that they may be accessed via the VED <ENTER> commands ? and ??
(described in HELP * QUERY).

LIB MKREFINDEX makes the following broad assumptions:

    1.  The set of files to be indexed all live in one directory.

    2.  That directory has a sub-directory named "doc_index".

    3.  Each file is made up of a mixture of discursory text and
        descriptions of individual named items.

    4.  Each named description can be divided into two parts - header
        and text.  The text part may be empty.

LIB MKREFINDEX reads through the set of files, and creates an index (in
the "doc_index" sub-directory) that records the locations of all the
descriptions found in the set of files.

The name "MKREFINDEX" derives from the fact that, by default, LIB
MKREFINDEX assumes that the documention files are formatted in the style
of Pop-11 REF files. However, it is possible to tailor LIB MKREFINDEX
for use with other formats, as explained below.


-----------------------------------------------------------------------
2  Using LIB MKREFINDEX
-----------------------------------------------------------------------

To use LIB MKREFINDEX from Pop-11, do

    lib mkrefindex;
    mkrefindex(dir);

This indexes the directory dir. An error is signalled if dir does not
have a sub-directory named "doc_index".

LIB MKREFINDEX may also be invoked from the shell (Unix) or DCL (VMS),
like this:

    pop11 mkrefindex dir


-----------------------------------------------------------------------
3  Index Format
-----------------------------------------------------------------------

A "doc_index" directory consists of 26 files, named "a", "b", "c" to
"z". Each file consists of a number of index entries. An entry records
the location of the description of an item whose name begins with the
same letter as the name of the index file. The index is not
case-sensitive, so (for example) the items "ARRAY" and "abs" would both
be listed in the index file "a". Names beginning with a non-alphabetic
character (e.g. "==>") are listed in the file "z".

Each index entry occupies a separate line of an index file. Entries
consist of five fields, separated by spaces. These fields are:

    1.  description name
    2.  name of the file that contains the description
    3.  the line number of the start of the description
    4.  the line number of the end of the header part of the description
    5.  the line number of the end of the description

Field 2 should contain the name of a file, not a full pathname. Fields
3, 4, and 5 may be the same.

Within each index file, the entries are arranged such that their first
fields are in alphabetical order.

For an example of an index file, examine $usepop/pop/ref/doc_index/a.


-----------------------------------------------------------------------
4  Index Utilities
-----------------------------------------------------------------------

The header file INCLUDE * DOC_INDEX defines a number of constants that
are useful to programs that manipulate indexes.

Also, the following two procedures are provided:

    sys_search_doc_index(name, dir, exact) -> n

This searches the index associated with dir for entries listed under
name. Returns the number of matching entries (n), followed by the
entries themselves. Each entry is a five-element vector, of the type
produced by sys_parse_doc_index_entry.


    sys_parse_doc_index_entry(string) -> vec

This converts a string (normally a line from an index file) into a
five-element vector, containing the five components of an index entry.
string should consist of five space-separated text items.


-----------------------------------------------------------------------
5  REF File Format
-----------------------------------------------------------------------

By default, LIB MKREFINDEX expects files to use the standard Pop-11 REF
file format. This is discussed in detail in REF * REFFORM.

Briefly, the rules used by LIB MKREFINDEX are:

1.  Descriptions commence with a line whose first character is not
    a space, and whose last character is `]`.

2.  The header part of a description is terminated by a line whose
    first non-whitespace character occurs in column 9.

3.  The text part of a description is terminated by 2 successive
    blank lines.

The name under which a description is indexed is determined by parsing
the first line of the description header into Pop-11 text items. The
description name is the first text item that is not italicised (formal
parameter names are depicted in italics).


-----------------------------------------------------------------------
6  Tailoring LIB MKREFINDEX for other documentation formats
-----------------------------------------------------------------------

You can use LIB MKREFINDEX to index documentation that doesn't use the
standard REF file format. There are two ways of doing this:


6.1  Method 1
-------------

The procedures called by mkrefindex to determine where a description
starts and ends can be redefined. These procedures are:

    description_hdr_start(line) -> bool

    description_hdr_end(line) -> bool

    description_hdr_name(line) -> string


The first, description_hdr_start, should return true if the line of text
line commences a description.

The second, description_hdr_end should return true if line terminates
the header part of a description. (Also, by definition, true if line
commences the text part of a description).

Finally, description_hdr_name, given the first line of a description,
should return the name (as a string) under which the description is to
be indexed.

Note: it is not possible to specify how descriptions are terminated. In
other words, descriptions can only be terminated by two blank lines.

For an example, examine the file $usepop/pop/lisp/mklisprefindex.p, in
which the procedure description_hdr_name is redefined to recognise Lisp
function names.


6.2  Method 2
-------------

Alternatively, you can redefine the procedure that mkrefindex uses to
parse each document. This procedure is:

    mkrefindex1(filename) -> (vec_1, vec_2, ..., vec_n, n)

filename is the name of the document. Each result vec is a five-element
vector of the type produced by sys_parse_doc_index_entry (see above),
and n is the total number of these vectors.

The standard version of mkrefindex1 uses description_hdr_start,
description_hdr_end, and description_hdr_name to parse the document.


-----------------------------------------------------------------------
7  See Also
-----------------------------------------------------------------------

    HELP * REF              - for examining REF files
    HELP * QUERY            - for details on <ENTER> ? and ??
    REF * REFFORM           - specification of standard REF file format


--- C.all/help/mkrefindex
--- Copyright University of Sussex 1991. All rights reserved.
