move status icon protocols into the info manual

Signed-off-by: Mattias Andrée <maandree@operamail.com>

2 files changed, 263 insertions, 161 deletions

diff --git a/doc/info/mds.texinfo b/doc/info/mds.texinfo
index f8f3ba9..6a25575 100644
--- a/doc/info/mds.texinfo
+++ b/doc/info/mds.texinfo
@@ -1723,6 +1723,7 @@ simple, reference implementation of a, status icon tray.
 * Virtual Terminal Protocols::      Virtual terminal protocols.
 * Keyboard Protocols::              Keyboard protocols.
 * Clipboard Protocols::             Clipboard protocols.
+* Status Icon Protocols::           Status icon protocols.
 * Miscellaneous Protocols::         Miscellaneous protocols.
 @end menu
 
@@ -2796,6 +2797,268 @@ Optional add-on to the clipboard's functionallity.
 
 
 
+@node Status Icon Protocols
+@section Status Icon Protocols
+
+@menu
+* add-tray-icon::                   Add a status icons to the status icon tray.
+* update-tray-icon::                Change the status of a status icon.
+* tray-update::                     Send updates about the status tray to the status icon.
+* new-tray::                        Announce the existence of a new status icon trays.
+@end menu
+
+
+
+@node add-tray-icon
+@subsection add-tray-icon
+
+@table @asis
+@item Identifying header:
+@command{Command: add-tray-icon}
+
+@item Action:
+Add a status icons to the status icon tray.
+
+The client should keep in mind that there can be any number of
+trays available on the system: zero, one, two or three, ...,
+and that it will get a response once from every tray.
+
+@item Required header: @code{Client ID}
+Your ID, provided by the @code{ID assignment} header
+in response to a @code{Command: assign-id} header.
+
+@item Required header: @code{Package}
+The name of the package to which the program announced the icon
+belongs.
+
+@item Required header: @code{Icon ID}
+An ID of the icon that can be used identify the icon, icon ID:s
+are not unique, but the combination of a package and a icon ID
+should be unque and can be used to ignore already added icons
+and hide icons that the user has been configured to be hidden.
+
+@item Required header: @code{Title}
+A title describing the icon for the user, used to configured
+when icons should be hidden and shown among other configuration.
+
+@item Required header: @code{Icon}
+The name or pathname of an icon to use together with the title.
+
+@item Response:
+Recipients will respond with a message containing the headers:
+@table @code
+@item To
+Will contain the value of the @code{Client ID} from the
+message that triggered this response.
+@item In response to
+Will contain the value of the @code{Message ID} from the
+message that triggered this response.
+@item Message ID
+Will contain a value as described in @ref{Message Passing}.
+@item Socket
+Will contain an ID to where the icon should be embeded.
+@item Will send update
+The value of this header will be @code{yes} if this
+message will be followed by a @code{Command: tray-update}
+message. Otherwise the value will be @code{no}.
+@end table
+
+@item Purpose:
+Enable clients to add a small icon that displays the status
+of programs, particularly minimised programs and services.
+
+@item Compulsivity:
+Optional.
+@end table
+
+
+
+@node update-tray-icon
+@subsection update-tray-icon
+
+@table @asis
+@item Identifying header:
+@command{Command: update-tray-icon}
+
+@item Action:
+Change the status of a status icon.
+
+@item Required header: @code{Status}
+@table @code
+@item hide
+Hide the icon if the value of the
+@code{Status} header is @code{hide}.
+@item show
+Show the icon if the value of the
+@code{Status} header is @code{show}.
+@item active
+The icon is active if the value of
+the @code{Status} header is @code{active}.
+@item inactive
+The icon is inactive if the value of
+the @code{Status} header is @code{inactive}.
+@end table
+
+@item Purpose:
+Enable status trays to automatically hide inactive icons.
+
+@item Purpose:
+Hide icons without actually removing them.
+
+@item Compulsivity:
+Required if supporting @code{Command: add-tray-icon},
+only @code{Status: hide} and @code{Status show} is required.
+@end table
+
+
+
+@node tray-update
+@subsection tray-update
+
+@table @asis
+@item Identifying header:
+@command{Command: tray-update}
+
+@item Action:
+Send updates about the status tray to the status icon.
+
+@item Required header: @code{Socket}
+Where the icon is embedded, used to identify the
+affected tray.
+
+@item Conditionally required header: @code{Max colour}
+The maximum colour component value, for example, if using 24-bit
+colour, which component will be 8-bit and the maximum value will
+be 255, this also applies to the alpha component.
+Required if either for the @code{Colour}-, @code{Foreground}-
+or @code{Alpha}-header are used.
+
+@item Conditionally required header: @code{Size}
+The width and height, in pixels, the icon should have.
+Required if the @code{Length}-header is used,
+otherwise this header is optional.
+
+@item Conditionally required header: @code{Has alpha}
+@table @code
+@item yes
+The message contains an alpha channel if the
+value of the @code{Has alpha} header is @code{yes}.
+@item no
+The message does not contain an alpha channel if the
+value of the @code{Has alpha} header is @code{no}.
+@end table
+Required if the @code{Length}-header is used.
+
+@item Conditionally required header: @code{Bytes}
+The number of bytes the subpixels used, for example,
+24-bit colours will have this set to 1 because each
+subpixel has 8 bits, 48-bit colours will have this
+set to 2 because each subpixel has 16 bits
+Allowed values are: 1, 2, 4 and 8. These values are
+used used so that CPU:s with any endianness can be
+trivially used as the words sizes are guaranteed to
+be supported in C, and mixed/middle-endiannes gets
+complicated if we go outside this.
+Required if the @code{Length}-header is used.
+
+@item Conditionally optional/required header: @code{Colour}
+Single blank space-separated [0, @code{<Max colour>}]
+sRGB 3-tuple.
+Available and optional if the @code{Length}-header
+is not used.
+Required if the @code{Foreground}-header but not
+@code{Length}-header is used.
+
+@item Conditionally optional header: @code{Foreground}
+Single blank space-separated [0, @code{<Max colour>}] sRGB 3-tuple.
+
+@item Optional header: @code{Alpha}
+The opacity of the tray.
+
+@item Optional header: @code{Length}
+Length of the message.
+
+@item Optional header: @code{Use urgency}
+@table @code
+@item yes
+The icon tray may blink if the value of the
+@code{Use urgency} header is @code{yes}.
+@item no
+The icon tray may not blink if the value of
+the @code{Use urgency} header is @code{no}.
+@end table
+
+@item Message:
+Raw binary encoding of the background image, bytes
+are orders: row, pixel, channel (alpha, red, green,
+blue), subpixel value (native CPU encoding). The
+Alpha channel should be included but ignored if
+@code{Has alpha: no}, in such as it is best to set
+it to full.
+
+Example image with @code{Bytes: 2},
+@code{Has alpha: no} and @code{Size: 3}:
+@example
+sRGB(x0102, 0, 0), sRGB(0, x0304, 0), sRGB(0, 0, x0506)
+sRGB(x0708, 0, 0), sRGB(0, x090A, 0), sRGB(0, 0, x0B0C)
+sRGB(x0D0E, 0, 0), sRGB(0, x0F10, 0), sRGB(0, 0, x1112)
+@end example
+
+Encoding of example image in hexadecimal representation:
+@example
+FFFF 0102 0000 0000 FFFF 0000 0304 0000 FFFF 0000 0000 0506
+FFFF 0708 0000 0000 FFFF 0000 090A 0000 FFFF 0000 0000 0B0C
+FFFF 0D0E 0000 0000 FFFF 0000 0F10 0000 FFFF 0000 0000 1112
+@end example
+
+Note that on a big-endian system this would be:
+@footnote{x86_64 computers are big-endian.}
+@example
+FF FF 02 01 0 0 0 0 FF FF 0 0 04 03 0 0 FF FF 0 0 0 0 06 05
+FF FF 08 07 0 0 0 0 FF FF 0 0 0A 09 0 0 FF FF 0 0 0 0 0C 0B
+FF FF 0E 0D 0 0 0 0 FF FF 0 0 10 0F 0 0 FF FF 0 0 0 0 12 11
+@end example
+
+It is up to the networking servers to translate
+the encoding between machines.@footnote{The host
+translates to big-endian unless they can confirm
+that they have the same endianness.}
+
+@item Purpose:
+Enable clients to be aware of the appearance of the tray,
+such as colours, transparency and background image.
+
+@item Purpose:
+Enable clients to be aware of how the user wants
+status icons to behave.
+
+@item Compulsivity:
+Optional.
+@end table
+
+
+
+@node new-tray
+@subsection new-tray
+
+@table @asis
+@item Identifying header:
+@command{Command: new-tray}
+
+@item Action:
+Announce the existence of a new status icon trays.
+
+@item Purpose:
+Allow clients to add their status icons to status icon
+trays that have been added to the display after those
+programs have started and attempted to add their icons.
+
+@item Compulsivity:
+Required if supporting @code{Command: add-tray-icon}.
+@end table
+
+
+
 @node Miscellaneous Protocols
 @section Miscellaneous Protocols
 
