SQUASHME: Suggestions from Jeff Sq

Signed-off-by: Jeff Squyres <jsquyres@cisco.com>

Author: jsquyres

docs/app-debug/mpir-tools.rst

@@ -13,27 +13,29 @@ This specification has been replaced by the PMIx tools API that is part of the
 `OpenPMIx project <https://openpmix.github.io/>`_.
 
 Debuggers and tools which use the legacy MPIR specification can
-continue functioning correctly with the *MPIR shim module* described
-in this section.
+continue functioning correctly with the `MPIR shim module
+<https://github.com/hpc/mpir-to-pmix-guide>`_ described in this
+section.
 
 Obtaining Application Process Mapping Information
 -------------------------------------------------
 
-The *MPIR shim module* is a stand-alone module which can be used by
-debuggers and tools that still utilize the legacy MPIR interface to
-attach to parallel MPI applications.  The debugger or tool launches
-the shim module as an intermediate process between it and the
-application's :ref:`mpirun(1) <man1-mpirun>` command.
+The `MPIR shim module <https://github.com/hpc/mpir-to-pmix-guide>`_ is
+a stand-alone module which can be used by debuggers and tools that
+still utilize the legacy MPIR interface to attach to parallel MPI
+applications.  The debugger or tool launches the shim module as an
+intermediate process between it and the application's :ref:`mpirun(1)
+<man1-mpirun>` command.
 
 The MPIR shim module implements the ``MPIR_Breakpoint`` function, as a
 hook where debuggers and tools can set a breakpoint to read the MPIR
 processing mapping when it is available.
 
 Instructions for use of the shim module are available at
-`<https://github.com/hpc/mpir-to-pmix-guide/blob/master/README.md>`_.
+https://github.com/hpc/mpir-to-pmix-guide/blob/master/README.md.
 
-You may need to build this module before you can use it. The source code for this
-module can be downloaded from
+You may need to build this shim module before you can use it. The
+source code for this module can be downloaded from
 `MPIR to PMIx Shim repository <https://github.com/hpc/mpir-to-pmix-guide>`_.
 
 Once you have the MPIR shim module built and installed, follow the

docs/app-debug/parallel-debug.rst

@@ -1,22 +1,23 @@
 Using Parallel Debuggers to Debug Open MPI Applications
 =======================================================
 
-Open MPI supports the TotalView API for attaching to parallel processes, which
-several parallel debuggers support (e.g., DDT, fx2).
-As part of v1.2.4 (released in September 2007), Open MPI also supports
-the TotalView API for viewing message queues in running MPI processes.
-
 Debugging with TotalView
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-This has changed with different releases of TotalView and Open MPI; it
-is best to consult TotalView's documentation for how you should debug
-Open MPI applications with TotalView.
+Debugging MPI applications has changed with different releases of
+TotalView and Open MPI; it is best to consult TotalView's
+documentation for how you should debug Open MPI applications with
+TotalView.
+
+Starting with Open MPI v5.0.0, debugging with Totalview requires the
+use of the MPIR shim module to attach to MPI processes.  See the
+:ref:`using MPIR-based tools with Open MPI section
+<using-mpir-based-tools-label>` for instructions on building and
+installing the MPIR shim module.
 
-As of Open MPI 5.0, debugging with Totalview requires the use of the MPIR
-shim module.  See the 
-:ref:`using MPIR-based tools with Open MPI section <using-mpir-based-tools-label>`
-for instructions on building and installing the MPIR shim module.
+Once TotalView is attached to Open MPI processes, it can also view
+Open MPI's message queues (for some transports), which can aid in
+debugging.
 
 .. note:: The integration of Open MPI message queue support is
    problematic with 64-bit versions of TotalView prior to v8.3:
@@ -30,12 +31,11 @@ for instructions on building and installing the MPIR shim module.
    There are two workarounds:
 
    * Use a 32-bit version of TotalView
-   * Upgrade to TotalView v8.3
+   * Upgrade to TotalView v8.3 or later
 
 Debugging with DDT
 ~~~~~~~~~~~~~~~~~~
 
-This has changed with different releases of DDT and Open MPI; it is
-best to consult DDT's documentation for how you should debug Open MPI
-applications with DDT.
-
+Debugging MPI application with DDT has changed with different releases
+of DDT and Open MPI; it is best to consult DDT's documentation for how
+you should debug Open MPI applications with DDT.

docs/building-apps/index.rst

