xsmp.xml: Use <synopsis> and related markup for protocol message definition

Signed-off-by: Alan Coopersmith <alan.coopersmith@oracle.com>

1 files changed, 146 insertions, 95 deletions

diff --git a/doc/xsmp.xml b/doc/xsmp.xml
index 1677cda..ee4bc14 100644
--- a/doc/xsmp.xml
+++ b/doc/xsmp.xml
@@ -411,44 +411,53 @@ set of valid responses and possible error messages are listed.  The
 <acronym>ICE</acronym> severity is given in parentheses following each error class.
   </para>
 
-  <para><function>RegisterClient</function> [Client &rarr; SM]</para>
+  <synopsis>
+<function>RegisterClient</function> [Client &rarr; SM]
 
-  <para><emphasis remap='I'>previous-ID</emphasis>: ARRAY8</para>
+  <parameter>previous-ID</parameter>: ARRAY8
 
-  <para>Valid Responses: <function>RegisterClientReply</function></para>
+  Valid Responses: <function>RegisterClientReply</function>
 
-  <para>Possible Errors: <errorname>BadValue</errorname> (<symbol role='Pn'>CanContinue</symbol>)</para>
+  Possible Errors: <errorname>BadValue</errorname> (<symbol role='Pn'>CanContinue</symbol>)
+  </synopsis>
 
   <para>
 The client must send this message to the SM to register the client's
 existence.  If a client is being restarted from a previous session,
-the previous-ID field must contain the client ID from the previous
-session.  For new clients, previous-ID should be of zero length.
+the <parameter>previous-ID</parameter> field must contain the client
+ID from the previous session.  For new clients, 
+<parameter>previous-ID</parameter> should be of zero length.
   </para>
 
   <para>
-If previous-ID is not valid, the SM will send a <errorname>BadValue</errorname>
+If <parameter>previous-ID</parameter> is not valid, 
+the SM will send a <errorname>BadValue</errorname>
 error message to the client.  At this point the SM reverts to the
 register state and waits for another <function>RegisterClient</function>
 The client should then send a <function>RegisterClient</function> with a
-null previous-ID field.
+null <parameter>previous-ID</parameter> field.
   </para>
 
-  <para><function>RegisterClientReply</function> [Client &larr; SM]</para>
+  <synopsis>
+<function>RegisterClientReply</function> [Client &larr; SM]
 
-  <para><emphasis remap='I'>client-ID</emphasis>: ARRAY8</para>
+  <parameter>client-ID</parameter>: <type>ARRAY8</type>
+  </synopsis>
 
   <para>
-The client-ID specifies a unique identification for this client.  If
-the client had specified an ID in the previous-ID field of
-the <function>RegisterClient</function> message, client-ID will be
-identical to the previously specified ID.  If previous-ID was null,
-client-ID will be a unique ID freshly generated by the SM.  The
-client-ID format is specified in section 6.
+The <parameter>client-ID</parameter> specifies a unique identification
+for this client.  If the client had specified an ID in the 
+<parameter>previous-ID</parameter> field of the 
+<function>RegisterClient</function> message, 
+<parameter>client-ID</parameter> will be identical to the previously
+specified ID.  If <parameter>previous-ID</parameter> was null,
+<parameter>client-ID</parameter> will be a unique ID freshly generated
+by the SM.  The <parameter>client-ID</parameter> format is specified in
+section 6.
   </para>
 
   <para>
-If the client didn't supply a previous-ID field to
+If the client didn't supply a <parameter>previous-ID</parameter> field to
 the <function>Register&shy;Client</function> message, the SM must send
 a <function>SaveYourself</function> message with type = Local,
 shutdown = False, interact-style = None, and fast = False immediately
@@ -457,27 +466,30 @@ respond to this like any other <function>Save&shy;Yourself</function>
 message.
   </para>
 
-  <para><function>SaveYourself</function> [Client &larr; SM]</para>
+  <synopsis>
+<function>SaveYourself</function> [Client &larr; SM]
 