diff --git a/doc/protocols b/doc/protocols
deleted file mode 100644
index 52c61bf..0000000
--- a/doc/protocols
+++ /dev/null
@@ -1,161 +0,0 @@
----------------------------------------------------------------------
-
-Command: add-tray-icon
-  Add a status icons to the status icon tray
-  The client should keep in mind that there can be any number of
-  trays available on the system: zero, one, two or three, ...,
-  and that it will get a response once from every tray
-
-Required header: Client ID
-  Your ID, provided by `ID assignment`
-  in response to `Command: assign-id`
-
-Required header: Package
-  The name of the package to which the program announced the icon
-  belongs
-
-Required header: Icon ID
-  An ID of the icon that can be used identify the icon, icon ID:s
-  are not unique, but the combination of a package and a icon ID
-  should be unque and can be used to ignore already added icons
-  and hide icons that the user has been configured to be hidden
-
-Required header: Title
-  A title describing the icon for the user, used to configured
-  when icons should be hidden and shown among other configuration
-
-Required header: Icon
-  The name or pathname of an icon to use together with the title
-
-Response:
-  To: <Client ID>
-  In response to: <Message ID>
-  Message ID: <the status tray's message ID>
-  Socket: <Where to embed the icon>
-  Will send update: <`yes` if this message will be followed by
-       	    	     `Command: tray-update`, otherwise `no`>
-
-Purpose: Enable clients to add a small icon that displays the status
-	 of programs, particularly minimised programs and services
-
-Compulsivity: optional
-
----------------------------------------------------------------------
-
-Command: update-tray-icon
-  Change the status of a status icon
-
-Required header: Status
-  hide)      Hide the icon
-  show)      Show the icon
-  active)    The icon is active
-  inactive)  The icon is inactive
-
-Purpose: Enable status trays to automatically hide inactive icons
-Purpose: Hide icons without actually removing them
-
-Compulsivity: required if supporting `Command: add-tray-icon`,
-	      only `Status: hide` and `Status show` is required
-
----------------------------------------------------------------------
-
-Command: tray-update
-  Send updates about the status tray to the status icon
-
-Required header: Socket
-  Where the icon is embedded, used to identify the affected tray
-
-Conditionally required header: Max colour
-  Required if: `Colour`-header is used
-  Required if: `Foreground`-header is used
-  Required if: `Alpha`-header is used
-  The maximum colour component value, for example, if using 24-bit
-  colour, which component will be 8-bit and the maximum value will
-  be 255, this also applies to the alpha component
-
-Conditionally required header: Size
-  Required if, otherwise optional: `Length`-header is used
-  The width and height, in pixels, the icon should have
-
-Conditionally required header: Has alpha
-  Required if: `Length`-header is used
-  yes)  The message contains an alpha channel
-  no)   The message does not contain an alpha channel
-
-Conditionally required header: Bytes
-  Required if: `Length`-header is used
-  The number of bytes the subpixels used, for example,
-  24-bit colours will have this set to 1 because each
-  subpixel has 8 bits, 48-bit colours will have this
-  set to 2 because each subpixel has 16 bits
-  Allowed values are: 1, 2, 4 and 8. These values are
-  used used so that CPU:s with any endianness can be
-  trivially used as the words sizes are guaranteed to
-  be supported in C, and mixed/middle-endiannes gets
-  complicated if we go outside this.
-
-Conditionally optional/required header: Colour
-  Available and optional if: `Length`-header is not used
-  Required if: `Foreground`-header but not `Length`-header is used
-  Single blank space-separated [0, <Max colour>] sRGB 3-tuple
-
-Conditionally optional header: Foreground
-  Single blank space-separated [0, <Max colour>] sRGB 3-tuple
-
-Optional header: Alpha
-  The opacity of the tray
-
-Optional header: Length
-  Length of the message
-
-Optional header: Use urgency
-  yes)  The icon tray may blink
-  no)   The icon tray may not blink
-
-Message: Raw binary encoding of the background image, bytes
-	 are orders: row, pixel, channel (alpha, red, green,
-	 blue), subpixel value (native CPU encoding). The
-	 Alpha channel should be included but ignored if
-	 `Has alpha: no`, in such as it is best to set it to
-	 full.
-	 
-	 Example image (with `Bytes: 2`, `Has alpha: no` and `Size: 3`):
-	   sRGB(x0102, 0, 0), sRGB(0, x0304, 0), sRGB(0, 0, x0506)
-	   sRGB(x0708, 0, 0), sRGB(0, x090A, 0), sRGB(0, 0, x0B0C)
-	   sRGB(x0D0E, 0, 0), sRGB(0, x0F10, 0), sRGB(0, 0, x1112)
-	
-	 Encoding of example image (hexadecimal):
-	   FFFF 0102 0000 0000 FFFF 0000 0304 0000 FFFF 0000 0000 0506
-	   FFFF 0708 0000 0000 FFFF 0000 090A 0000 FFFF 0000 0000 0B0C
-	   FFFF 0D0E 0000 0000 FFFF 0000 0F10 0000 FFFF 0000 0000 1112
-	   
-	   Note that on a big-endian system this would be:
-	     FF FF 02 01 00 00 00 00 FF FF 00 00 04 03 00 00 FF FF 00 00 00 00 06 05
-	     FF FF 08 07 00 00 00 00 FF FF 00 00 0A 09 00 00 FF FF 00 00 00 00 0C 0B
-	     FF FF 0E 0D 00 00 00 00 FF FF 00 00 10 0F 00 00 FF FF 00 00 00 00 12 11
-	     (x86_64 computers are big-endian)
-	   
-	   It is up to the networking servers to translate
-	   the encoding between machines. (The host translates to big-endian
-	   unless they can confirm that they have the same endianness.)
-
-Purpose: Enable clients to be aware of the appearance of the tray,
-	 such as colours, transparency and background image
-Purpose: Enable clients to be aware of how the user wants
-	 status icons to behave
-
-Compulsivity: optional
-
----------------------------------------------------------------------
-
-Command: new-tray
-  Announce the existence of a new status icon trays
-
-Purpose: Allow clients to add their status icons to status icon
-	 trays that have been added to the display after those
-	 programs have started and attempted to add their icons
-
-Compulsivity: required if supporting `Command: add-tray-icon`
-
----------------------------------------------------------------------
-