@@ -13,16 +13,13 @@ Open MPI "wrapper" compilers.
    removed-mpi-constructs
    deprecation-warnings
    building-static-apps
-   building-multithreaded-apps
-   building-heterogeneous-apps
-   dynamic-loading
-   fork-system-popen
 
-.. warning:: Open MPI does not attempt to interface to other MPI
-    implementations, nor executables that were compiled for them.
-    MPI applications need to be compiled and linked with Open MPI in order to
-    run under Open MPI.
+.. warning:: Open MPI does not attempt to interoperate with other MPI
+             implementations, nor executables that were compiled for
+             them.  MPI applications need to be compiled and linked
+             with Open MPI in order to run under Open MPI.
 
-    See the :doc:`section on Open MPI's version numbering scheme </version-numbering>`
-    for information about binary compatibility between different versions of
-    Open MPI for applications compiled with another version.
+             See the :doc:`section on Open MPI's version numbering
+             scheme </version-numbering>` for information about binary
+             compatibility between different versions of Open MPI for
+             applications compiled with another version.

docs/installing-open-mpi/compilers-and-flags.rst

@@ -150,4 +150,3 @@ runtime libraries with Open MPI:
 .. code-block::
 
    shell$ ./configure CC=icc CXX=icpc FC=ifort LDFLAGS=-Wc,-static-intel ...
-

docs/tuning-apps/custom-components.rst renamed to docs/installing-open-mpi/custom-components.rst

@@ -1,4 +1,4 @@
-.. _tuning-custom-components:
+.. _installing-custom-components-label:
 
 Installing custom components
 ============================
@@ -31,4 +31,3 @@ run MPI jobs, then you need to ensure that it is visible on all nodes
 filesystem installs, or by installing them in a directory that is
 visible to all nodes via a networked filesystem).  Open MPI does not
 automatically send components to remote nodes when MPI jobs are run.
-

docs/installing-open-mpi/index.rst

@@ -17,6 +17,7 @@ Building and installing Open MPI
    configure-output-summary
    make-targets
    installation-location
+   custom-components
    updating
    packagers
    sysadmins

docs/installing-open-mpi/installation-location.rst

@@ -16,8 +16,8 @@ nodes without using a password, etc.).
 Regardless of whether Open MPI is installed on a shared / networked
 filesystem or independently on each node, it is usually easiest if
 Open MPI is available in the same filesystem path on every node.
-For example, if you install Open MPI to ``/opt/openmpi-$ver_current`` on
-one node, ensure that it is available in ``/opt/openmpi-$ver_current``
+For example, if you install Open MPI to ``/opt/openmpi-|ompi_ver|`` on
+one node, ensure that it is available in ``/opt/openmpi-|ompi_ver|``
 on *all* nodes.
 
 .. important:: For simplicity, the Open MPI team *strongly* recommends
@@ -313,5 +313,3 @@ error) in some cases, and definitely does not work in other cases.
 There's unfortunately little that we can do about this |mdash| it's a
 compiler compatibility issue, and one that compiler authors have
 little incentive to resolve.
-
-

docs/installing-open-mpi/required-support-libraries.rst

@@ -234,8 +234,9 @@ on Mac OS because:
    tarballs).
 #. In MacOS, it is common for `Homebrew <https://brew.sh/>`_ or
    `MacPorts <https://www.macports.org/>`_ to install:
-   * hwloc and/or Libevent
-   * gcc and gfortran
+   
+   * `Hardware Locality <https://www.open-mpi.org/projects/hwloc/>`_
+   * `Libevent <https://libevent.org/>`_
 
 For example, as of July 2019, Homebrew:
 

docs/installing-open-mpi/supported-systems.rst

@@ -65,4 +65,3 @@ resources.
 
 That being said, :doc:`contributions are always welcome!
 </contributing>`.
-

docs/installing-open-mpi/sysadmins.rst

@@ -131,6 +131,9 @@ Open MPI installation, Open MPI will
 simply open the new plugin at run-time |mdash| your applications do not need
 to be recompiled or re-linked.
 
+:ref:`See this section <installing-custom-components-label>` for more
+details.
+
 Upgrading network hardware with a global Open MPI installation
 --------------------------------------------------------------
 
@@ -166,4 +169,3 @@ per-user basis in two important ways:
   experiment with new components without destabilizing Open MPI for the rest
   of the users on the system.  Or power users can download 3rd party components
   (perhaps even research-quality components) without affecting other users.
-