docs: replace many specific references to MPI-1

jsquyres · jsquyres · commit 5da4cfd0ecb8 · 2023-11-11T12:55:28.000-05:00
Where relevant, replace specific references to MPI-1 to generic
references to the MPI standard (linked out to the MPI Forum web site)
with either a chapter/section number that is still correct, or, if the
section/chapter number has changed over time, use the section/chapter
title (which is correct in both the old version of the MPI standard
and the current [MPI-4.1] version).

In a few places, this also carried a few trivial RST formatting
updates, and sections were re-flowed after adding the link to the MPI
Forum web site, but in general, no other text or content changed.

Signed-off-by: Jeff Squyres &lt;jeff@squyres.com&gt;
diff --git a/docs/man-openmpi/man3/MPI_Cancel.3.rst b/docs/man-openmpi/man3/MPI_Cancel.3.rst
@@ -74,7 +74,7 @@ loop for a canceled communication, then :ref:`MPI_Test` will eventually be
 successful.
 
 :ref:`MPI_Cancel` can be used to cancel a communication that uses a persistent
-request (see Section 3.9 in the MPI-1 Standard, "Persistent
+request (see Section 3.9 in the `MPI Standard <https://www.mpi-forum.org/docs/>`_, "Persistent
 Communication Requests") in the same way it is used for nonpersistent
 requests. A successful cancellation cancels the active communication,
 but not the request itself. After the call to :ref:`MPI_Cancel` and the
diff --git a/docs/man-openmpi/man3/MPI_Comm_dup.3.rst b/docs/man-openmpi/man3/MPI_Comm_dup.3.rst
@@ -63,15 +63,19 @@ determines the attribute value associated with this key in the new
 communicator; one particular action that a copy callback may take is to
 delete the attribute from the new communicator. Returns in newcomm a new
 communicator with the same group, any copied cached information, but a
-new context (see Section 5.7.1 of the MPI-1 Standard, "Functionality").
+new context (see the "Functionality" subsection of the "Caching"
+section in the "Groups, Contexts, and Communicators" chapter in the
+`MPI Standard <https://www.mpi-forum.org/docs/>`_).
+
 
 NOTES
 -----
 
 This operation is used to provide a parallel library call with a
 duplicate communication space that has the same properties as the
 original communicator. This includes any attributes (see below) and
-topologies (see Chapter 6, "Process Topologies," in the MPI-1 Standard).
+topologies (see the "Process Topologies" chapter in the `MPI Standard
+<https://www.mpi-forum.org/docs/>`_).
 This call is valid even if there are pending point-to-point
 communications involving the communicator comm. A typical call might
 involve an :ref:`MPI_Comm_dup` at the beginning of the parallel call, and an
diff --git a/docs/man-openmpi/man3/MPI_Comm_dup_with_info.3.rst b/docs/man-openmpi/man3/MPI_Comm_dup_with_info.3.rst
@@ -71,7 +71,8 @@ NOTES
 This operation is used to provide a parallel library call with a
 duplicate communication space that has the same properties as the
 original communicator. This includes any attributes (see below) and
-topologies (see Chapter 6, "Process Topologies," in the MPI-1 Standard).
+topologies (see the "Process Topologies" chapter in the `MPI Standard
+<https://www.mpi-forum.org/docs/>`_.
 This call is valid even if there are pending point-to-point
 communications involving the communicator comm. A typical call might
 involve an :ref:`MPI_Comm_dup_with_info` at the beginning of the parallel call,
diff --git a/docs/man-openmpi/man3/MPI_Comm_free.3.rst b/docs/man-openmpi/man3/MPI_Comm_free.3.rst
@@ -61,8 +61,10 @@ handle is set to MPI_COMM_NULL. Any pending operations that use this
 communicator will complete normally; the object is actually deallocated
 only if there are no other active references to it. This call applies to
 intracommunicators and intercommunicators. Upon actual deallocation, the
-delete callback functions for all cached attributes (see Section 5.7 in
-the MPI-1 Standard, "Caching") are called in arbitrary order.
+delete callback functions for all cached attributes (see the "Caching"
+section in the "Groups, Contexts, and Communicators" chapter in the
+`MPI Standard <https://www.mpi-forum.org/docs/>`_) are called in
+arbitrary order.
 
 
 NOTES
diff --git a/docs/man-openmpi/man3/MPI_Comm_idup.3.rst b/docs/man-openmpi/man3/MPI_Comm_idup.3.rst
@@ -67,8 +67,10 @@ respective copy callback function determines the attribute value
 associated with this key in the new communicator; one particular action
 that a copy callback may take is to delete the attribute from the new
 communicator. Returns in newcomm a new communicator with the same group,
-any copied cached information, but a new context (see Section 5.7.1 of
-the MPI-1 Standard, "Functionality"). The communicator returned in
+any copied cached information, but a new context (see the
+"Functionality" subsection of the "Caching" section in the "Groups,
+Contexts, and Communicators" chapter in the `MPI Standard
+<https://www.mpi-forum.org/docs/>`_).  The communicator returned in
 *newcomm* will not be available until the request is complete.
 
 The completion of a communicator duplication request can be determined
@@ -82,7 +84,8 @@ NOTES
 This operation is used to provide a parallel library call with a
 duplicate communication space that has the same properties as the
 original communicator. This includes any attributes (see below) and
-topologies (see Chapter 6, "Process Topologies," in the MPI-1 Standard).
+topologies (see the "Process Topologies" chapter in the `MPI Standard
+<https://www.mpi-forum.org/docs/>`_).
 This call is valid even if there are pending point-to-point
 communications involving the communicator comm. A typical call might
 involve an :ref:`MPI_Comm_idup` at the beginning of the parallel call, and an
diff --git a/docs/man-openmpi/man3/MPI_Comm_idup_with_info.3.rst b/docs/man-openmpi/man3/MPI_Comm_idup_with_info.3.rst
@@ -68,8 +68,10 @@ value, the respective copy callback function determines the attribute
 value associated with this key in the new communicator; one particular
 action that a copy callback may take is to delete the attribute from the
 new communicator. Returns in newcomm a new communicator with the same
-group, any copied cached information, but a new context (see Section
-5.7.1 of the MPI-1 Standard, "Functionality"). The communicator returned
+group, any copied cached information, but a new context
+(see the "Functionality" subsection of the "Caching"
+section in the "Groups, Contexts, and Communicators" chapter in the
+`MPI Standard <https://www.mpi-forum.org/docs/>`_).  The communicator returned
 in *newcomm* will not be available until the request is complete. The
 hints provided by the supplied *info* argument are associated with the
 output communicator.
@@ -85,7 +87,8 @@ NOTES
 This operation is used to provide a parallel library call with a
 duplicate communication space that has the same properties as the
 original communicator. This includes any attributes (see below) and
-topologies (see Chapter 6, "Process Topologies," in the MPI-1 Standard).
+topologies (see the "Process Topologies" chapter in the `MPI Standard
+<https://www.mpi-forum.org/docs/>`_).
 This call is valid even if there are pending point-to-point
 communications involving the communicator comm. A typical call might
 involve an :ref:`MPI_Comm_idup_with_info` at the beginning of the parallel
diff --git a/docs/man-openmpi/man3/MPI_Errhandler_create.3.rst b/docs/man-openmpi/man3/MPI_Errhandler_create.3.rst
@@ -78,7 +78,8 @@ may be written in Fortran.
 NOTE
 ----
 
-The MPI-1 Standard states that an implementation may make the output
+The `MPI Standard <https://www.mpi-forum.org/docs/>`_ states that an
+implementation may make the output
 value (errhandler) simply the address of the function. However, the
 action of :ref:`MPI_Errhandler_free` makes this impossible, since it is
 required to set the value of the argument to MPI_ERRHANDLER_NULL. In
diff --git a/docs/man-openmpi/man3/MPI_Get_count.3.rst b/docs/man-openmpi/man3/MPI_Get_count.3.rst
@@ -61,10 +61,11 @@ DESCRIPTION
 
 Returns the number of entries received. (We count entries, each of type
 datatype, not bytes.) The datatype argument should match the argument
-provided by the receive call that set the status variable. (As explained
-in Section 3.12.5 in the MPI-1 Standard, "Use of General Datatypes in
-Communication," :ref:`MPI_Get_count` may, in certain situations, return the
-value MPI_UNDEFINED.)
+provided by the receive call that set the status variable. As explained
+in the "Use of General Datatypes in Communication" section of the `MPI
+Standard <https://www.mpi-forum.org/docs/>`_.
+:ref:`MPI_Get_count` may, in certain situations, return the value
+MPI_UNDEFINED.
 
 The datatype argument is passed to :ref:`MPI_Get_count` to improve performance.
 A message might be received without counting the number of elements it
diff --git a/docs/man-openmpi/man3/MPI_Iprobe.3.rst b/docs/man-openmpi/man3/MPI_Iprobe.3.rst
@@ -81,10 +81,11 @@ returns in status the same value that would have been returned by
 :ref:`MPI_Recv`. Otherwise, the call returns *flag* = false, and leaves status
 undefined.
 
-If :ref:`MPI_Iprobe` returns *flag* = true, then the content of the status object
-can be subsequently accessed as described in Section 3.2.5 of the MPI-1
-Standard, "Return Status," to find the source, tag, and length of the
-probed message.
+If :ref:`MPI_Iprobe` returns *flag* = true, then the content of the
+status object can be subsequently accessed as described in the "Return
+Status" subsection of the "Point-to-Point Communication" chapter in
+the `MPI Standard <https://www.mpi-forum.org/docs/>`_ to find the
+source, tag, and length of the probed message.
 
 A subsequent receive executed with the same context, and the source and
 tag returned in status by :ref:`MPI_Iprobe` will receive the message that was
diff --git a/docs/man-openmpi/man3/MPI_Send.3.rst b/docs/man-openmpi/man3/MPI_Send.3.rst
@@ -74,7 +74,7 @@ NOTE
 
 This routine will block until the message is sent to the destination.
 For an in-depth explanation of the semantics of the standard-mode send,
-refer to the MPI-1 Standard.
+refer to the `MPI Standard <https://www.mpi-forum.org/docs/>`_.
 
 
 ERRORS
diff --git a/docs/man-openmpi/man3/MPI_Sendrecv.3.rst b/docs/man-openmpi/man3/MPI_Sendrecv.3.rst
@@ -92,8 +92,9 @@ example, even processes send, then receive; odd processes receive first,
 then send) in order to prevent cyclic dependencies that may lead to
 deadlock. When a send-receive operation is used, the communication
 subsystem takes care of these issues. The send-receive operation can be
-used in conjunction with the functions described in Chapter 6 of the
-MPI-1 Standard, "Process Topologies," in order to perform shifts on
+used in conjunction with the functions described in the "Process
+Topologies" chapter in the `MPI Standard
+<https://www.mpi-forum.org/docs/>`_ in order to perform shifts on
 various logical topologies. Also, a send-receive operation is useful for
 implementing remote procedure calls.
 
diff --git a/docs/man-openmpi/man3/MPI_Ssend.3.rst b/docs/man-openmpi/man3/MPI_Ssend.3.rst
@@ -66,8 +66,9 @@ OUTPUT PARAMETER
 DESCRIPTION
 -----------
 
-:ref:`MPI_Ssend` performs a synchronous-mode, blocking send. See the MPI-1
-Standard for more detailed information about such sends.
+:ref:`MPI_Ssend` performs a synchronous-mode, blocking send. See the
+`MPI Standard <https://www.mpi-forum.org/docs/>`_ for
+more detailed information about such sends.
 
 
 ERRORS
diff --git a/docs/man-openmpi/man3/MPI_Start.3.rst b/docs/man-openmpi/man3/MPI_Start.3.rst
@@ -72,7 +72,8 @@ until after the operation completes, the communication buffer should not
 be accessed.
 
 The call is local, with semantics similar to the nonblocking
-communication operations (see Section 3.7 in the MPI-1 Standard,
+communication operations (see Section 3.7 in the `MPI Standard
+<https://www.mpi-forum.org/docs/>`_,
 "Nonblocking Communication.") That is, a call to :ref:`MPI_Start` with a
 request created by :ref:`MPI_Send_init` starts a communication in the same
 manner as a call to :ref:`MPI_Isend`; a call to :ref:`MPI_Start` with a request
diff --git a/docs/man-openmpi/man3/MPI_Startall.3.rst b/docs/man-openmpi/man3/MPI_Startall.3.rst
@@ -70,13 +70,15 @@ A communication started with a call to :ref:`MPI_Start` or :ref:`MPI_Startall` i
 completed by a call to :ref:`MPI_Wait`, :ref:`MPI_Test`, or one of the derived
 functions :ref:`MPI_Waitany`, :ref:`MPI_Testany`, :ref:`MPI_Waitall`, :ref:`MPI_Testall`,
 :ref:`MPI_Waitsome`, :ref:`MPI_Testsome` (these are described in Section 3.7.5 of the
-MPI-1 Standard, "Multiple Completions"). The request becomes inactive
+`MPI Standard <https://www.mpi-forum.org/docs/>`_, "Multiple
+Completions"). The request becomes inactive
 after successful completion by such a call. The request is not
 deallocated, and it can be activated anew by another :ref:`MPI_Start` or
 :ref:`MPI_Startall` call.
 
-A persistent request is deallocated by a call to :ref:`MPI_Request_free` (see
-Section 3.7.3 of the MPI-1 Standard, "Communication Completion").
+A persistent request is deallocated by a call to
+:ref:`MPI_Request_free` (see Section 3.7.3 of the `MPI Standard
+<https://www.mpi-forum.org/docs/>`_, "Communication Completion").
 
 | The call to :ref:`MPI_Request_free` can occur at any point in the program
   after the persistent request was created. However, the request will be
diff --git a/docs/man-openmpi/man3/MPI_Test.3.rst b/docs/man-openmpi/man3/MPI_Test.3.rst
@@ -70,10 +70,12 @@ false, otherwise. In this case, the value of the status object is
 undefined. :ref:`MPI_Test` is a local operation.
 
 The return status object for a receive operation carries information
-that can be accessed as described in Section 3.2.5 of the MPI-1
-Standard, "Return Status." The status object for a send operation
-carries information that can be accessed by a call to :ref:`MPI_Test_cancelled`
-(see Section 3.8 of the MPI-1 Standard, "Probe and Cancel").
+that can be accessed as described in the "Return Status" subsection of
+the "Point-to-Point Communication" chapter in the `MPI Standard
+<https://www.mpi-forum.org/docs/>`_. The status object for a send
+operation carries information that can be accessed by a call to
+:ref:`MPI_Test_cancelled` (see the "Probe and Cancel" section of the
+`MPI Standard <https://www.mpi-forum.org/docs/>`_).
 
 If your application does not need to examine the *status* field, you can
 save resources by using the predefined constant ``MPI_STATUS_IGNORE`` as a
diff --git a/docs/man-openmpi/man3/MPI_Type_contiguous.3.rst b/docs/man-openmpi/man3/MPI_Type_contiguous.3.rst
@@ -96,8 +96,8 @@ defined by:
        disp(n-1) + ex), ...,(type(0), disp(0) + ex * (count - 1)),
        ...,(type(n-1), disp(n-1) + ex * (count - 1))}.
 
-For more information about derived datatypes, see Section 3.12 of the
-MPI-1 Standard.
+For more information about derived datatypes, see the Datatypes
+chapter in the `MPI Standard <https://www.mpi-forum.org/docs/>`_.
 
 
 ERRORS
diff --git a/docs/man-openmpi/man3/MPI_Type_create_darray.3.rst b/docs/man-openmpi/man3/MPI_Type_create_darray.3.rst
@@ -93,7 +93,7 @@ For a call to :ref:`MPI_Type_create_darray` to be correct, the equation
 
 must be satisfied. The ordering of processes in the process grid is
 assumed to be row-major, as in the case of virtual Cartesian process
-topologies in MPI-1.
+topologies in the `MPI Standard <https://www.mpi-forum.org/docs/>`_.
 
 Each dimension of the array can be distributed in one of three ways:
 
diff --git a/docs/man-openmpi/man3/MPI_Type_create_hvector.3.rst b/docs/man-openmpi/man3/MPI_Type_create_hvector.3.rst
@@ -73,8 +73,9 @@ in bytes. This routine replaces :ref:`MPI_Type_hvector`, which is deprecated.
 
 The function :ref:`MPI_Type_create_hvector` is identical to :ref:`MPI_Type_vector`, except
 that stride is given in bytes, rather than in elements. The use for both
-types of vector constructors is illustrated in the examples in Section
-3.12.7 of the MPI-1 Standard.
+types of vector constructors is illustrated in the examples in the
+Datatype chapter of the `MPI Standard
+<https://www.mpi-forum.org/docs/>`_.
 
 Assume that oldtype has type map
 
diff --git a/docs/man-openmpi/man3/MPI_Type_get_contents.3.rst b/docs/man-openmpi/man3/MPI_Type_get_contents.3.rst
@@ -110,9 +110,10 @@ that was constructed using :ref:`MPI_Type_create_f90_real`,
 predefined data type). In such a case, an empty *array_of_datatypes is
 returned.*
 
-In the MPI-1 data-type constructor calls, the address arguments in
-Fortran are of type INTEGER. In the new MPI-2 calls, the address
-arguments are of type INTEGER(KIND=MPI_ADDRESS_KIND). The call
+In the legacy MPI-1 datatype constructor calls, the address arguments in
+Fortran are of type ``INTEGER``. In subsequent versions of the `MPI
+Standard <https://www.mpi-forum.org/docs/>`_, the address
+arguments are of type ``INTEGER(KIND=MPI_ADDRESS_KIND)``. The call
 :ref:`MPI_Type_get_contents` returns all addresses in an argument of type
 INTEGER(KIND=MPI_ADDRESS_KIND). This is true even if the old MPI-1 calls
 were used. Thus, the location of values returned can be thought of as
diff --git a/docs/man-openmpi/man3/MPI_Wait.3.rst b/docs/man-openmpi/man3/MPI_Wait.3.rst
@@ -64,12 +64,14 @@ created by a nonblocking send or receive call, then the object is
 deallocated by the call to :ref:`MPI_Wait` and the request handle is set to
 ``MPI_REQUEST_NULL``.
 
-The call returns, in status, information on the completed operation. The
-content of the status object for a receive operation can be accessed as
-described in Section 3.2.5 of the MPI-1 Standard, "Return Status." The
-status object for a send operation may be queried by a call to
-:ref:`MPI_Test_cancelled` (see Section 3.8 of the MPI-1 Standard, "Probe and
-Cancel").
+The call returns, in status, information on the completed
+operation. The content of the status object for a receive operation
+can be accessed as described in the "Return Status" subsection of the
+"Point-to-Point Communication" chapter in the `MPI Standard
+<https://www.mpi-forum.org/docs/>`_.  The status object for a send
+operation may be queried by a call to :ref:`MPI_Test_cancelled` (see
+the "Probe and Cancel" section in the `MPI Standard
+<https://www.mpi-forum.org/docs/>`_).
 
 If your application does not need to examine the *status* field, you can
 save resources by using the predefined constant ``MPI_STATUS_IGNORE`` as a
@@ -86,8 +88,9 @@ NOTES
 Successful return of :ref:`MPI_Wait` after an :ref:`MPI_Ibsend` implies that the user
 send buffer can be reused i.e., data has been sent out or copied into a
 buffer attached with :ref:`MPI_Buffer_attach`. Note that, at this point, we can
-no longer cancel the send (for more information, see Section 3.8 of the
-MPI-1 Standard, "Probe and Cancel"). If a matching receive is never
+no longer cancel the send (for more information, see the "Probe and
+Cancel" section in the `MPI Standard
+<https://www.mpi-forum.org/docs/>`_).  If a matching receive is never
 posted, then the buffer cannot be freed. This runs somewhat counter to
 the stated goal of :ref:`MPI_Cancel` (always being able to free program space
 that was committed to the communication subsystem).