-  <para><emphasis remap='I'>type</emphasis>: SAVE_TYPE</para>
-  <para><emphasis remap='I'>shutdown</emphasis>: BOOL</para>
-  <para><emphasis remap='I'>interact-style</emphasis>: INTERACT_STYLE</para>
-  <para><emphasis remap='I'>fast</emphasis>: BOOL</para>
+  <parameter>type</parameter>: <type>SAVE_TYPE</type>
+  <parameter>shutdown</parameter>: <type>BOOL</type>
+  <parameter>interact-style</parameter>: <type>INTERACT_STYLE</type>
+  <parameter>fast</parameter>: <type>BOOL</type>
 
-  <para>Valid Responses:
+  Valid Responses:
     <function>SetProperties</function>
     <function>DeleteProperties</function>
     <function>GetProperties</function>
     <function>SaveYourselfDone</function>
     <function>SaveYourselfPhase2Request</function>
-    <function>InteractRequest</function></para>
+    <function>InteractRequest</function>
+  </synopsis>
 
   <para>
 The SM sends this message to a client to ask it to save its state.
 The client writes a state file, if necessary, and, if necessary,
 uses <function>SetProperties</function> to inform the SM of how to
 restart it and how to discard the saved state.  During this process it
-can, if allowed by interact-style, request permission to interact with
+can, if allowed by <parameter>interact-style</parameter>, request permission
+to interact with
 the user by sending an <function>InteractRequest</function> message.
 After the state has been saved, or if it cannot be successfully saved,
 and the properties are appropriately set, the client sends
@@ -492,10 +504,11 @@ a <function>ShutdownCancelled</function> message.
   </para>
 
   <para>
-If interact-style is <function>None</function> the client must not
-interact with the user while saving state.  If the interact-style
+If <parameter>interact-style</parameter> is <function>None</function> the
+client must not interact with the user while saving state.  If the
+<parameter>interact-style</parameter>
 is <function>Errors</function> the client may interact with the user
-only if an error condition arises.  If interact-style
+only if an error condition arises.  If <parameter>interact-style</parameter>
 is <function>Any</function> then the client may interact with the user
 for any purpose.  This is done by sending
 an <function>Interact&shy;Request</function> message.  The SM will
@@ -526,8 +539,8 @@ responding as appropriate to the newly received
 </para>
 
   <para>
-The type field specifies the type of information that should be
-saved: <function>Global</function> <function>Local</function>
+The <parameter>type</parameter> field specifies the type of information that
+should be saved: <function>Global</function> <function>Local</function>
 or <function>Both</function> The <function>Local</function> type
 indicates that the application must update the properties to reflect
 its current state, send
@@ -573,13 +586,16 @@ to remove it.
     </para>
 
     <para>
-Once the SM has send <function>SaveYourself</function> to a client, it can't send another <function>SaveYourself</function> to that client until the client either responds with a <function>SaveYourselfDone</function> or the SM sends a <function>ShutdownCancelled</function>
+Once the SM has send <function>SaveYourself</function> to a client, it
+can't send another <function>SaveYourself</function> to that client until
+the client either responds with a <function>SaveYourselfDone</function> or
+the SM sends a <function>ShutdownCancelled</function>
     </para>
   </note>
 
   <note><title>Advice to Implementors</title>
     <para>
-If the client stores local any state in a file or similar "Qexternal"
+If the client stores local any state in a file or similar "external"
 storage, it must create a distinct copy in response to
 each <function>SaveYourself</function> message.
 It <emphasis remap='I'>must not</emphasis> simply refer to a previous
@@ -590,7 +606,8 @@ needed for the new checkpoint.
   </note>
 
   <para>
-The shutdown field specifies whether the system is being shut down.
+The <parameter>shutdown</parameter> field specifies whether the system is
+being shut down.
   </para>
 
   <note><title>Rationale</title>
@@ -607,19 +624,22 @@ user does after the save will be lost.
   </para>
 
   <para>
-The fast field specifies whether or not the client should save its
-state as quickly as possible.  For example, if the SM knows that power
-is about to fail, it should set the fast field to <constant>True</constant>
+The <parameter>fast</parameter> field specifies whether or not the client
+should save its state as quickly as possible.  For example, if the SM knows
+that power is about to fail, it should set the <parameter>fast</parameter>
+field to <constant>True</constant>.
   </para>
 
