Make the examples index better - list all examples with "Example $ChapNum$.$ExNum$: $example_title$"

[dholmes-epcc-ed-ac-uk]

Problem

The example index is counter-intuitive: it lists terms/phrases/functions used in examples, rather than a list of the examples in the document.

Proposal

There should be an index that lists all the examples in the format:
Example $ChapNum$.$ExNum$: $example_title$, $page_num$

The "function usage" information from the current examples index is useful - this should be added to the function index.

Changes to the Text

OLD example index entries

MPI_ACCUMULATE, 453
MPI_Accumulate, 495, 498

NEW example index entries

Example 11.3: $shortened_title_for_ex11.3$, 453
:
Example 11.18: $shortened_title_for_ex11.18$, 495
:
Example 11.23: $shortened_title_for_ex11.23$, 498

OLD function index entry

MPI_ACCUMULATE, 429, 445, <u>452</u>, 453, 455,
             461, 465, 489, 495, 496, 849, 852

NEW function index entry

MPI_ACCUMULATE, 429, 445, <u>452</u>, 453, 455,
             461, 465, 489, 495, 496, 849, 852
      Fortran example usage 453
      C example usage 495, 498

Impact on Implementations

None.

Impact on Users

• Easier to find a particular example by number.
• Still possible to find example function usage.
• Example usage location(s) is/are shown in the same index entry as the primary definition and other references to that function.

References

Adding absent titles for examples will be done by issue #228.

Shortening long titles for examples will be done by issue #235.

[wesbland]

This is probably a combination of a bunch of efforts. It'll require more metadata on the example side (e.g., better title, language, etc.) and then a bunch more LaTeX to generate the correct data in both places.

[wesbland]

@wgropp I'd like to see some feedback from you on this before we try to go too far down this path. I think this probably would involve two parts:

1. Creating new LaTeX macros to generate metadata that can be used when generating the various indexes to add examples.

2. Going through each of the examples in the document and adding the relevant metadata (e.g., the functions and/or concepts demonstrated in the example).

The first thing would probably need to be done by @wgropp . The second thing will be a combined effort of each of the chapter committees.

[wgropp]

I think this is worthwhile, but as you suspect, it will take a number of steps, including updating the index building process. I'll work on that, and when its ready, I'll note that on this issue (ready will mean both updating the macros, build process, and instructions document)

[wgropp]

Ok, I have a working version. Use\Exindex{language}{description}{routines,....} as in \Exindex{C}{Matching sends and receives}{MPI\_SEND,MPI\_RECV}. I created a new python program to build the indices; this has also identified a number of problems with the current indices. \Exindex can only be used within the example environment. \exindex is still available. I will push this to the mpi-4.x branch, as it reproduces the current index (with a few fixes) and adds \Exindex. Finally, I didn't implement exactly what is shown above; in particular, a number of different entries are added to both the Examples and MPI Function indices. Once we have enough examples of entries, it is easy to select a subset of the entries added (e.g., I'm still including the MPI functions in the Example index, but with \Exindex, we could limit those to the MPI Function index.

[wesbland]

Thanks for taking care of this @wgropp! The new version looks much more useful.