Update current state of PRRTE help docs

Continue to work on setting up entries for reuse. Add verbose
entries for more complex options. Triage the actual options
for prte and prterun.

Signed-off-by: Ralph Castain <rhc@pmix.org>

src/mca/schizo/base/Makefile.am

@@ -11,7 +11,8 @@
 
 dist_prtedata_DATA += \
     base/help-schizo-base.txt \
-    base/help-schizo-cli.txt
+    base/help-schizo-cli.txt \
+    base/help-schizo-deprecated.txt
 
 headers += \
         base/base.h

src/mca/schizo/base/help-schizo-cli.txt

@@ -21,6 +21,9 @@ Supported values include:
 
 -   ALLOCATION displays the detected hosts and slot assignments for this job
 
+-   ALLOC-DEVEL displays a more detailed report of the detected hosts
+    and slot assignments for this job
+
 -   BIND displays the resulting bindings applied to processes in this job
 
 -   MAP displays the resulting locations assigned to processes in this job
@@ -315,3 +318,135 @@ as defined in the environment using (in precedence order) the envars TMPDIR, TEM
 finally TMP. In the absence of any of those variables, PRRTE will default to the "/tmp"
 location.
 #
+#  PRTEMCA
+#
+[prtemca]
+Pass a PRRTE MCA parameter
+
+Syntax: --prtemca <arg0> <arg1>
+where arg0 is the parameter name and arg1 is the parameter value
+#
+#  PMIXMCA
+#
+[pmixmca]
+Pass a PMIx MCA parameter
+
+Syntax: --pmixmca <arg0> <arg1>
+where arg0 is the parameter name and arg1 is the parameter value
+#
+#  TUNE
+#
+[tune]
+Comma-delimited list of one or more files containing PRRTE and PMIx MCA params
+for tuning DVM and/or application operations. Parameters in the file will be
+treated as _generic_ parameters and subject to the translation rules/uncertainties.
+ See "--help mca" for more information.
+
+Syntax in the file is:
+
+param = value
+
+with one parameter and its associated value per line. Empty lines and lines beginning
+with the '#' character are ignored.
+#
+#  DEBUG-DAEMONS
+#
+[debug-daemons]
+Debug daemon output enabled. This is a somewhat limited stream of information normally
+used to simply confirm that the daemons started. Includes leaving the output streams
+open.
+#
+#  DEBUG-DAEMONS-FILE
+[debug-daemons-file]
+Debug daemon output is enabled and all output from the daemons is redirected into
+files named
+
+   output-prted-<daemon-nspace>-<nodename>.log
+
+to avoid conflict on shared file systems. The files are located in the top-level
+session directory assigned to the DVM.
+
+#include#help-schizo-cli#session-dir
+#
+#  LEAVE-SESSION-ATTACHED
+#
+[leave-session-attached]
+Do not discard stdout/stderr of remote PRRTE daemons. The primary use for this option
+is to ensure that the daemon output streams (i.e., stdout and stderr) remain open after
+launch, thus allowing the user to see any daemon-generated error messages. Otherwise,
+the daemon will "daemonize" itself upon launch, thereby closing its output streams.
+#
+#  PREFIX
+#
+[prefix]
+Prefix to be used to look for PRRTE executables. PRRTE automatically sets the prefix
+for remote daemons if it was either configured with the --enable-prte-prefix-by-default
+option OR prte itself was executed with an absolute path to the prte cmd. This option
+overrides those settings, if present, and forces use of the provided path.
+#
+#  NO-PREFIX
+#
+[noprefix]
+Disable automatic --prefix behavior. PRRTE automatically sets the prefix for remote
+daemons if it was either configured with the --enable-prte-prefix-by-default option
+OR prte itself was executed with an absolute path to the prte cmd. This option disables
+that behavior.
+#
+#  FORWARD-SIGNALS
+#
+[forward-signals]
+Comma-delimited list of additional signals (names or integers) to forward to application
+processes ["none" => forward nothing]. Signals provided by default include SIGTSTP,
+SIGUSR1, SIGUSR2, SIGABRT, SIGALRM, and SIGCONT
+#
+#  ALLOW-RUN-AS-ROOT
+#
+[allow-run-as-root]
+Allow execution as root (STRONGLY DISCOURAGED).
+
+Running as root exposes the user to potentially catastrophic file system corruption
+and damage - e.g., if the user accidentally points the root of the session directory
+to a system required point, this directory and all underlying elements will be
+deleted upon job completion, thereby rendering the system inoperable.
+
+It is recognized that some environments (e.g., containers) may require operation as
+root, and that the user accepts the risks in those scenarios. Accordingly, one can
+override PRRTE's run-as-root protection by providing one of the following:
+
+  * the "--allow-run-as-root" cmd line directive
+  * adding BOTH of the following environmental parameters
+    * PRTE_ALLOW_RUN_AS_ROOT=1
+    * PRTE_ALLOW_RUN_AS_ROOT_CONFIRM=1
+
+Again, we recommend this only be done if absolutely necessary.
+#
+#  X
+#
+[x]
+Export an environment variable, optionally specifying a value. For example:
+
+  * "-x foo" exports the environment variable foo and takes its value from the
+    current environment
+  * "-x foo=bar" exports the environment variable name foo and sets its value
+    to "bar" in the started processes
+  * "-x foo*" exports all current environmental variables starting with "foo"
+#
+#  STREAM-BUFFERING
+#
+[stream-buffering]
+Adjust buffering for stdout/stderr
+    [0 => unbuffered]
+    [1 => line buffered]
+    [2 => fully buffered]
+#
+#  PERSONALITY
+#
+[personality]
+Specify the personality to be used. This governs selection of the plugin
+responsible for defining and parsing the command line, harvesting and
+forwarding environmental variables, and providing library-dependent
+support to the launched processes. Examples include "ompi" for an
+application compiled with Open MPI, "mpich" for one built against
+the MPICH library, or "oshmem" for an OpenSHMEM application compiled
+against SUNY's reference library.
+#

