From c5b211d9a01438958546669f95a5215784348534 Mon Sep 17 00:00:00 2001 From: Alan Coopersmith Date: Fri, 22 Oct 2010 08:44:46 -0700 Subject: xsmp.xml: Misc markup tag cleanups Signed-off-by: Alan Coopersmith --- doc/xsmp.xml | 168 ++++++++++++++++++++++++++++++----------------------------- 1 file changed, 86 insertions(+), 82 deletions(-) diff --git a/doc/xsmp.xml b/doc/xsmp.xml index 6584be1..c2d41d8 100644 --- a/doc/xsmp.xml +++ b/doc/xsmp.xml @@ -68,7 +68,7 @@ This document specifies a protocol that facilitates the management of groups of client applications by a session manager. The session manager can cause clients to save their state, to shut down, and to be restarted into a previously saved state. This protocol is layered on -top of the X.Org ICE protocol. +top of the X.Org ICE protocol. @@ -78,8 +78,8 @@ top of the X.Org ICE protocol. Acknowledgments -First I would like to thank the entire ICCCM and Intrinsics working -groups for the comments and suggestions. I would like to make special +First I would like to thank the entire ICCCM and Intrinsics +working groups for the comments and suggestions. I would like to make special thanks to the following people (in alphabetical order), Jordan Brown, Ellis Cohen, Donna Converse, Vania Joloboff, Stuart Marks, Ralph Mor and Bob Scheifler. @@ -90,12 +90,12 @@ and Bob Scheifler. Definitions and Goals -The purpose of the X Session Management Protocol (XSMP) is to provide -a uniform mechanism for users to save and restore their sessions. -A session is a group of clients, each +The purpose of the X Session Management Protocol (XSMP) is +to provide a uniform mechanism for users to save and restore their sessions. +A session is a group of clients, each of which has a particular state. The session is controlled by a -network service called the session -manager. The session manager issues commands to its +network service called the session manager. +The session manager issues commands to its clients on behalf of the user. These commands may cause clients to save their state or to terminate. It is expected that the client will save its state in such a way that the client can be restarted at a @@ -108,7 +108,7 @@ protocol. -For purposes of this protocol, a client +For purposes of this protocol, a client of the session manager is defined as a connection to the session manager. A client is typically, though not necessarily, a process running an application program connected to an X Window System @@ -117,8 +117,8 @@ display or not be connected to any X displays at all. -This protocol is layered on top of the X Consortium's ICE protocol and -relies on the ICE protocol to handle connection management and authentication. +This protocol is layered on top of the X Consortium's ICE protocol and +relies on the ICE protocol to handle connection management and authentication. @@ -138,13 +138,13 @@ taken as an indication that the client died unexpectedly. Clients are expected to save their state in such a way as to allow multiple instantiations of themselves to be managed independently. A -unique value called a client-ID is +unique value called a client-ID is provided by the protocol for the purpose of disambiguating multiple instantiations of clients. Clients may use this ID, for example, as part of a filename in which to store the state for a particular instantiation. The client-ID should be saved as part of the command used to restart this client -(the RestartCommand) so that the client +(the RestartCommand) so that the client will retain the same ID after it is restarted. Certain small pieces of state might also be stored in the RestartCommand. For example, an X11 client might place a '-twoWindow' option in its RestartCommand to @@ -154,22 +154,23 @@ restarted. The client finds the network address of the SM in a system-dependent -way. On POSIX systems an environment variable called SESSION_MANAGER +way. On POSIX systems an environment +variable called SESSION_MANAGER will contain a list of network IDs. Each id will contain the transport name followed by a slash and the (transport-specific) address. A TCP/IP address would look like this: - -tcp/hostname:portnumber - + + tcp/hostname:portnumber + where the hostname is a fully qualified domain name. A Unix Domain address looks like this: - -local/hostname:path - + + local/hostname:path + A DECnet address would look like this: - -decnet/nodename::objname - + + decnet/nodename::objname + @@ -214,8 +215,8 @@ Some clients may wish to manage the programs they start. For example, a mail program could start a text editor for editing the text of a mail message. A client that does this is a session manager itself; it should supply the clients it starts with the appropriate connection -information (i.e., the SESSION_MANAGER environment variable) that -specifies a connection to itself instead of to the top level session +information (i.e., the SESSION_MANAGER environment variable) +that specifies a connection to itself instead of to the top level session manager. @@ -235,7 +236,7 @@ no properties set. XSMP messages contain several types of data. Both the SM and the client always send messages in their native byte order. Thus, both sides may need to byte-swap the messages received. The need to do -byte-swapping is determined at run-time by the ICE protocol. +byte-swapping is determined at run-time by the ICE protocol. @@ -257,7 +258,7 @@ the receiver of the message to the sender of the message. BOOL - False or True + False or True INTERACT_STYLE @@ -310,9 +311,9 @@ the receiver of the message to the sender of the message. To start the XSMP protocol, the client sends the server an -ICE ProtocolSetup message. All XSMP messages are -in the standard ICE message format. The message's major opcode is -assigned to XSMP by ICE at run-time. The different parties (client +ICE ProtocolSetup message. All XSMP messages are +in the standard ICE message format. The message's major opcode is +assigned to XSMP by ICE at run-time. The different parties (client and SM) may be assigned different major opcodes for XSMP. Once assigned, all XSMP messages issued by this party will use the same major opcode. The message's minor opcode specifies which protocol @@ -332,20 +333,24 @@ and Register­ClientReply messages. Client IDs consist of the pieces described below. The ID is formed by concatenating the pieces in sequence, without separator characters. -All pieces are padded on the left with '0' characters so as to fill -the specified length. Decimal numbers are encoded using the -characters '0' through '9', and hexadecimal numbers using the -characters '0' through '9' and 'A' through 'F'. +All pieces are padded on the left with '0' +characters so as to fill the specified length. Decimal numbers are +encoded using the characters '0' through +'9', and hexadecimal numbers using the characters +'0' through '9' and +'A' through 'F'. - Version. This is currently the character '1'. + +Version. This is currently the character '1'. + Address type and address. The address type will be one of - '1' a 4-byte IPv4 address encoded as 8 hexadecimal digits - '2' a 6-byte DECNET address encoded as 12 hexadecimal digits - '6' a 16-byte IPv6 address encoded as 32 hexadecimal digits + '1' a 4-byte IPv4 address encoded as 8 hexadecimal digits + '2' a 6-byte DECNET address encoded as 12 hexadecimal digits + '6' a 16-byte IPv6 address encoded as 32 hexadecimal digits @@ -353,7 +358,7 @@ characters '0' through '9' and 'A' through 'F'. The address is the one of the network addresses of the machine where the session manager (not the client) is running. For example, the IP address 198.112.45.11 would be encoded as the string -"QC6702D0B". +"QC6702D0B". @@ -364,7 +369,7 @@ address 198.112.45.11 would be encoded as the string Process-ID type and process-ID. The process-ID type will be one of -'1' a POSIX process-ID encoded as a 10-digit decimal number. + '1' a POSIX process-ID encoded as a 10-digit decimal number. @@ -398,12 +403,12 @@ any user, session manager, and machine will be different from any other. Protocol The protocol consists of a sequence of messages as described below. -Each message type is specified by an ICE minor opcode. A given +Each message type is specified by an ICE minor opcode. A given message type is sent either from a client to the session manager or from the session manager to a client; the appropriate direction is listed with each message's description. For each message type, the set of valid responses and possible error messages are listed. The -ICE severity is given in parentheses following each error class. +ICE severity is given in parentheses following each error class. RegisterClient [Client → SM] @@ -604,7 +609,7 @@ user does after the save will be lost. 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 True +is about to fail, it should set the fast field to True SaveYourselfPhase2 [Client → SM] @@ -660,15 +665,16 @@ message in response and it may leave the fields intact. -A vendor of a UPS (Uninterruptible Power Supply) might include an SM client -that would monitor the status of the UPS and generate a fast shutdown if the -power is about to be lost. +A vendor of a UPS (Uninterruptible Power Supply) +might include an SM client that would monitor the status of +the UPS and generate a fast shutdown if the power +is about to be lost. -If global is set to True then the +If global is set to True then the resulting SaveYourself should be sent to all -applications. If global is set to False then the +applications. If global is set to False then the resulting SaveYourself should be sent to the application that sent the Save­Yourself­Request @@ -723,14 +729,14 @@ This message is used by a client to notify the SM that it is done interacting. -Setting the cancel-shutdown field to True +Setting the cancel-shutdown field to True indicates that the user has requested that the entire shutdown be -cancelled. Cancel-shutdown may only be True if +cancelled. Cancel-shutdown may only be True if the corresponding SaveYourself message -specified True for the shutdown field +specified True for the shutdown field and Any or Errors for the interact-style field. Otherwise, cancel-shutdown must -be False +be False SaveYourselfDone [Client → SM] @@ -750,14 +756,14 @@ sending SaveYourselfDone the client must wait for a SaveComplete ShutdownCancelled or Die message before changing its state. If the SaveYourself operation was successful, then -the client should set the success field to True -otherwise the client should set it to False +the client should set the success field to True +otherwise the client should set it to False If a client tries to save its state and runs out of disk space, it -should return False in the success field of +should return False in the success field of the SaveYourselfDone message. @@ -802,7 +808,7 @@ The shutdown currently in process has been aborted. The client can now continue as if the shutdown had never happened. If the client has not sent SaveYourselfDone yet, the client can either abort the save and send SaveYourselfDone -with the success field set to False or it can +with the success field set to False or it can continue with the save and send a SaveYourselfDone with the success field set to reflect the outcome of the save. @@ -822,7 +828,7 @@ 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 -on a POSIX system) should be forwarded to the SM here, one ARRAY8 per +on a POSIX system) should be forwarded to the SM here, one ARRAY8 per line of the message. It is the responsibility of the SM to display this reason to the user. @@ -892,10 +898,10 @@ message and includes the values of all the properties. When the receiver of a message detects an error condition, the -receiver sends an ICE error message to the sender. There are only two +receiver sends an ICE error message to the sender. There are only two types of errors that are used by the XSMP: BadValue and BadState -These are both defined in the ICE protocol. +These are both defined in the ICE protocol. @@ -917,7 +923,7 @@ client and the SM. start: - ICE protocol setup complete → register + ICE protocol setup complete → register register: @@ -1379,18 +1385,19 @@ client and the SM. Messages -XSMP is a sub-protocol of ICE. The major opcode is assigned at -run-time by ICE and is represented here by '?'. +XSMP is a sub-protocol of ICE. The major opcode is +assigned at run-time by ICE and is represented here +by '?'. To start the XSMP protocol, the client sends the server an -ICE ProtocolSetup message. The protocol-name -field should be specified as "XSMP", the major version of the protocol -is 1, the minor version is 0. These values may change if the protocol -is revised. The minor version number will be incremented if the -change is compatible, otherwise the major version number will be -incremented. +ICE ProtocolSetup message. +The protocol-name field should be specified as "XSMP", +the major version of the protocol is 1, the minor version is 0. These +values may change if the protocol is revised. The minor version +number will be incremented if the change is compatible, otherwise the +major version number will be incremented. @@ -1399,7 +1406,7 @@ manager, the XSMP protocol defines the vendor parameter as product identification of the session manager, and defines the release parameter as the software release identification of the session manager. The session manager should supply this information in the -ICE ProtocolReply message. +ICE ProtocolReply message. @@ -2284,14 +2291,14 @@ of stored properties does not extend into subsequent sessions. This is like the RestartCommand except it restarts a copy of the application. The only difference is that the -application doesn't supply its client id at register time. On POSIX +application doesn't supply its client id at register time. On POSIX systems the type should be a LISTofARRAY8. CurrentDirectory -On POSIX-based systems specifies the value of the current directory that +On POSIX-based systems specifies the value of the current directory that needs to be set up prior to starting the program and should be of type ARRAY8. @@ -2303,13 +2310,13 @@ that the client is running on (determined from the connection), will cause it to discard any information about the current state. If this command is not specified, the SM will assume that all of the client's state is encoded in the Restart­Command On -POSIX systems the type should be LISTofARRAY8. +POSIX systems the type should be LISTofARRAY8. Environment -On POSIX based systems, this will be of type LISTofARRAY8 where the +On POSIX based systems, this will be of type LISTofARRAY8 where the ARRAY8s alternate between environment variable name and environment variable value. @@ -2317,7 +2324,7 @@ variable value. ProcessID -This specifies an OS-specific identifier for the process. On POSIX +This specifies an OS-specific identifier for the process. On POSIX systems this should of type ARRAY8 and contain the return value of getpid() turned into a Latin-1 (decimal) string. @@ -2325,7 +2332,7 @@ getpid() turned into a Latin-1 (decimal) string. Program -The name of the program that is running. On POSIX systems this should +The name of the program that is running. On POSIX systems this should be the first parameter passed to execve and should be of type ARRAY8. @@ -2334,7 +2341,7 @@ be the first parameter passed to execve and should be of type ARRAY8. The restart command contains a command that when delivered to the host that the client is running on (determined from the connection), will -cause the client to restart in its current state. On POSIX-based +cause the client to restart in its current state. On POSIX-based systems this is of type LISTofARRAY8 and each of the elements in the array represents an element in the argv array. This restart command should ensure that the client restarts with the specified @@ -2379,10 +2386,6 @@ possible values are as follows: Name Value - - .TH - - @@ -2480,8 +2483,9 @@ to Restart­Anyway and would register a UserID -Specifies the user's ID. On POSIX-based systems this will contain the -the user's name (the pw_name field of struct passwd). +Specifies the user's ID. On POSIX-based systems +this will contain the the user's name (the pw_name +field of struct passwd). -- cgit v1.2.3