-  <para><function>SaveYourselfPhase2</function> [Client &rarr; SM]</para>
+  <synopsis>
+<function>SaveYourselfPhase2</function> [Client &rarr; SM]
 
-  <para>Valid Responses:
+  Valid Responses:
     <function>SetProperties</function>
     <function>DeleteProperties</function>
     <function>GetProperties</function>
     <function>SaveYourselfDone</function>
-    <function>InteractRequest</function></para>
+    <function>InteractRequest</function>
+  </synopsis>
 
   <para>
 The SM sends this message to a client that has previously sent
@@ -648,15 +668,17 @@ and the properties are appropriately set, the client sends
 a <function>SaveYourselfDone</function> message.
   </para>
 
-  <para><function>SaveYourselfRequest</function> [Client &rarr; SM]</para>
+  <synopsis>
+<function>SaveYourselfRequest</function> [Client &rarr; SM]
 
-  <para><emphasis remap='I'>type</emphasis>: SAVE_TYPE</para>
-  <para><emphasis remap='I'>shutdown</emphasis>: BOOL</para>
-  <para><emphasis remap='I'>interact-style</emphasis>: INTERACT_STYLE</para>
-  <para><emphasis remap='I'>fast</emphasis>: BOOL</para>
-  <para><emphasis remap='I'>global</emphasis>: BOOL</para>
+  <parameter>type</parameter>: <type>SAVE_TYPE</type>
+  <parameter>shutdown</parameter>: <type>BOOL</type>
+  <parameter>interact-style</parameter>: <type>INTERACT_STYLE</type>
+  <parameter>fast</parameter>: <type>BOOL</type>
+  <parameter>global</parameter>: <type>BOOL</type>
 
-  <para>Valid Responses: <function>SaveYourself</function></para>
+  Valid Responses: <function>SaveYourself</function>
+  </synopsis>
 
   <para>
 An application sends this to the SM to request a checkpoint.  When the
@@ -672,20 +694,23 @@ is about to be lost.
   </para></note>
 
   <para>
-If global is set to <constant>True</constant> then the
+If <parameter>global</parameter> is set to <constant>True</constant> then the
 resulting <function>SaveYourself</function> should be sent to all
-applications.  If global is set to <constant>False</constant> then the
+applications.  If <parameter>global</parameter> is set to
+<constant>False</constant> then the
 resulting <function>SaveYourself</function> should be sent to the
 application that sent the <function>Save&shy;Yourself&shy;Request</function>
   </para>
 
-  <para><function>InteractRequest</function> [Client &rarr; SM]</para>
+  <synopsis>
+<function>InteractRequest</function> [Client &rarr; SM]
 
-  <para><emphasis remap='I'>dialog-type</emphasis>: DIALOG_TYPE</para>
+  <parameter>dialog-type</parameter>: <type>DIALOG_TYPE</type>
 
-  <para>Valid Responses: <function>Interact</function> <function>ShutdownCancelled</function></para>
+  Valid Responses: <function>Interact</function> <function>ShutdownCancelled</function>
 
-  <para>Possible Errors: <errorname>BadState</errorname> (<symbol role='Pn'>CanContinue</symbol>)</para>
+  Possible Errors: <errorname>BadState</errorname> (<symbol role='Pn'>CanContinue</symbol>)
+  </synopsis>
 
   <para>
 During a checkpoint or session-save operation, only one client at a
@@ -696,15 +721,17 @@ shutdown is not cancelled by another client first.
   </para>
 
   <para>
-The dialog-type field specifies either <function>Errors</function>
-indicating that the client wants to start an error dialog
-or <function>Normal</function> meaning the client wishes to start a
-non-error dialog.
+The <parameter>dialog-type</parameter> field specifies either
+<function>Errors</function> indicating that the client wants to start an
+error dialog or <function>Normal</function> meaning the client wishes
+to start a non-error dialog.
   </para>
 
-  <para><function>Interact</function> [Client &larr; SM]</para>
+  <synopsis>
+<function>Interact</function> [Client &larr; SM]
 
-  <para>Valid Responses: <function>InteractDone</function></para>
+  Valid Responses: <function>InteractDone</function>
+  </synopsis>
 
   <para>
 This message grants the client the privilege of interacting with the
