Next: PKG_ADD and PKG_DEL Directives, Previous: The DESCRIPTION File, Up: Creating Packages

#### 35.4.2 The INDEX File

The optional `INDEX` file provides a categorical view of the functions in the package. This file has a very simple format

- Lines beginning with ‘`#`’ are comments.
- The first non-comment line should look like this

                toolbox >> Toolbox name

- Lines beginning with an alphabetical character indicates a new category of functions.
- Lines starting with a white space character indicate that the function names on the line belong to the last mentioned category.

The format can be summarized with the following example.

         # A comment
         toolbox >> Toolbox name
         Category Name 1
          function1 function2 function3
          function4
         Category Name 2
          function2 function5

If you wish to refer to a function that users might expect to find in your package but is not there, providing a work around or pointing out that the function is available elsewhere, you can use:

         fn = workaround description

This workaround description will not appear when listing functions in the package with `pkg describe` but they will be published in the HTML documentation online. Workaround descriptions can use any HTML markup, but keep in mind that it will be enclosed in a bold-italic environment. For the special case of:

         fn = use <code>alternate expression</code>

the bold-italic is automatically suppressed. You will need to use `<code>` even in references:

         fn = use <a href="someothersite.html"><code>fn</code></a>

Sometimes functions are only partially compatible, in which case you can list the non-compatible cases separately. To refer to another function in the package, use `<f>fn</f>`. For example:

         eig (a, b) = use <f>qz</f>

Since sites may have many missing functions, you can define a macro rather than typing the same link over and again.

         $id = expansion

defines the macro id. You can use `$id` anywhere in the description and it will be expanded. For example:

         $TSA = see <a href="link_to_spctools">SPC Tools</a>
         arcov = $TSA <code>armcv</code>

id is any string of letters, numbers and `_`.