Merge pull request #11392 from zerothi/11340-2-beautification

Continuation of the beautifaction process

Author: jsquyres

docs/Makefile.am

@@ -415,6 +415,7 @@ OMPI_MAN3 = \
         MPI_Status_set_cancelled.3 \
         MPI_Status_set_elements.3 \
         MPI_Status_set_elements_x.3 \
+        MPI_T.3 \
         MPI_T_category_changed.3 \
         MPI_T_category_get_categories.3 \
         MPI_T_category_get_cvars.3 \
@@ -542,9 +543,8 @@ OMPI_MAN3 = \
         MPIX_Query_rocm_support.3 \
         OMPI_Affinity_str.3
 
-OMPI_MAN5 = \
-        MPI_T.5 \
-        Open-MPI.5
+OMPI_MAN7 = \
+        Open-MPI.7
 
 OSHMEM_MAN1 = \
         oshmem-wrapper-compiler.1 \
@@ -779,8 +779,8 @@ OMPI_MAN1_BUILT = $(OMPI_MAN1:%.1=$(MAN_OUTDIR)/%.1)
 OMPI_MAN3_RST = $(OMPI_MAN3:%.3=man-openmpi/man3/%.3.rst)
 OMPI_MAN3_BUILT = $(OMPI_MAN3:%.3=$(MAN_OUTDIR)/%.3)
 
-OMPI_MAN5_RST = $(OMPI_MAN5:%.5=man-openmpi/man5/%.5.rst)
-OMPI_MAN5_BUILT = $(OMPI_MAN5:%.5=$(MAN_OUTDIR)/%.5)
+OMPI_MAN7_RST = $(OMPI_MAN7:%.7=man-openmpi/man7/%.7.rst)
+OMPI_MAN7_BUILT = $(OMPI_MAN7:%.7=$(MAN_OUTDIR)/%.7)
 
 OSHMEM_MAN1_RST = $(OSHMEM_MAN1:%.1=man-oshmem/man1/%.1.rst)
 OSHMEM_MAN1_BUILT = $(OSHMEM_MAN1:%.1=$(MAN_OUTDIR)/%.1)
@@ -791,7 +791,7 @@ OSHMEM_MAN3_BUILT = $(OSHMEM_MAN3:%.3=$(MAN_OUTDIR)/%.3)
 EXTRA_DIST += \
         $(OMPI_MAN1_BUILT) \
         $(OMPI_MAN3_BUILT) \
-        $(OMPI_MAN5_BUILT) \
+        $(OMPI_MAN7_BUILT) \
         $(OSHMEM_MAN1_BUILT) \
         $(OSHMEM_MAN3_BUILT)
 
@@ -852,7 +852,7 @@ EXTRA_DIST += \
         $(OUTDIR)/man
 
 ALL_MAN_BUILT = \
-        $(OMPI_MAN1_BUILT) $(OMPI_MAN3_BUILT) $(OMPI_MAN5_BUILT) \
+        $(OMPI_MAN1_BUILT) $(OMPI_MAN3_BUILT) $(OMPI_MAN7_BUILT) \
         $(OSHMEM_MAN1_BUILT) $(OSHMEM_MAN_3_BUILT)
 $(ALL_MAN_BUILT): $(RST_SOURCE_FILES) $(IMAGE_SOURCE_FILES)
 $(ALL_MAN_BUILT): $(TEXT_SOURCE_FILES) $(SPHINX_CONFIG)
@@ -903,7 +903,7 @@ man1_MANS += $(OMPI_MAN1_JAVA_REDIRECTS)
 endif
 
 man3_MANS = $(OMPI_MAN3_BUILT)
-man5_MANS = $(OMPI_MAN5_BUILT)
+man7_MANS = $(OMPI_MAN7_BUILT)
 
 if PROJECT_OSHMEM
 man1_MANS += \

docs/conf.py

