Capture Kathryn's changes and update revisions

Move the revisions chapter to an appendix per Kathryn's suggestion and
include all the "added" constants and attributes in it.

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

Chap_API_Event.tex

@@ -55,6 +55,16 @@ \section{Notification and Management}
 
 Upon completing its work and prior to returning, each handler \textit{must} call the event handler completion function provided when it was invoked (including a status code plus any information to be passed to later handlers) so that the chain can continue being progressed. \ac{PMIx} automatically aggregates the status and any results of each handler (as provided in the completion callback) with status from all prior handlers so that each step in the chain has full knowledge of what preceded it. An event handler can terminate all further progress along the chain by passing the \refconst{PMIX_EVENT_ACTION_COMPLETE} status to the completion callback function.
 
+\subsection{Events versus status constants}
+\label{api:event:evssc}
+
+Return status constants (see Section \ref{api:struct:errors}) represent values that can be returned from or passed into \ac{PMIx}
+\acp{API}. These are distinct from \ac{PMIx} \emph{events} in that they are
+not values that can be registered against event handlers. In general, the two
+types of constants are distinguished by inclusion of an "ERR" in the name of
+error constants versus an "EVENT" in events, though there are exceptions (e.g,
+the \refconst{PMIX_SUCCESS} constant).
+
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{\code{PMIx_Register_event_handler}}

Chap_API_Init.tex

@@ -4,13 +4,13 @@
 \chapter{Client Initialization and Finalization}
 \label{chap:api_init}
 
-The \ac{PMIx} library is required to be initialized and finalized around the usage of most of the \acp{API}.
+The \ac{PMIx} library is required to be initialized and finalized around the usage of most \ac{PMIx} functions or macros.
 The \acp{API} that may be used outside of the initialized and finalized region are noted.
 All other \acp{API} must be used inside this region.
 
-There are three sets of initialization and finalization functions depending upon the role of the process in the \ac{PMIx} Standard - those associated with the \ac{PMIx} \emph{client} are defined in this chapter. \ac{PMIx} clients are processes that have been assigned to a particular \ac{PMIx} server at time of start, with the information required to connect to that server being provided to them.
+There are three sets of initialization and finalization functions depending upon the role of the process in the \ac{PMIx} Standard - those associated with the \ac{PMIx} \refterm{client} are defined in this chapter. Similar functions corresponding to the roles of \emph{server} and \emph{tool} are defined in Chapters \ref{chap:api_server} and \ref{chap:api_tools}, respectively.
 
-Note that a process can only call \textit{one} of the init/finalize functional pairs - e.g., a process that calls the client initialization function cannot also call the tool or server initialization functions, and must call the corresponding client finalize. Regardless of the role assumed by the process, all processes have access to the client \acp{API}. Thus, the \emph{server} and \emph{tool} roles can be considered supersets of the \ac{PMIx} client.
+Note that a process can only call \textit{one} of the initialization/finalization functional pairs from the set of three - e.g., a process that calls the client initialization function cannot also call the tool or server initialization functions, and must call the corresponding client finalization function. Regardless of the role assumed by the process, all processes have access to the client \acp{API}. Thus, the \emph{server} and \emph{tool} roles can be considered supersets of the \ac{PMIx} client.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -311,8 +311,8 @@ \subsection{Finalize attributes}
 %
 \declareAttribute{PMIX_EMBED_BARRIER}{"pmix.embed.barrier"}{bool}{
 Execute a blocking fence operation before executing the specified operation.
-For example, \refapi{PMIx_Finalize} does not include an internal barrier operation by default.
-This attribute would direct \refapi{PMIx_Finalize} to execute a barrier as part of the finalize operation.
+\refapi{PMIx_Finalize} does not include an internal barrier operation by default.
+This attribute directs \refapi{PMIx_Finalize} to execute a barrier as part of the finalize operation.
 }
 
 

Chap_API_Job_Mgmt.tex

@@ -395,7 +395,7 @@ \subsection{\code{PMIx_Job_control}}
 \descr
 
 Request a job control action.
-The \refarg{targets} array identifies the processes to which the requested job control action is to be applied.
+The \refarg{targets} array identifies the processes to which the requested job control action is to be applied. All \refterm{clones} of an identified process are to have the requested action applied to them.
 A \code{NULL} value can be used to indicate all processes in the caller's namespace.
 The use of \refconst{PMIX_RANK_WILDCARD} can also be used to indicate that all processes in the given namespace are to be included.
 
@@ -481,7 +481,7 @@ \subsection{\code{PMIx_Job_control_nb}}
 \descr
 
 Non-blocking form of the \refapi{PMIx_Job_control} \ac{API}.
-The \refarg{targets} array identifies the processes to which the requested job control action is to be applied.
+The \refarg{targets} array identifies the processes to which the requested job control action is to be applied. All \refterm{clones} of an identified process are to have the requested action applied to them.
 A \code{NULL} value can be used to indicate all processes in the caller's namespace.
 The use of \refconst{PMIX_RANK_WILDCARD} can also be used to indicate that all processes in the given namespace are to be included.
 

Chap_API_Proc_Mgmt.tex

@@ -488,7 +488,7 @@ \subsection{Spawn attributes}
 event whenever a process either normally or abnormally terminates.
 }
 %
-\declareAttributeNEW{PMIX_NOTIFY_PROC_ABNORMAL TERMINATION}{"pmix.noteabproc"}{bool}{
+\declareAttributeNEW{PMIX_NOTIFY_PROC_ABNORMAL_TERMINATION}{"pmix.noteabproc"}{bool}{
 Requests that the launcher generate the \refconst{PMIX_EVENT_PROC_TERMINATED}
 event only when a process abnormally terminates.
 }
@@ -498,7 +498,7 @@ \subsection{Spawn attributes}
 whenever a process either normally or abnormally terminates.
 }
 %
