Documentation beautification on the rst pages

[zerothi]

Is your feature request related to a problem? Please describe.
The new documentation produces some weird looking links on when viewed on a website

A reference: https://docs.open-mpi.org/en/v5.0.x/man-openmpi/man3/MPI_Win_allocate.3.html#mpi-win-allocate

Describe the solution you'd like
In the above link I would like to:

1. Change ERRORS.rst to list form of the

   Custom MPI error handlers can be created by calling: [MPI_Comm_create_errhandler(3)](https://docs.open-mpi.org/en/v5.0.x/man-openmpi/man3/MPI_Comm_create_errhandler.3.html#mpi-comm-create-errhandler) [MPI_File_create_errhandler(3)](https://docs.open-mpi.org/en/v5.0.x/man-openmpi/man3/MPI_File_create_errhandler.3.html#mpi-file-create-errhandler)[MPI_Session_create_errhandler(3)](https://docs.open-mpi.org/en/v5.0.x/man-openmpi/man3/MPI_Session_create_errhandler.3.html#mpi-session-create-errhandler) [MPI_Win_create_errhandler(3)](https://docs.open-mpi.org/en/v5.0.x/man-openmpi/man3/MPI_Win_create_errhandler.3.html#mpi-win-create-errhandler)
   
   Predefined and custom error handlers can be set by calling: [MPI_Comm_set_errhandler(3)](https://docs.open-mpi.org/en/v5.0.x/man-openmpi/man3/MPI_Comm_set_errhandler.3.html#mpi-comm-set-errhandler) [MPI_File_set_errhandler(3)](https://docs.open-mpi.org/en/v5.0.x/man-openmpi/man3/MPI_File_set_errhandler.3.html#mpi-file-set-errhandler) [MPI_Session_set_errhandler(3)](https://docs.open-mpi.org/en/v5.0.x/man-openmpi/man3/MPI_Session_set_errhandler.3.html#mpi-session-set-errhandler) [MPI_Win_set_errhandler(3)](https://docs.open-mpi.org/en/v5.0.x/man-openmpi/man3/MPI_Win_set_errhandler.3.html#mpi-win-set-errhandler)
   

   the above items would become a list of links (easier for the eye)
2. In the See Also section I would also like to make the entries a list in that case.
3. Try and fix the missing spaces in the Notes section.

I would not start these changes without confirmation, let me know if you think these changes would apply all-over the rst documentations. Also, if you want all in one PR? :)

• Beautification of ERRORS.rst
  • Listify the elements
  • add links to the routines listed
  • Remove (3) in function links
• Listify See also sections
• Add missing links across the man-pages
• Make constants and other code use backticks to highlight code pieces
• Once Documentation of global variables #11359 is completed, make links to the constants page (likely will be a separate PR)
• Remove references to "Sun Fortran" -- they can probably just be references to Fortran these days (one of the main initial authors of the nroff man pages was a docs writer at Sun)
• Make linking to man pages easier, per ideas like Beautification of rst documentation #11367 (comment)
• Move section 5 man pages to more appropriate sections (perhaps 7?)
• Copy code examples from deprecated routines to new (see MPI_Type_struct and MPI_Type_create_struct)

[jsquyres]

I agree -- ERRORS.rst can definitely be made a bit more beautiful.

In addition to what you suggest, I'd also turn the verbatim section under "Open MPI includes three predefined error handlers that can be used:" into a bullet list as well -- I'm not sure why it's a verbatim section.

I'm sure you're aware, but just to make sure we're on the same sheet of music: the verbatim markdown section you posted in the PR description won't be sufficient -- you'll need to use RST syntax, not MD syntax, and use relative links to link to the man pages, etc.

[zerothi]

I agree -- ERRORS.rst can definitely be made a bit more beautiful.

In addition to what you suggest, I'd also turn the verbatim section under "Open MPI includes three predefined error handlers that can be used:" into a bullet list as well -- I'm not sure why it's a verbatim section.

I'm sure you're aware, but just to make sure we're on the same sheet of music: the verbatim markdown section you posted in the PR description won't be sufficient -- you'll need to use RST syntax, not MD syntax, and use relative links to link to the man pages, etc.

Agreed, of course rst syntax ;) I'll have a jump!

[zerothi]

In addition, is the MPI_Comm_create_errhandler(3) <MPI_Comm_create_errhandler> really necessary? Would it be ok to remove (3)? I don't see it adding any information that isn't already present in the toc? It is clearly under man3.

[zerothi]

I'll add a list of items to the main post, then you can comment as we go by, I'll probably stumble upon more things ;)

[jsquyres]

In addition, is the MPI_Comm_create_errhandler(3) <MPI_Comm_create_errhandler> really necessary? Would it be ok to remove (3)? I don't see it adding any information that isn't already present in the toc? It is clearly under man3.

FWIW, we generally tried to list the man page section number in links to man pages in all the RST docs, which serves two purposes:

1. It emphasizes that the content we're referring to is another man page
   • E.g., it's helpful when you're reading the content via man MPI_Whatever (e.g., in a terminal), not in a pretty web page. Since the terminal-rendered man page won't have a link to click on, the (x) in the text gives the reader the clue that we're referring to another man page that they can see via man MPI_That_thing.
2. It shows which section the man page is in

Also FWIW: We didn't make up that convention; we took that convention of including the (x) in the reference from other man pages.

[zerothi]

But that is not enforced on any other references in that man3 section? If you want, then I would argue it should also be on all seealso references etc, no?

[jsquyres]

Yes, we should definitely be consistent in all references to man pages -- inline in text, in man pages, in see also, etc.

I'm just about to comment on the PR, but I'll say it here, too: we converted the man pages from wildly-inconsistent, handwritten nroff (which you can still see in the v4.1.x series) to RST via some scripting. We thought we did a pretty good job of catching most corner cases, but you have fixed a whole boatload more corner cases that our scripting fixed.

I.e., if you see inconsistencies like this -- particularly in the man pages -- it's almost certainly due to the initial wildly-inconsistent nroff source code for the man pages (which were written by different people at different times, so things weren't always uniform across all the man pages).

[zerothi]

I think this is just hurting the experience for those who use the web-documentation.

I would argue/think that most people use your web-page documentation and people viewing these pages will have no clue why the (3) is present. Rather few people will use the man pages. Just a guess ;)
Again I think this should be fixed via some mechanism in the conf.py. How exactly, I am not sure. But having (3) all over I must confess is just annoying ;)

[jsquyres]

Ok, I can buy that argument.

It would be awesome if we could have it render differently in HTML and nroff. Would it be possible to make an OMPI-specific macro/function/something (I don't know the correct RST / Sphinx terminology here) for linking to man pages? This would allow us to have a compact/easy notation in the .rst files, and it renders appropriately (without the (x) for HTML, and with the (x) for nroff)?

[zerothi]

I agree this approach would be the way to do it. See my small snippet and idea in the PR.