@@ -131,6 +131,15 @@
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'venv', 'py*/**']
 
 
+# Clarify the language for verbatim blocks (::)
+# Never change this to anything else. Lots of verbatim code blocks
+# exists across the documentation pages.
+# The default value is actually "default" which is something like Python3
+# and on fail it reverts to "none". We just go directly to none for clarity.
+highlight_language = "none"
+
+
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -212,5 +221,6 @@ def _doit(topdir):
 .. |flex_min_version| replace:: {flex_min_version}
 .. |mpi_standard_version| replace:: {mpi_standard_version}
 .. |mpi_standard_subversion| replace:: {mpi_standard_subversion}
+.. |deprecated_favor| replace:: this routine is deprecated in favor of
 
 """

docs/man-openmpi/index.rst

@@ -19,4 +19,4 @@ Open MPI man pages, by section:
 
    man1/index
    man3/index
-   man5/index
+   man7/index

docs/man-openmpi/man3/MPI_Accumulate.3.rst

@@ -33,8 +33,8 @@ C Syntax
    	MPI_Request *request)
 
 
-Fortran Syntax (see FORTRAN 77 NOTES)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Fortran Syntax
+^^^^^^^^^^^^^^
 
 .. code-block:: fortran
 
@@ -138,21 +138,6 @@ indicates that the *origin_addr* buffer is free to be updated. It does
 not indicate that the operation has completed at the target window.
 
 
-FORTRAN 77 NOTES
-----------------
-
-The MPI standard prescribes portable Fortran syntax for the
-*TARGET_DISP* argument only for Fortran 90. FORTRAN 77 users may use the
-non-portable syntax
-
-.. code-block:: fortran
-
-        INTEGER*MPI_ADDRESS_KIND TARGET_DISP
-
-where ``MPI_ADDRESS_KIND`` is a constant defined in ``mpif.h`` and gives the
-length of the declared integer in bytes.
-
-
 NOTES
 -----
 

docs/man-openmpi/man3/MPI_Address.3.rst

@@ -6,8 +6,7 @@ MPI_Address
 
 .. include_body
 
-:ref:`MPI_Address` - Gets the address of a location in memory -- use of
-this routine is deprecated.
+:ref:`MPI_Address` - Gets the address of a location in memory -- |deprecated_favor| :ref:`MPI_Get_address`.
 
 
 SYNTAX
@@ -29,7 +28,9 @@ Fortran Syntax
 
 .. code-block:: fortran
 
-   INCLUDE 'mpif.h'
+   USE MPI
+   ! or the older form: INCLUDE 'mpif.h'
+
    MPI_ADDRESS(LOCATION, ADDRESS, IERROR)
    	<type>	LOCATION (*)
    	INTEGER	ADDRESS, IERROR
@@ -50,40 +51,6 @@ DESCRIPTION
 Note that use of this routine is *deprecated* as of MPI-2. Please use
 :ref:`MPI_Get_address` instead.
 
-The address of a location in memory can be found by invoking this
-function. Returns the (byte) address of location.
-
-Example: Using :ref:`MPI_Address` for an array.
-
-.. code-block:: fortran
-
-   REAL A(100,100)
-
-   INTEGER I1, I2, DIFF
-   CALL MPI_ADDRESS(A(1,1), I1, IERROR)
-   CALL MPI_ADDRESS(A(10,10), I2, IERROR)
-   DIFF = I2 - I1
-   ! The value of DIFF is 909*sizeof(real)
-   !the values of I1 and I2 are implementation dependent.
-
-
-NOTES
------
-
-This routine is provided for both Fortran and C programmers and may be
-useful when writing portable code. In the current release, the address
-returned by this routine will be the same as that produced by the C ``&``
-operator.
-
-C users may be tempted to avoid using :ref:`MPI_Address` and rely on the
-availability of the address operator &. Note, however, that &
-cast-expression is a pointer, not an address. ANSI C does not require
-that the value of a pointer (or the pointer cast to int) be the absolute
-address of the object pointed at although this is commonly the case.
-Furthermore, referencing may not have a unique definition on machines
-with a segmented address space. The use of :ref:`MPI_Address` to "reference" C
-variables guarantees portability to such machines as well.
-
 
 ERRORS
 ------

docs/man-openmpi/man3/MPI_Alloc_mem.3.rst

@@ -23,8 +23,8 @@ C Syntax
    int MPI_Alloc_mem(MPI_Aint size, MPI_Info info, void *baseptr)
 
 
-Fortran Syntax (see FORTRAN NOTES)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Fortran Syntax
+^^^^^^^^^^^^^^
 
 .. code-block:: fortran
 
@@ -74,40 +74,31 @@ pointer object for this parameter. The provided argument should be a
 pointer to a pointer of arbitrary type (e.g., ``void **``).
 
 
-FORTRAN NOTES
+Fortran NOTES
 -------------
 
-There is no portable FORTRAN 77 syntax for using :ref:`MPI_Alloc_mem`. There is
-no portable Fortran syntax for using pointers returned from
-:ref:`MPI_Alloc_mem`. However, :ref:`MPI_Alloc_mem` can be used with Sun Fortran
-compilers.
-
-From FORTRAN 77, you can use the following non-standard declarations for
-the SIZE and BASEPTR arguments:
+The :ref:`MPI_Alloc_mem` calls require the use of the ``iso_c_binding`` module
+for due to the use of ``TYPE(C_PTR)``.
 
 .. code-block:: fortran
 
-              INCLUDE "mpif.h"
-              INTEGER*MPI_ADDRESS_KIND SIZE, BASEPTR
-	      
-
-From either FORTRAN 77 or Fortran 90, you can use "Cray pointers" for
-the BASEPTR argument. Cray pointers are described further in the Fortran
-User's Guide and are supported by many Fortran compilers. For example,
+   use iso_c_binding
 
-.. code-block:: fortran
+   type(c_ptr) :: alloc_ptr
+   integer :: size, ierr
+   double precision, pointer :: array(:,:)
 
-              INCLUDE "mpif.h"
-              REAL*4 A(100,100)
-              POINTER (BASEPTR, A)
-              INTEGER*MPI_ADDRESS_KIND SIZE
+   ! A 2D array of 100 elements
+   size = 10 * 10
+   call MPI_Alloc_Mem(size * 8, MPI_INFO_NULL, alloc_ptr, ierr)
 
-              SIZE = 4 * 100 * 100
-              CALL MPI_ALLOC_MEM(SIZE,MPI_INFO_NULL,BASEPTR,IERR)
+   ! Point to the array
+   call c_f_pointer(alloc_ptr, array, [10, 10])
 
-              ! use A
+   ! ... use the array ...
 
-              CALL MPI_FREE_MEM(A, IERR)
+   ! Free the memory, no need for the alloc_ptr
+   call MPI_Free_mem(array, ierr)
 
 
 ERRORS

docs/man-openmpi/man3/MPI_Attr_delete.3.rst

@@ -6,8 +6,7 @@ MPI_Attr_delete
 
 .. include_body
 
-:ref:`MPI_Attr_delete` - Deletes attribute value associated with a key --
-use of this routine is deprecated.
+:ref:`MPI_Attr_delete` - Deletes attribute value associated with a key -- |deprecated_favor| :ref:`MPI_Comm_delete_attr`.
 
 
 SYNTAX
@@ -29,7 +28,9 @@ Fortran Syntax
 
 .. code-block:: fortran
 
-   INCLUDE 'mpif.h'
+   USE MPI
+   ! or the older form: INCLUDE 'mpif.h'
+
    MPI_ATTR_DELETE(COMM, KEYVAL, IERROR)
    	INTEGER	COMM, KEYVAL, IERROR
 
@@ -50,27 +51,6 @@ Note that use of this routine is *deprecated* as of MPI-2, and was
 *deleted* in MPI-3. Please use :ref:`MPI_Comm_delete_attr`. This function does
 not have a mpi_f08 binding.
 
-Delete attribute from cache by key. This function invokes the attribute
-delete function delete_fn specified when the keyval was created. The
-call will fail if the delete_fn function returns an error code other
-than MPI_SUCCESS.
-
-Whenever a communicator is replicated using the function :ref:`MPI_Comm_dup`,
-all callback copy functions for attributes that are currently set are
-invoked (in arbitrary order). Whenever a communicator is deleted using
-the function :ref:`MPI_Comm_free`, all callback delete functions for attributes
-that are currently set are invoked.
-
-
-NOTES
------
-
-Note that it is not defined by the MPI standard what happens if the
-delete_fn callback invokes other MPI functions. In Open MPI, it is not
-valid for delete_fn callbacks (or any of their children) to add or
-delete attributes on the same object on which the delete_fn callback is
-being invoked.
-
 
 ERRORS
 ------

docs/man-openmpi/man3/MPI_Attr_get.3.rst

@@ -6,8 +6,7 @@ MPI_Attr_get
 
 .. include_body
 
-:ref:`MPI_Attr_get` - Retrieves attribute value by key -- use of this
-routine is deprecated.
+:ref:`MPI_Attr_get` - Retrieves attribute value by key -- |deprecated_favor| :ref:`MPI_Comm_get_attr`.
 
 
 SYNTAX
@@ -30,7 +29,9 @@ Fortran Syntax
 
 .. code-block:: fortran
 
-   INCLUDE 'mpif.h'
+   USE MPI
+   ! or the older form: INCLUDE 'mpif.h'
+
    MPI_ATTR_GET(COMM, KEYVAL, ATTRIBUTE_VAL, FLAG, IERROR)
    	INTEGER	COMM, KEYVAL, ATTRIBUTE_VAL, IERROR
    	LOGICAL	FLAG
@@ -54,12 +55,6 @@ Note that use of this routine is *deprecated* as of MPI-2, and was
 *deleted* in MPI-3. Please use :ref:`MPI_Comm_get_attr`. This function does not
 have a mpi_f08 binding.
 
-Retrieves attribute value by key. The call is erroneous if there is no
-key with value keyval. On the other hand, the call is correct if the key
-value exists, but no attribute is attached on comm for that key; in such
-case, the call returns flag = false. In particular MPI_KEYVAL_INVALID is
-an erroneous key value.
-
 
 ERRORS
 ------

docs/man-openmpi/man3/MPI_Attr_put.3.rst

@@ -6,8 +6,8 @@ MPI_Attr_put
 
 .. include_body
 
-:ref:`MPI_Attr_put` - Stores attribute value associated with a key -- use
-of this routine is deprecated.
+:ref:`MPI_Attr_put` - Stores attribute value associated with a key -- |deprecated_favor| :ref:`MPI_Comm_set_attr`.
+
 
 
 SYNTAX
@@ -29,7 +29,9 @@ Fortran Syntax
 
 .. code-block:: fortran
 
-   INCLUDE 'mpif.h'
+   USE MPI
+   ! or the older form: INCLUDE 'mpif.h'
+
    MPI_ATTR_PUT(COMM, KEYVAL, ATTRIBUTE_VAL, IERROR)
    	INTEGER	COMM, KEYVAL, ATTRIBUTE_VAL, IERROR
 
@@ -51,31 +53,6 @@ Note that use of this routine is *deprecated as of MPI-2, and* was
 deleted in MPI-3. Please use :ref:`MPI_Comm_set_attr`. This function does not
 have a mpi_f08 binding.
 
-:ref:`MPI_Attr_put` stores the stipulated attribute value attribute_val for
-subsequent retrieval by :ref:`MPI_Attr_get`. If the value is already present,
-then the outcome is as if :ref:`MPI_Attr_delete` was first called to delete the
-previous value (and the callback function delete_fn was executed), and a
-new value was next stored. The call is erroneous if there is no key with
-value keyval; in particular MPI_KEYVAL_INVALID is an erroneous key
-value. The call will fail if the delete_fn function returned an error
-code other than MPI_SUCCESS.
-
-
-NOTES
------
-
-Values of the permanent attributes MPI_TAG_UB, MPI_HOST, MPI_IO, and
-MPI_WTIME_IS_GLOBAL may not be changed.
-
-The type of the attribute value depends on whether C or Fortran is being
-used. In C, an attribute value is a pointer (``void *``); in Fortran, it is
-a single integer (not a pointer, since Fortran has no pointers and there
-are systems for which a pointer does not fit in an integer, e.g., any
-32-bit address system that uses 64 bits for Fortran DOUBLE PRECISION).
-
-If an attribute is already present, the delete function (specified when
-the corresponding keyval was created) will be called.
-
 
 ERRORS
 ------