Retire the FAQ section of the docs, moving its content to other locations

docs/Makefile.am

@@ -44,7 +44,6 @@ RST_SOURCE_FILES   = \
         $(srcdir)/tuning-apps/*.rst \
         $(srcdir)/tuning-apps/*/*.rst \
         $(srcdir)/app-debug/*.rst \
-        $(srcdir)/faq/*.rst \
         $(srcdir)/developers/*.rst \
         $(srcdir)/license/*.rst \
         $(srcdir)/news/*.rst \

docs/app-debug/index.rst

@@ -23,6 +23,7 @@ that can aid debugging.
    debug-tools
    debug-options
    serial-debug
+   parallel-debug
    lost-output
    memchecker
    valgrind

docs/app-debug/mpir-tools.rst

@@ -1,3 +1,5 @@
+.. _using-mpir-based-tools-label:
+
 Using MPIR-based tools with Open MPI
 ====================================
 
@@ -11,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

@@ -0,0 +1,41 @@
+Using Parallel Debuggers to Debug Open MPI Applications
+=======================================================
+
+Debugging 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.
+
+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:
+
+   * The message queues view will be truncated.
+   * Both the communicators and requests lists will be incomplete.
+   * Both the communicators and requests lists may be filled with wrong
+     values (such as an ``MPI_Send`` to the destination
+     ``MPI_ANY_SOURCE``).
+
+   There are two workarounds:
+
+   * Use a 32-bit version of TotalView
+   * Upgrade to TotalView v8.3 or later
+
+Debugging 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,3 +13,13 @@ Open MPI "wrapper" compilers.
    removed-mpi-constructs
    deprecation-warnings
    building-static-apps
+
+.. 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.