src/mca/schizo/base/help-schizo-deprecated.txt

@@ -0,0 +1,157 @@
+# -*- text -*-
+#
+# Copyright (c) 2022 Nanook Consulting.  All rights reserved.
+# $COPYRIGHT$
+#
+# Additional copyrights may follow
+#
+# $HEADER$
+#
+#  MCA
+#
+Syntax: --mca <arg0> <arg1>
+where arg0 is the parameter name and arg1 is the parameter value
+
+Pass generic MCA parameters - i.e., parameters whose project affiliation
+must be determined by PRRTE based on matching the name of the parameter with defined values
+from various projects that PRRTE knows about.
+
+DEPRECATED: This translation can be incomplete (e.g., if a project adds or changes
+parameters) - thus, it is strongly recommended that users use project-specific parameters
+such as "prtemca" or "pmixmca".
+#
+#  GMCA
+#
+Syntax: --gmca <arg0> <arg1>
+where arg0 is the parameter name and arg1 is the parameter value. The "g" prefix
+indicates that this parameter is to be applied to _all_ application contexts and
+not just the one in which the directive appears.
+
+Pass generic MCA parameters - i.e., parameters whose project affiliation
+must be determined by PRRTE based on matching the name of the parameter with defined values
+from various projects that PRRTE knows about. This translation can be incomplete (e.g., if
+a known project adds or changes parameters) - thus, it is strongly recommended that users
+use project-specific parameters such as "prtemca" or "pmixmca".
+
+DEPRECATED: This translation can be incomplete (e.g., if  known project adds or changes
+parameters) - thus, it is strongly recommended that users use project-specific parameters
+such as "gprtemca" or "gpmixmca".
+#
+#  XML
+#
+[xml]
+Provide all output in XML format
+
+DEPRECATED: please use "--output"
+
+#include#help-schizo-cli#output
+#
+# TAG-OUTPUT
+#
+[tag-output]
+Tag all output with [job,rank]
+
+DEPRECATED: please use "--output tag"
+
+#include#help-schizo-cli#output
+#
+#  TIMESTAMP-OUTPUT
+#
+[timestamp-output]
+Timestamp all application process output
+
+DEPRECATED: please use "--output timestamp"
+
+#include#help-schizo-cli#output
+#
+#  OUTPUT-DIRECTORY
+#
+[output-directory]
+Redirect output from application processes into filename/job/rank/std[out,err,diag]. A
+relative path value will be converted to an absolute path. The directory name may include a
+colon followed by a comma-delimited list of optional case-insensitive directives. Supported
+directives currently include NOJOBID (do not include a job-id directory level) and NOCOPY
+(do not copy the output to the stdout/err streams)
+
+DEPRECATED: please use "--output dir=<path>"
+
+#include#help-schizo-cli#output
+#
+#  OUTPUT-FILENAME
+#
+[output-filename]
+Redirect output from application processes into filename.rank. A relative path value will be
+converted to an absolute path. The directory name may include a colon followed by a
+comma-delimited list of optional case-insensitive directives. Supported directives currently
+include NOCOPY (do not copy the output to the stdout/err streams)
+
+DEPRECATED: please use "--output file=<path>"
+
+#include#help-schizo-cli#output
+#
+#  MERGE-STDERR-TO-STDOUT
+#
+[merge-stderr-to-stdout]
+Merge stderr to stdout for each process
+
+DEPRECATED: please "--output merge"
+
+#include#help-schizo-cli#output
+#
+#  DISPLAY-DEVEL-MAP
+#
+[display-devel-map]
+Display a detailed process map (mostly intended for developers)
+just before launch
+
+DEPRECATED: please use "--display map-devel"
+
+#include#help-schizo-cli#display
+#
+#  DISPLAY-TOPO
+#
+[display-topo]
+Display the topology as part of the process map (mostly intended
+for developers) just before launch
+
+DEPRECATED: please use "--display topo"
+
+#include#help-schizo-cli#display
+#
+#  REPORT-BINDINGS
+#
+[report-bindings]
+Display process bindings to stderr
+
+DEPRECATED: please use "--display bindings"
+
+#include#help-schizo-cli#display
+#
+#  DISPLAY-DEVEL-ALLOCATION
+#
+[display-devel-allocation]
+Display a detailed list (mostly intended for developers) of the
+allocation being used by this job
+
+DEPRECATED: please use "--display alloc-devel"
+
+#include#help-schizo-cli#display
+#
+#  DISPLAY-MAP
+#
+[display-map]
+Display the process map just before launch
+
+DEPRECATED: please use "--display map"
+
+#include#help-schizo-cli#display
+#
+#  DISPLAY-ALLOCATION
+#
+[display-allocation]
+Display the allocation being used by this job
+
+DEPRECATED: please use "--display alloc"
+
+#include#help-schizo-cli#display
+#