@@ -719,36 +746,40 @@ sending a <function>InteractDone</function> the client should abort
 the interaction and send a <function>SaveYourselfDone</function>
   </para></note>
 
-  <para><function>InteractDone</function> [Client &rarr; SM]</para>
+  <synopsis>
+<function>InteractDone</function> [Client &rarr; SM]
 
-  <para><emphasis remap='I'>cancel-shutdown</emphasis>: BOOL</para>
+  <parameter>cancel-shutdown</parameter>: <type>BOOL</type>
 
-  <para>Valid Responses: <function>ShutdownCancelled</function></para>
+  Valid Responses: <function>ShutdownCancelled</function>
+  </synopsis>
 
   <para>
 This message is used by a client to notify the SM that it is done interacting.
   </para>
 
   <para>
-Setting the cancel-shutdown field to <constant>True</constant>
+Setting the <parameter>cancel-shutdown</parameter> field to <constant>True</constant>
 indicates that the user has requested that the entire shutdown be
-cancelled.  Cancel-shutdown may only be <constant>True</constant> if
+cancelled.  <parameter>Cancel-shutdown</parameter> may only be <constant>True</constant> if
 the corresponding <function>SaveYourself</function> message
 specified <constant>True</constant> for the shutdown field
 and <function>Any</function> or <function>Errors</function> for the
-interact-style field.  Otherwise, cancel-shutdown must
-be <constant>False</constant>
+<parameter>interact-style</parameter> field.  Otherwise,
+<parameter>cancel-shutdown</parameter> must be <constant>False</constant>.
   </para>
 
-  <para><function>SaveYourselfDone</function> [Client &rarr; SM]</para>
+  <synopsis>
+<function>SaveYourselfDone</function> [Client &rarr; SM]
 
-  <para><emphasis remap='I'>success</emphasis>: BOOL</para>
+  <parameter>success</parameter>: <type>BOOL</type>
 
-  <para>Valid Responses:
+  Valid Responses:
     <function>SaveComplete</function>
     <function>Die</function>
     <function>ShutdownCancelled</function>
-  </para>
+  
+  </synopsis>
 
   <para>
 This message is sent by a client to indicate that all of the
@@ -757,33 +788,38 @@ sending <function>SaveYourselfDone</function> the client must wait for
 a <function>SaveComplete</function> <function>ShutdownCancelled</function>
 or <function>Die</function> message before changing its state.  If
 the <function>SaveYourself</function> operation was successful, then
-the client should set the success field to <constant>True</constant>
-otherwise the client should set it to <constant>False</constant>
+the client should set the <parameter>success</parameter> field to
+<constant>True</constant> otherwise the client should set it to
+<constant>False</constant>.
   </para>
 
   <note><title>Example</title>
     <para>
 If a client tries to save its state and runs out of disk space, it
-should return <constant>False</constant> in the success field of
-the <function>SaveYourselfDone</function> message.
+should return <constant>False</constant> in the <parameter>success</parameter>
+field of the <function>SaveYourselfDone</function> message.
     </para>
   </note>
 
-  <para><function>SaveYourselfPhase2Request</function> [Client &rarr; SM]</para>
+  <synopsis>
+<function>SaveYourselfPhase2Request</function> [Client &rarr; SM]
 
-  <para>Valid Responses:
+  Valid Responses:
     <function>ShutdownCancelled</function>
     <function>SaveYourselfPhase2</function>
-  </para>
+  
+  </synopsis>
 
   <para>
 This message is sent by a client to indicate that it needs to be informed
 when all the other clients are quiescent, so it can continue its state.
   </para>
 
-  <para><function>Die</function> [Client &larr; SM]</para>
+  <synopsis>
+<function>Die</function> [Client &larr; SM]
 
-  <para>Valid Responses: <function>ConnectionClosed</function></para>
+  Valid Responses: <function>ConnectionClosed</function>
+  </synopsis>
 
   <para>
 When the SM wants a client to die it sends a <function>Die</function>
@@ -792,9 +828,11 @@ a <function>ConnectionClosed</function> message and may then close its
 connection to the SM at any time.
   </para>
 
