devreal commented 1 week ago

Problem

The MPI standard (PDF and HTML versions) does not use hyperlinks to reference mentions of symbols to their definition. Such back references are useful in navigating the standard by providing an easy back to the definition of a symbol.

Proposal

Add hyperlinks from places where symbols are mentioned to their definitions. This can be automated using the existing macros (e.g., \mpifunc pointing back to \mpifuncmain).

Changes to the Text

Extend the existing LaTeX macros to provide hyperlink capabilities and fix any inconsistencies that emerge in the process (e.g., repeated use of main macros for the same symbol or missing main macros for a symbol referenced).

The resulting cleanup touches many chapters. While the changes are not substantial and do not change any semantics, they should be double-checked by the respective chapter committees and @wgropp as the editor.

The list of chapters affected by https://github.com/mpi-forum/mpi-standard/pull/954 in order of appearance in the document:

[ ] Terms (@cblaas)
[ ] Point-to-point (@Wee-Free-Scot)
[ ] Datatypes (@bosilca)
[ ] Collectives (@tonyskjellum)
[x] Groups & Communicators (@GuillaumeMercier)
[ ] Environment (@bosilca)
[x] Info (@schulzm)
[ ] Process Management (@bosilca)
[x] One-sided (@wgropp)
[ ] External Interfaces (@schulzm)
[ ] I/O (@tonyskjellum)
[ ] Tools (@mahermanns)
[ ] Changelog (@th-hlrs)
[ ] Language Bindings (@puribangalore)
[ ] Annex A (@puribangalore)

The changes in each chapter are relatively short so I would appreciate if the CCs could take a quick look at them.

Impact on Implementations

None.

Impact on Users

Improved navigation through the standard document.

References and Pull Requests

PR: https://github.com/mpi-forum/mpi-standard/pull/954

Other relevant PRs: https://github.com/mpi-forum/mpi-standard/pull/969 https://github.com/mpi-forum/mpi-standard/pull/967 https://github.com/mpi-forum/mpi-standard/pull/966

Issue for missing main definitions: https://github.com/mpi-forum/mpi-issues/issues/845

GuillaumeMercier commented 6 days ago

@devreal : I don't see the Topologies Chapter in your list. Is this intentional?

devreal commented 6 days ago

@GuillaumeMercier Yes because https://github.com/mpi-forum/mpi-standard/pull/954 does not affect the topologies chapter. That is addressed in https://github.com/mpi-forum/mpi-standard/pull/969.