-\declareAttributeNEW{PMIX_LOG_PROC_ABNORMAL TERMINATION}{"pmix.logabproc"}{bool}{
+\declareAttributeNEW{PMIX_LOG_PROC_ABNORMAL_TERMINATION}{"pmix.logabproc"}{bool}{
 Requests that the launcher log the \refconst{PMIX_EVENT_PROC_TERMINATED} event
 only when a process abnormally terminates.
 }
@@ -782,6 +782,11 @@ \subsection{\code{PMIx_Connect}}
 \reqattrend
 
 \optattrstart
+The following attributes are optional for \ac{PMIx} implementations:
+
+\pasteAttributeItem{PMIX_ALL_CLONES_PARTICIPATE}
+
+
 The following attributes are optional for host environments that support this operation:
 
 \pasteAttributeItem{PMIX_TIMEOUT}
@@ -857,6 +862,11 @@ \subsection{\code{PMIx_Connect_nb}}
 \reqattrend
 
 \optattrstart
+The following attributes are optional for \ac{PMIx} implementations:
+
+\pasteAttributeItem{PMIX_ALL_CLONES_PARTICIPATE}
+
+
 The following attributes are optional for host environments that support this operation:
 
 \pasteAttributeItem{PMIX_TIMEOUT}
@@ -912,6 +922,11 @@ \subsection{\code{PMIx_Disconnect}}
 \reqattrend
 
 \optattrstart
+The following attributes are optional for \ac{PMIx} implementations:
+
+\pasteAttributeItem{PMIX_ALL_CLONES_PARTICIPATE}
+
+
 The following attributes are optional for host environments that support this operation:
 
 \pasteAttributeItem{PMIX_TIMEOUT}
@@ -987,6 +1002,11 @@ \subsection{\code{PMIx_Disconnect_nb}}
 \reqattrend
 
 \optattrstart
+The following attributes are optional for \ac{PMIx} implementations:
+
+\pasteAttributeItem{PMIX_ALL_CLONES_PARTICIPATE}
+
+
 The following attributes are optional for host environments that support this operation:
 
 \pasteAttributeItem{PMIX_TIMEOUT}

Chap_API_Reserved_Keys.tex

@@ -24,18 +24,18 @@ \chapter{Reserved Keys}
 \section{Data realms}
 \label{api:struct:attributes:retrieval}
 
-\ac{PMIx} information spans a wide range of topics and sources. In some cases,
+\ac{PMIx} information spans a wide range of sources. In some cases,
 there are multiple overlapping sources for the same type of data - e.g., the
 session, job, and application can each provide information on the number of
 nodes involved in their respective area. In order to resolve the ambiguity,
-\ac{PMIx} introduced the concept of a \declaretermAlt{data realm}{realm,realms,data realm,data realms}
-that identifies the scope to which the referenced data applies. Thus, reference
+a \declaretermAlt{data realm}{realm,realms,data realm,data realms}
+is used to identify the scope to which the referenced data applies. Thus, a reference
 to an attribute that isn't specific to a realm (e.g., the
 \refattr{PMIX_NUM_NODES} attribute) must be accompanied by a corresponding
 attribute identifying the realm to which the request pertains if it differs
 from the default.
 
-\ac{PMIx} has defined five \emph{data realms} to resolve the ambiguities, as
+\ac{PMIx} defines five \emph{data realms} to resolve the ambiguities, as
 captured in the following attributes used in \refapi{PMIx_Get} for retrieving
 information from each of the realms:
 
@@ -55,9 +55,7 @@ \section{Data realms}
 containing the target application. If information about an application other
 than the one containing the target process is desired, then the attribute array
 must contain a \refattr{PMIX_APPNUM} attribute identifying the desired target
-application - this is useful when the requesting process knows there are
-multiple applications, but doesn't know which processes belong to which
-application.
+application. This is useful in cases where there are multiple applications and the mapping of processes to applications is unclear.
 }
 %
 \declareAttribute{PMIX_PROC_INFO}{"pmix.proc.info"}{bool}{
@@ -71,7 +69,7 @@ \section{Data realms}
 Return information from the node realm regarding the node upon which the specified process is executing. If information about
 a node other than the one containing the specified process is desired, then
 the attribute array must also contain either the \refattr{PMIX_NODEID} or
-\refattr{PMIX_HOSTNAME} attribute identifying the desired target - this is useful when the requesting process wants to know something about a specific node, but isn't sure what processes might be executing upon it.
+\refattr{PMIX_HOSTNAME} attribute identifying the desired target. This is useful for requesting information about a specific node even if the identity of processes running on that node are not known..
 }
 
 \adviceuserstart
@@ -341,7 +339,7 @@ \subsection{Process realm attributes}
 }
 %
 \declareAttributeNEW{PMIX_PACKAGE_RANK}{"pmix.pkgrank"}{uint16_t}{
-Rank of the specified process on the package where this process resides - refers to the numerical location (starting from zero) of the process on its package when counting only those processes from the same job that share the package, ordered by their overall rank within that job. Note that processes that are not bound to \acp{PU} within a single specific package cannot have a package rank.
+Rank of the specified process on the \refterm{package} where this process resides - refers to the numerical location (starting from zero) of the process on its package when counting only those processes from the same job that share the package, ordered by their overall rank within that job. Note that processes that are not bound to \acp{PU} within a single specific package cannot have a package rank.
 }
 %
 \declareAttribute{PMIX_PROC_PID}{"pmix.ppid"}{pid_t}{