-  <para><function>SaveComplete</function> [Client &rarr; SM]</para>
+  <synopsis>
+<function>SaveComplete</function> [Client &rarr; SM]
 
-  <para>Valid Responses:</para>
+  Valid Responses:
+  </synopsis>
 
   <para>
 When the SM is done with a checkpoint, it will send each of the
@@ -802,7 +840,9 @@ clients a <function>SaveComplete</function> message.  The client is
 then free to change its state.
   </para>
 
-  <para><function>ShutdownCancelled</function> [Client &larr; SM]</para>
+  <synopsis>
+<function>ShutdownCancelled</function> [Client &larr; SM]
+  </synopsis>
 
   <para>
 The shutdown currently in process has been aborted.  The client can
@@ -814,9 +854,11 @@ continue with the save and send a <function>SaveYourselfDone</function>
 with the success field set to reflect the outcome of the save.
   </para>
 
-  <para><function>ConnectionClosed</function> [Client &rarr; SM]</para>
+  <synopsis>
+<function>ConnectionClosed</function> [Client &rarr; SM]
 
-  <para><emphasis remap='I'>reason</emphasis>: LISTofARRAY8</para>
+  <parameter>reason</parameter>: <type>LISTofARRAY8</type>
+  </synopsis>
 
   <para>
 Specifies that the client has decided to terminate.  It should be
@@ -824,8 +866,8 @@ immediately followed by closing the connection.
   </para>
 
   <para>
-The reason field specifies why the client is resigning from the
-session.  It is encoded as an array of Compound Text strings.  If the
+The <parameter>reason</parameter> field specifies why the client is resigning
+from the session.  It is encoded as an array of Compound Text strings.  If the
 resignation is expected by the user, there will typically be zero
 ARRAY8s here.  But if the client encountered an unexpected fatal
 error, the error message (which might otherwise be printed on stderr
@@ -848,12 +890,15 @@ protocols will not provide immediate notification of connection
 closure.
   </para></note>
 
-  <para><function>SetProperties</function> [Client &rarr; SM]</para>
+  <synopsis>
+<function>SetProperties</function> [Client &rarr; SM]
 
-  <para><emphasis remap='I'>properties</emphasis>: LISTofPROPERTY</para>
+  <parameter>properties</parameter>: <type>LISTofPROPERTY</type>
+  </synopsis>
 
   <para>
-Sets the specified properties to the specified values.  Existing
+Sets the specified <parameter>properties</parameter> to the specified values.
+Existing
 properties not specified in the <function>Set&shy;Properties</function>
 message are unaffected. Some properties have predefined semantics.
 See section 11, "Predefined Properties."
@@ -869,28 +914,34 @@ XSMP reserves all property names not beginning with an underscore for
 future use.
   </para>
 
-  <para><function>DeleteProperties</function> [Client &rarr; SM]</para>
+  <synopsis>
+<function>DeleteProperties</function> [Client &rarr; SM]
 
-  <para><emphasis remap='I'>property-names</emphasis>: LISTofARRAY8</para>
+  <parameter>property-names</parameter>: <type>LISTofARRAY8</type>
+  </synopsis>
 
   <para>Removes the named properties.</para>
 
-  <para><function>GetProperties</function> [Client &rarr; SM]</para>
+  <synopsis>
+<function>GetProperties</function> [Client &rarr; SM]
 
-  <para>Valid Responses: <function>GetPropertiesReply</function></para>
+  Valid Responses: <function>GetPropertiesReply</function>
+  </synopsis>
 
   <para>
 Requests that the SM respond with the values of all the properties for
 this client.
   </para>
 
-  <para><function>GetPropertiesReply</function> [Client &larr; SM]</para>
+  <synopsis>
+<function>GetPropertiesReply</function> [Client &larr; SM]
 
-  <para><emphasis remap='I'>values</emphasis>: LISTofPROPERTY</para>
+  <parameter>values</parameter>: <type>LISTofPROPERTY</type>
+  </synopsis>
 
   <para>
 This message is sent in reply to a <function>GetProperties</function>
-message and includes the values of all the properties.
+message and includes the <parameter>values</parameter> of all the properties.
   </para>
 </chapter>