Add hyperref links for MPI symbols throughout the standard

[devreal]

Problem

It is hard to navigate through the standard because both the PDF and HTML versions are lacking hyperlinks. By adding hyperlinks to both versions users can jump to the definition of a symbol (function, datatype, error handler) without having to use the document search function.

Proposal

Extend the corresponding LaTeX macros to add a \hypertarget to \*main macros and link to it in the non-main macros (except for skip macros).

Changes to the Text

No changes to the text, except for the cleanup of erroneous macro usage in https://github.com/mpi-forum/mpi-issues/issues/825. All other changes are solely in the user-facing macros.

Impact on Implementations

None

Impact on Users

Hyperlinks make users happy.

References and Pull Requests

Initial draft of the hyperref integration: https://github.com/mpi-forum/mpi-standard/pull/954

[bkmgit]

Some changes to the workflow maybe needed to generate an HTML version.

[devreal]

I had seen this HTML version we're hosting but didn't realize that it's MPI 2.2. We should probably update that.

https://www.mpi-forum.org/docs/mpi-2.2/mpi22-report/mpi22-report.htm

[wgropp]

There are more recent HTML versions - see the docs page. They aren't perfect; there might be a tool that can better handle the LaTeX in the standard now, but there wasn't the last time I checked (which was probably > 10 years ago).

[devreal]

Ahh that's right. Somehow Google gave me links to the 2.2 version. I tried to build the html version of the standard (make HTMLVERSION) but I'm missing tohtml and cannot figure out what package that belongs to.

@bkmgit What changes do you think would be needed?

[bkmgit]

Ahh that's right. Somehow Google gave me links to the 2.2 version. I tried to build the html version of the standard (|make HTMLVERSION|) but I'm missing |tohtml| and cannot figure out what package that belongs to. Clearly not on Arch: https://man.archlinux.org/man/tohtml.1.en

@bkmgit https://github.com/bkmgit What changes do you think would be needed?

Gemini support. For html, dark mode.

[wgropp]

tohtml is part of a very old package of tools I used to automate some elements of package development. I'm in the midst of enhancing tohtml to address some of the shortcomings in the 4.1 version.

[bkmgit]

If a license (preferably one that is well known and used for other free and open source HPC software) could be added, that would really help inclusion in other linux distributions. Can add dark mode support. Maybe easier to create a separate derivative package togemini, can do this, but not the highest priority.

[wgropp]

Can you point me at an example of what it should look like? Normally, text is copyrighted, not licensed, though I can see there's a grey area with HTML.

Dark mode is non-trivial, because some more complex LaTeX is currently handled by generating an image directly from the LaTeX, then including that image. But I can also look into this (tohtml dates from long before CSS, and so has a very old-fashioned HTML output).

[bkmgit]

License is for the sowing package. Made a pull request to add MPICH license: https://bitbucket.org/petsc/pkg-sowing/pull-requests/ Arch package lists GPL, but does not indicate which version and if it is that version only or that version or later: https://gitlab.archlinux.org/archlinux/packaging/packages/sowing/-/blob/main/PKGBUILD There is no documentation as to what is appropriate distributed with the source package. Probably relevant evaluators are https://otm.illinois.edu/disclose-protect/open-source-licensing and for Argonne from https://github.com/Argonne-National-Laboratory opensource at anl dot gov

For the standard, probably SPI would hold rights but some agreement would be needed.

[bkmgit]

Created separate issue for document and code licensing https://github.com/mpi-forum/mpi-issues/issues/827