Merge pull request #12058 from jsquyres/pr/still-moar-docs-updates

A bunch of docs updates

Author: jsquyres

docs/building-apps/abi-compatibility.rst

@@ -8,7 +8,7 @@ compatibility for the C MPI bindings to the last major Open MPI release. Specifi
 application compiled with Open MPI v4.x can be executed with Open MPI
 |ompi_series| without having to recompile the application.
 
-.. important:: ABI is maintained for *most* of the Fortran MPI bindings, too -- see below for additional information.
+.. important:: ABI is maintained for *most* of the Fortran MPI bindings, too |mdash| see below for additional information.
 
 There are however a few scenarios where an application compiled with
 Open MPI v4.x might not execute correctly with Open MPI 5.0.

docs/developers/prerequisites.rst

@@ -96,8 +96,8 @@ generate both the HTML version of the documentation (that you are
 reading right now) and the nroff man pages.
 
 Official Open MPI distribution tarballs contain pre-built HTML
-documentation and man pages.  This means that -- similar to the GNU
-Autotools -- end users do not need to have Sphinx installed, but will
+documentation and man pages.  This means that |mdash| similar to the GNU
+Autotools |mdash| end users do not need to have Sphinx installed, but will
 still have both the HTML documentation and man pages installed as part
 of the normal configure / build / install process.
 

docs/developers/rst-for-markdown-expats.rst

@@ -228,7 +228,7 @@ Comments
         will not be included in the rendered output.
 
         Your comment can even include blank lines.  You terminate a
-        comment -- just like most other things in RST -- by a blank
+        comment |mdash| just like most other things in RST |mdash| by a blank
         line and then outdenting back out to the same column as the
         first ".".
 

docs/developers/source-code.rst

@@ -54,7 +54,7 @@ C / C++
   * C99-style mixing declarations are allow allowable (and preferred).
 
 * **ALWAYS** include ``<level>_config.h`` as your first #include file,
-  where ``<level>`` is one of ``ompi``, ``oshmem``, or ``opal`` -- the
+  where ``<level>`` is one of ``ompi``, ``oshmem``, or ``opal`` |mdash| the
   level that you're writing in.  There are very, very few cases where
   this is not true (E.g., some bizarre Windows scenarios).  But in
   99.9999% of cases, this file should be included **first** so that it
@@ -77,7 +77,7 @@ C / C++
   * The GNU Way is to ``#define`` a macro when it is "true" and to
     ``#undef`` it when it is "false".
   * In Open MPI, we **always** ``#define`` a logical macro to be
-    either 0 or 1 -- we never ``#undef`` it.
+    either 0 or 1 |mdash| we never ``#undef`` it.
   * The reason for this is defensive programming: if you are only
     checking if a preprocessor macro is defined (via ``#ifdef FOO`` or
     ``#if defined(FOO)``), you will get no warning when compiling if

docs/features/java.rst

@@ -6,7 +6,7 @@ Open MPI Java bindings
 Open MPI |ompi_ver| provides support for Java-based MPI applications.
 
 .. warning:: The Open MPI Java bindings are provided on a
-   "provisional" basis -- i.e., they are not part of the current or
+   "provisional" basis |mdash| i.e., they are not part of the current or
    proposed MPI standards.  Thus, inclusion of Java support is not
    required by the standard.  Continued inclusion of the Java bindings
    is contingent upon active user interest and continued developer

docs/features/ulfm.rst

@@ -573,7 +573,7 @@ sign up on the user's mailing list: ulfm+subscribe@googlegroups.com
 
 Because of spam, only subscribers are allowed to post to these lists
 (ensure that you subscribe with and post from exactly the same e-mail
-address -- joe@example.com is considered different than
+address |mdash| joe@example.com is considered different than
 joe@mycomputer.example.com!).  Visit these pages to subscribe to the
 lists: https://groups.google.com/forum/#!forum/ulfm
 

docs/history.rst

@@ -20,13 +20,13 @@ MPI implementation focused on different areas of excellence, we all
 shared the same common core values:
 
 * A full MPI implementation
-* Production quality code -- it has to "just work"
+* Production quality code |mdash| it has to "just work"
 * A desire to explore lots of things that an MPI implementation can do
   that we've never had the time/resources to investigate because we
   are bound to bug fixing, etc.
 
 Hence, we decided to collaborate and pool our resources.  At SC2003,
-we decided to start an entire new code base -- leaving all the cruft
+we decided to start an entire new code base |mdash| leaving all the cruft
 and legacy code of our prior implementations behind.  Take the best,
 leave the rest.  The source tree's first commit was on November 22,
 2003; development work started in earnest on January 5, 2004.  Since

docs/installing-open-mpi/configure-cli-options/installation.rst

@@ -238,7 +238,7 @@ be used with ``configure``:
   Some examples:
 
   #. Default to building all components as static (i.e., as part of
-     the Open MPI core libraries -- no DSOs)::
+     the Open MPI core libraries |mdash| no DSOs)::
 
         shell$ ./configure
 
@@ -304,7 +304,7 @@ be used with ``configure``:
   their Open MPI package, both of which require support libraries
   (``libFOO.so`` and ``libBAR.so``).  If an end user only has BAR
   hardware, they likely only have ``libBAR.so`` available on their
-  systems -- not ``libFOO.so``.  Disabling load errors by default will
+  systems |mdash| not ``libFOO.so``.  Disabling load errors by default will
   prevent the user from seeing potentially confusing warnings about
   the FOO components failing to load because ``libFOO.so`` is not
   available on their systems.

docs/installing-open-mpi/configure-cli-options/misc.rst

@@ -29,7 +29,7 @@ above categories that can be used with ``configure``:
   with different endian representations).  Heterogeneous support is
   disabled by default because it imposes a minor performance penalty.
 
-  .. danger:: The heterogeneous functionality is currently broken --
+  .. danger:: The heterogeneous functionality is currently broken |mdash|
               do not use.
 
 .. _install-wrapper-flags-label:
@@ -40,7 +40,7 @@ above categories that can be used with ``configure``:
 * ``--with-wrapper-ldflags=LDFLAGS``
 * ``--with-wrapper-libs=LIBS``:
   Add the specified flags to the default flags that are used in Open
-  MPI's "wrapper" compilers (e.g., ``mpicc`` -- see below for more
+  MPI's "wrapper" compilers (e.g., ``mpicc`` |mdash| see below for more
   information about Open MPI's wrapper compilers).  By default, Open
   MPI's wrapper compilers use the same compilers used to build Open
   MPI and specify a minimum set of additional flags that are necessary

docs/installing-open-mpi/configure-cli-options/runtime.rst

@@ -13,7 +13,7 @@ can be used with ``configure``:
   prevents most ``rsh``/``ssh``-based users from needing to modify their
   shell startup files to set the ``PATH`` and/or ``LD_LIBRARY_PATH`` for
   Open MPI on remote nodes.  Note, however, that such users may still
-  desire to set ``PATH`` -- perhaps even in their shell startup files --
+  desire to set ``PATH`` |mdash| perhaps even in their shell startup files |mdash|
   so that executables such as ``mpicc`` and ``mpirun`` can be found
   without needing to type long path names.