Incorrect content generation for Appendix A

[dholmes-epcc-ed-ac-uk]

Problem

Thanks for the helpful discussion of this in the virtual meeting just now.

I have found the offending commit (c79a0b90f) and I understand the bug it introduced (a flawed change to the egrep regex for finding bindings in the rendered tex files).

The commit is this one:
https://github.com/mpi-forum/mpi-standard/commit/c79a0b90f6faa0aaa3a7f5f08556aaa0e3dbf9a6

Here are the before and after PDFs:

Before c79a0b90f:
mpi-report-before-c79a0b90f.pdf

After c79a0b90f:
mpi-report-after-c79a0b90f.pdf

In particular, MPI_Wtime appears in §A.3.7 in the before PDF but does not appear in the after PDF.

Proposal

Fix the bug in the MAKE-APPLANG script.

Changes to the Text

Correct the regex expressions to account for the variety of binding Latex macros.

Impact on Implementations

Correct appendices are easier to use than broken ones.

Impact on Users

Correct appendices are easier to use than broken ones.

References

Insert any internal (other issues) or external (websites, papers, etc.) references here.

[martinruefenacht]

This occurred in this PR: mpi-forum/mpi-standard#331

"Fixing" this issue: #334

Looking back, obviously it doesn't work. With the new regex we exclude many different latex macros... We need to have all the latex binding macros captured by the regex.

[RolfRabenseifner]

Why did you changed MAKE-APPLANG with these 4 additional "{" on 3 lines?
Can you just revert these 4 changes, i.e., removing these 4 "{"?

[martinruefenacht]

@RolfRabenseifner We introduced the \mpibindbcindex macro, because the embiggend functions were not being indexed. Bill proposed introducing a tag and we needed to avoid it matching the flag in MAKE-APPLANG. Clearly no one remembered the issue that there are multiple macros with a similar beginning and we needed to do a better regex expression.

These changes will be reverted or made better.

The whole indexing method is pretty broken since it does it through Latex (which at the time was all that could be done), but now with Python we can simply emit an index file directly. This will be worked on after MPI 4.0.

[wgropp]

And the easiest fix is to revert to the old MAKE-APPLANG and change the name of the new macro to MPIbindbcindex. And I agree with @martinruefenacht - with the pythonization, we have better tools to produce the bindings summary, and we'll do that for 4.1.

[dholmes-epcc-ed-ac-uk]

@wgropp somewhat unrelated but I'll mention it anyway because it touches on the auto-generation of the appendix: the hyperrefs for the function names and MPI object types (present in MPI-3.1 document) are missing in all MPI-4-RC versions of the document (that I've checked). I do not see anything (in previous versions of the git repo from the mpi-3.1 era or in later versions) that would have generated hyperrefs in the appendix. However, they existed before and do not now. Do you know the mechanism by which they came to exist in previous document versions? Is it now broken (and can it be fixed?) or is it a manual step that you perform after the FRM?

[wgropp]

@dholmes-epcc-ed-ac-uk I'll look into this. I believe it is a not-fully-automatic step that I need to execute.

[wgropp]

Found it - a fairly fragile process that has a make target, but currently doesn't work. It should be easy to fix, and I'll make the build a bit more robust.

[wgropp]

More info just for tracking - this was broken by the changes in the make process for the pythonization (not a criticism, the dependency is not obvious). It does mean that the fix is a bit more involved.