specs: replace troff source with docbook-xml source

Signed-off-by: Gaetan Nadon <memsize@videotron.ca>

5 files changed, 1012 insertions, 0 deletions

diff --git a/Makefile.am b/Makefile.am
index 0a26e33..8f51dd8 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,3 +1,5 @@
+SUBDIRS=specs
+
 scrnsaverdir = $(includedir)/X11/extensions
 scrnsaver_HEADERS = \
 	saver.h \
diff --git a/configure.ac b/configure.ac
index 13ed780..f9f0b1a 100644
--- a/configure.ac
+++ b/configure.ac
@@ -8,6 +8,11 @@ m4_ifndef([XORG_MACROS_VERSION],
           [m4_fatal([must install xorg-macros 1.3 or later before running autoconf/autogen])])
 XORG_MACROS_VERSION(1.3)
 XORG_DEFAULT_OPTIONS
+XORG_ENABLE_SPECS
+XORG_WITH_XMLTO(0.0.20)
+XORG_WITH_FOP
+XORG_CHECK_SGML_DOCTOOLS(1.5)
 
 AC_OUTPUT([Makefile
+           specs/Makefile
            scrnsaverproto.pc])
diff --git a/specs/.gitignore b/specs/.gitignore
new file mode 100644
index 0000000..12fe512
--- /dev/null
+++ b/specs/.gitignore
@@ -0,0 +1,6 @@
+#		Add & Override for this directory and it's subdirectories
+*.html
+*.ps
+*.pdf
+*.txt
+*.css
diff --git a/specs/Makefile.am b/specs/Makefile.am
new file mode 100644
index 0000000..a312ac9
--- /dev/null
+++ b/specs/Makefile.am
@@ -0,0 +1,64 @@
+#
+# Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice (including the next
+# paragraph) shall be included in all copies or substantial portions of the
+# Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+#
+
+if ENABLE_SPECS
+doc_sources = saver.xml
+dist_doc_DATA = $(doc_sources)
+
+if HAVE_XMLTO
+doc_DATA = $(doc_sources:.xml=.html)
+
+if HAVE_FOP
+doc_DATA += $(doc_sources:.xml=.ps) $(doc_sources:.xml=.pdf)
+endif
+
+if HAVE_XMLTO_TEXT
+doc_DATA += $(doc_sources:.xml=.txt)
+endif
+
+if HAVE_STYLESHEETS
+XMLTO_FLAGS = -m $(XSL_STYLESHEET)
+
+doc_DATA += xorg.css
+xorg.css: $(STYLESHEET_SRCDIR)/xorg.css
+	$(AM_V_GEN)cp -pf $(STYLESHEET_SRCDIR)/xorg.css $@
+endif
+
+CLEANFILES = $(doc_DATA)
+
+SUFFIXES = .xml .ps .pdf .txt .html
+
+.xml.txt:
+	$(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) txt $<
+
+.xml.html:
+	$(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) xhtml-nochunks $<
+
+.xml.pdf:
+	$(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop pdf $<
+
+.xml.ps:
+	$(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop ps $<
+
+endif HAVE_XMLTO
+endif ENABLE_SPECS
diff --git a/specs/saver.xml b/specs/saver.xml
new file mode 100644
index 0000000..93b5229
--- /dev/null
+++ b/specs/saver.xml
@@ -0,0 +1,935 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<book id="saver">
+
+<bookinfo>
+   <title>X11 Screen Saver Extension</title>
+   <subtitle>MIT X Consortium Proposed Standard</subtitle>
+   <releaseinfo>Version 1.0</releaseinfo>
+   <authorgroup>
+   <othercredit>
+      <firstname>Jim</firstname><surname>Fulton</surname>
+      <affiliation><orgname>Network Computing Devices, Inc</orgname></affiliation>
+   </othercredit>
+   <othercredit>
+      <firstname>Keith</firstname><surname>Packard</surname>
+      <affiliation><orgname>
+X Consortium, Laboratory for Computer Science, Massachusetts Institute of Technology
+      </orgname></affiliation>
+   </othercredit>
+   </authorgroup>
+
+   <copyright><year>1992</year><holder>Massachusetts Institute of Technology and Network Computing Devices, Inc</holder></copyright>
+
+   <productnumber>X Version 11, Release 5</productnumber>
+
+<legalnotice>
+<para>
+Permission to use, copy, modify, and distribute this documentation for any
+purpose and without fee is hereby granted, provided that the above copyright
+notice and this permission notice appear in all copies.  MIT and
+Network Computing Devices, Inc. make no
+representations about the suitability for any purpose of the information in
+this document.  This documentation is provided "as is" without express or
+implied warranty.
+</para>
+
+</legalnotice>
+</bookinfo>
+
+<chapter id="title">
+<title>TITLE</title>
+<sect1 id="Introduction_">
+<title>Introduction</title>
+<para>
+The X Window System provides support for changing the image on a display screen
+after a user-settable period of inactivity to avoid burning the cathode ray
+tube phosphors.  However, no interfaces are provided for the user to control
+the image that is drawn.  This extension allows an external "screen saver"
+client to detect when the alternate image is to be displayed and to provide the
+graphics.
+</para>
+<para>
+Current X server implementations typically provide at least one form of
+"screen saver" image.  Historically, this has been a copy of the X logo
+drawn against the root background pattern.  However, many users have asked
+for the mechanism to allow them to write screen saver programs that provide
+capabilities similar to those provided by other window systems.  In
+particular, such users often wish to be able to display corporate logos,
+instructions on how to reactivate the screen, and automatic screen-locking
+utilities.  This extension provides a means for writing such clients.
+</para>
+</sect1>
+
+<sect1 id="Assumptions">
+<title>Assumptions</title>
+<para>
+This extension exports the notion of a special screen saver window that is
+mapped above all other windows on a display.  This window has the
+<emphasis remap='I'>override-redirect</emphasis> attribute set so that it is not subject to manipulation by
+the window manager.  Furthermore, the X identifier for the window is never
+returned by <function>QueryTree</function> requests on the root window, so it is typically
+not visible to other clients.
+</para>
+</sect1>
+
+<sect1 id="Overview">
+<title>Overview</title>
+<para>
+The core
+<function>SetScreenSaver</function>
+request can be used to set the length of time without
+activity on any input devices after which the screen saver should "activate"
+and alter the image on the screen.  This image periodically "cycles" to
+reduce
+the length of time that any particular pixel is illuminated.  Finally, the
+screen saver is "deactivated" in response to activity on any of the input
+devices
+or particular X requests.
+</para>
+
+<para>
+Screen saving is typically done by disabling video output to the display tube
+or by drawing a changing pattern onto the display.  If the server chooses the
+latter approach, a window with a special identifier is created and mapped at
+the top of the stacking order where it remains until the screen saver
+deactivates.  At this time, the window is unmapped and is not accessible to any
+client requests.
+</para>
+<para>
+The server's default mechanism is refered to as the <emphasis remap='I'>internal</emphasis> screen
+saver.  An <emphasis remap='I'>external</emphasis>
+screen saver client requires a means of determining the window
+id for the screen saver window and setting the attributes (e.g. size,
+location, visual, colormap) to be used when the window is mapped.  These
+requirements form the basis of this extension.
+</para>
+</sect1>
+
+<sect1 id="Issues">
+<title>Issues</title>
+<para>
+This extension raises several interesting issues.  First is the question of
+what should be done if some other client has the server grabbed when the screen
+saver is supposed to activate?  This commonly occurs with window managers that
+automatically ask the user to position a window when it is first mapped by
+grabbing the server and drawing XORed lines on the root window.
+</para>
+<para>
+Second, a screen saver program must control the actual RGB values sent to the
+display tube to ensure that the values change periodically to avoid phosphor
+burn in.  Thus, the client must have a known colormap installed whenever the
+screen saver window is displayed.  To prevent screen flashing, the visual type
+of the screen saver window should also be controlable.
+</para>
+<para>
+Third, some implementations may wish to destroy the screen saver window when
+it is not mapped so that it need not be avoided during event delivery.  Thus,
+screen saver clients may find that the requests that reference the screen
+saver window may fail when the window is not displayed.
+</para>
+</sect1>
+
+<sect1 id="Protocol">
+<title>Protocol</title>
+<para>
+The Screen Saver extension is as follows:
+</para>
+
+<sect2 id="Types">
+<title>Types</title>
+<para>
+In adition to the comon types described in the core protocol, the following
+type is used in the request and event definitions in subsequent sections.
+</para>
+
+<informaltable frame="none">
+  <tgroup cols='2' align='left'>
+  <colspec colname='c1' colsep="0"/>
+  <colspec colname='c2' colsep="0"/>
+  <thead>
+    <row>
+      <entry>Name</entry>
+      <entry>Value</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row rowsep="0">
+      <entry>SCREENSAVEREVENT</entry>
+      <entry><emphasis role="bold">ScreenSaverNotify</emphasis>,
+      <emphasis role="bold">ScreenSaverCycle</emphasis></entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+</sect2>
+
+<sect2 id="Errors">
+<title>Errors</title>
+<para>
+The Screen Saver extension adds no errors beyond the core protocol.
+</para>
+</sect2>
+
+<sect2 id="Requests">
+<title>Requests</title>
+<para>
+The Screen Saver extension adds the following requests:
+</para>
+
+<literallayout>
+<emphasis role="bold">ScreenSaverQueryVersion</emphasis>
+     client-major-version: CARD8
+     client-minor-version: CARD8
+->
+     server-major-version: CARD8
+     server-minor-version: CARD8
+</literallayout>
+
+<para>
+This request allows the client and server to determine which version of
+the protocol should be used.  The client sends the version that it
+prefers; if the server understands that
+version, it returns the same values and interprets subsequent requests
+for this extension according to the specified version.  Otherwise,
+the server returns the closest version of the protocol that it can
+support and interprets subsequent requests according to that version.
+This document describes major version 1, minor version 0; the major
+and minor revision numbers should only be incremented in response to
+incompatible and compatible changes, respectively.
+</para>
+
+<literallayout>
+<emphasis role="bold">ScreenSaverQueryInfo</emphasis>
+<emphasis>drawable</emphasis> DRAWABLE
+
+saver-window: WINDOW
+state: {<emphasis role="bold">Disabled</emphasis>, <emphasis role="bold">Off</emphasis>, <emphasis role="bold">On</emphasis>}
+kind: {<emphasis role="bold">Blanked</emphasis>, <emphasis role="bold">Internal</emphasis>, <emphasis role="bold">External</emphasis>}
+til-or-since: CARD32
+idle: CARD32
+event-mask: SETofSCREENSAVEREVENT
+
+Errors: <emphasis role="bold">Drawable</emphasis>
+</literallayout>
+
+<para>
+This request returns information about the state of the screen
+saver on the screen associated with <emphasis remap='I'>drawable</emphasis>.  The <emphasis remap='I'>saver-window</emphasis>
+is the XID that is associated with the screen saver window.  This
+window is not guaranteed to exist
+except when external screen saver is active.  Although it is a
+child of the root, this window is not returned by
+<function>QueryTree</function>
+requests on the root.  Whenever this window is mapped, it is always above
+any of its siblings in the stacking order.  XXX - TranslateCoords?
+</para>
+<para>
+The <emphasis remap='I'>state</emphasis> field specifies whether or not the screen saver is currently
+active and how the <emphasis remap='I'>til-or-since</emphasis> value should be interpretted:
+</para>
+
+<informaltable frame="none">
+  <tgroup cols='2' align='left'>
+  <colspec colname='c1' colsep="0"/>
+  <colspec colname='c2' colsep="0"/>
+  <tbody>
+    <row rowsep="0">
+      <entry><emphasis role="bold">Off</emphasis></entry>
+      <entry>
+The screen is not currently being saved;
+<emphasis remap='I'>til-or-since</emphasis>
+specifies the number of milliseconds until the screen saver is expected to
+activate.
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry><emphasis role="bold">On</emphasis></entry>
+      <entry>
+The screen is currently being saved;
+<emphasis remap='I'>til-or-since</emphasis> specifies
+the number of milliseconds since the screen saver activated.
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry><emphasis role="bold">Disabled</emphasis></entry>
+      <entry>
+The screen saver is currently disabled;
+<emphasis remap='I'>til-or-since</emphasis> is zero.
+      </entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+The <emphasis remap='I'>kind</emphasis> field specifies the mechanism that either is currently being
+used or would have been were the screen being saved:
+</para>
+
+<informaltable frame="none">
+  <tgroup cols='2' align='left'>
+  <colspec colname='c1' colsep="0"/>
+  <colspec colname='c2' colsep="0"/>
+  <tbody>
+    <row rowsep="0">
+      <entry><emphasis role="bold">Blanked</emphasis></entry>
+      <entry>The video signal to the display monitor was disabled.</entry>
+    </row>
+    <row rowsep="0">
+      <entry><emphasis role="bold">Internal</emphasis></entry>
+      <entry>A server-dependent, built-in screen saver image was displayed; either no
+      client had set the screen saver window attributes or a different client
+      had the server grabbed when the screen saver activated.</entry>
+    </row>
+    <row rowsep="0">
+      <entry><emphasis role="bold">External</emphasis></entry>
+      <entry>The screen saver window was mapped with attributes set by a
+      client using the <function>ScreenSaverSetAttributes</function> request.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+The <emphasis remap='I'>idle</emphasis> field specifies the number of milliseconds since the last
+input was received from the user on any of the input devices.
+</para>
+
+<para>
+The <emphasis remap='I'>event-mask</emphasis> field specifies which, if any, screen saver
+events this client has requested using <function>ScreenSaverSelectInput</function>.
+</para>
+
+<para>
+If <emphasis remap='I'>drawable</emphasis> is not a valid drawable identifier, a Drawable
+error is returned and the request is ignored.
+</para>
+
+<literallayout>
+<emphasis role="bold">ScreenSaverSelectInput</emphasis>
+drawable: DRAWABLE
+event-mask: SETofSCREENSAVEREVENT
+</literallayout>
+
+<para>
+Errors:
+<emphasis role="bold">Drawable</emphasis>,
+<emphasis role="bold">Match</emphasis>
+</para>
+
+<para>
+This request specifies which Screen Saver extension events on the screen
+associated with <emphasis remap='I'>drawable</emphasis> should be generated for this client.  If
+no bits are set in <emphasis remap='I'>event-mask</emphasis>, then no events will be generated.
+Otherwise, any combination of the following bits may be set:
+</para>
+
+<informaltable frame="none">
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1' colsep="0"/>
+  <colspec colname='c2' colsep="0"/>
+  <tbody>
+    <row rowsep="0">
+      <entry><emphasis role="bold">ScreenSaverNotify</emphasis></entry>
+      <entry>
+If this bit is set, <emphasis role="bold">ScreenSaverNotify</emphasis> events are generated whenever
+the screen saver is activated or deactivated.
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry><emphasis role="bold">ScreenSaverCycle</emphasis></entry>
+      <entry>
+If this bit is set, <emphasis role="bold">ScreenSaverNotify</emphasis> events are generated whenever
+the screen saver cycle interval passes.
+      </entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+If <emphasis remap='I'>drawable</emphasis> is not a valid drawable identifier, a Drawable
+error is returned.  If any undefined bits are set in <emphasis remap='I'>event-mask</emphasis>,
+a Value error is returned.  If an error is returned,
+the request is ignored.
+</para>
+
+<para>
+<emphasis role="bold">ScreenSaverSetAttributes</emphasis>
+</para>
+<literallayout>
+drawable: DRAWABLE
+class:
+{<emphasis role="bold">InputOutput</emphasis>, <emphasis role="bold">InputOnly</emphasis>, <emphasis role="bold">CopyFromParent</emphasis>}
+depth: CARD8
+visual: VISUALID or <emphasis role="bold">CopyFromParent</emphasis>
+x, y: INT16
+width, height, border-width: CARD16
+value-mask: BITMASK
+value-list: LISTofVALUE
+
+<emphasis role="bold">Access</emphasis>, <emphasis role="bold">Window</emphasis>, <emphasis role="bold">Pixmap</emphasis>, <emphasis role="bold">Colormap</emphasis>, <emphasis role="bold">Cursor</emphasis>, <emphasis role="bold">Match</emphasis>, <emphasis role="bold">Value</emphasis>, <emphasis role="bold">Alloc</emphasis>
+</literallayout>
+
+<para>
+This request sets the attributes that this client would like to see
+used in creating the screen saver window on the screen associated
+with <emphasis remap='I'>drawable</emphasis>.  If another client currently has the attributes set,
+an Access error is generated and the request is ignored.
+</para>
+
+<para>
+Otherwise, the specified window attributes are checked as if
+they were used in a core <function>CreateWindow</function> request whose
+parent is the root.  The <emphasis remap='I'>override-redirect</emphasis> field is ignored as
+it is implicitly set to True.  If the window attributes result in an
+error according to the rules for <function>CreateWindow</function>, the request is ignored.
+</para>
+<para>
+Otherwise, the attributes are stored and will take effect on the next
+activation that occurs when the server is not grabbed by another client.
+Any resources specified for the
+<emphasis remap='I'>background-pixmap</emphasis> or <emphasis remap='I'>cursor</emphasis> attributes may be
+freed immediately.  The server is free to copy the <emphasis remap='I'>background-pixmap</emphasis>
+or <emphasis remap='I'>cursor</emphasis> resources or to use them in place; therefore, the effect of
+changing the contents of those resources is undefined.  If the
+specified <emphasis remap='I'>colormap</emphasis> no longer exists when the screen saver activates,
+the parent's colormap is used instead.  If no errors are generated by this
+request, any previous
+screen saver window attributes set by this client are released.
+</para>
+<para>
+When the screen saver next activates and the server is not grabbed by
+another client, the screen saver window is
+created, if necessary, and set to the specified attributes and events
+are generated as usual.  The colormap
+associated with the screen saver window is
+installed.  Finally, the screen saver window is mapped.
+</para>
+<para>
+The window remains mapped and at the top of the stacking order
+until the screen saver is deactivated in response to activity on
+any of the user input devices, a <function>ForceScreenSaver</function> request with
+a value of Reset, or any request that would cause the window to be
+unmapped.
+</para>
+<para>
+If the screen saver activates while the server is grabbed by another
+client, the internal saver mechanism is used.  The <function>ForceScreenSaver</function>
+request may be used with a value of Active to
+deactivate the internal saver and activate the external saver.
+</para>
+<para>
+If the screen saver client's connection to the server is broken
+while the screen saver is activated and the client's close down mode has not
+been RetainPermanent or RetainTemporary, the current screen saver
+is deactivated and the internal screen saver is immediately activated.
+</para>
+<para>
+When the screen saver deactivates, the screen saver window's colormap
+is uninstalled and the window is unmapped (except as described below).
+The screen saver XID is disassociated
+with the window and the server may, but is not required to,
+destroy the window along with any children.
+</para>
+<para>
+When the screen saver is being deactivated and then immediately
+reactivated (such as when switching screen savers), the server
+may leave the screen saver window mapped (typically to avoid
+generating exposures).
+</para>
+
+<para>
+<emphasis role="bold">ScreenSaverUnsetAttributes</emphasis>
+</para>
+
+<literallayout>
+<emphasis>drawble</emphasis>: <emphasis role="bold">DRAWABLE</emphasis>
+
+Errors: <emphasis role="bold">Drawable</emphasis>
+</literallayout>
+
+<para>
+This request notifies the server that this client no longer
+wishes to control the screen saver window.  Any screen saver
+attributes set by this client and any descendents of the screen
+saver window created by this client should be released
+immediately if the screen saver is not active, else upon
+deactivation.
+</para>
+<para>
+This request is ignored if the client has not previously set the screen saver
+window attributes.
+</para>
+</sect2>
+
+<sect2 id="Events_">
+<title>Events</title>
+<para>
+The Screen Saver extension adds one event:
+</para>
+<para>
+<emphasis role="bold">ScreenSaverNotify</emphasis>
+</para>
+
+<literallayout>
+<emphasis role="bold">root</emphasis>: WINDOW
+<emphasis role="bold">window</emphasis>: WINDOW
+<emphasis role="bold">state</emphasis>: {<emphasis role="bold">Off</emphasis>, <emphasis role="bold">On</emphasis>, <emphasis role="bold">Cycle</emphasis>}
+<emphasis role="bold">kind</emphasis>: { <emphasis role="bold">Blanked</emphasis>, <emphasis role="bold">Internal</emphasis> , <emphasis role="bold">External</emphasis> }
+<emphasis role="bold">forced</emphasis>: BOOL
+<emphasis role="bold">time</emphasis>: TIMESTAMP
+</literallayout>
+<para>
+This event is delivered to clients that have requested
+ScreenSaverNotify events using the <function>ScreenSaverSelectInput</function> request
+whenever the screen saver activates or deactivates.
+</para>
+<para>
+The <emphasis remap='I'>root</emphasis> field specifies root window of the screen for
+which the event was generated.  The <emphasis remap='I'>window</emphasis> field specifies
+the value that is returned by <function>ScreenSaverQueryInfo</function> as
+the identifier for the screen saver window.  This window is not
+required to exist if the external screen saver is not active.
+</para>
+<para>
+The <emphasis remap='I'>state</emphasis> field specifies the cause of the event:
+</para>
+
+<informaltable frame="none">
+  <tgroup cols='2' align='left'>
+  <colspec colname='c1' colsep="0"/>
+  <colspec colname='c2' colsep="0"/>
+  <tbody>
+    <row rowsep="0">
+      <entry><emphasis role="bold">Off</emphasis></entry>
+      <entry>
+The screen saver deactivated; this event is sent if the client has set the
+ScreenSaverNotify bit in its event mask.
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry><emphasis role="bold">On</emphasis></entry>
+      <entry>
+The screen saver activated.  This event is sent if the client has set the
+ScreenSaverNotify bit in its event mask.
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry><emphasis role="bold">Cycle</emphasis></entry>
+      <entry>
+The cycle interval passed and the client is expected to change the image on
+the screen.  This event is sent if the client has set the
+ScreenSaverCycle bit in its event mask.
+      </entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+If <emphasis remap='I'>state</emphasis> is set to
+<emphasis role="bold">On </emphasis> or
+<emphasis role="bold">Off</emphasis>
+then <emphasis remap='I'>forced</emphasis> indicates whether or not
+activation or deactivation was caused by a core
+<function>ForceScreenSaver</function>
+request; otherwise, <emphasis remap='I'>forced</emphasis> is set to False.
+</para>
+
+<para>
+The <emphasis remap='I'>kind</emphasis> field specifies mechanism that was used to save the screen
+when the screen saver was activated, as described in
+<function>ScreenSaverQueryInfo</function>.
+</para>
+
+<para>
+The <emphasis remap='I'>time</emphasis> field indicates the server time
+when the event was generated.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Encoding">
+<title>Encoding</title>
+<para>
+Please refer to the X11 Protocol Encoding document as this document uses
+conventions established there.
+</para>
+<para>
+The name of this extension is "SCREEN-SAVER".
+</para>
+
+<sect2 id="Common_Types">
+<title>Common Types</title>
+<literallayout class="monospaced">
+SETofSCREENSAVEREVENT
+     #x00000001     ScreenSaverNotifyMask
+     #x00000002     ScreenSaverCycleMask
+</literallayout>
+</sect2>
+
+<sect2 id="Requests_2">
+<title>Requests</title>
+<literallayout class="monospaced">
+<emphasis role="bold">ScreenSaverQueryVersion</emphasis>
+1     CARD8                   screen saver opcode
+1     0                       minor opcode
+2     2                       request length
+1     CARD8                   client major version
+1     CARD8                   client minor version
+2                             unused
+->
+1     1                       Reply
+1                             unused
+2     CARD16                  sequence number
+4     0                       reply length
+1     CARD8                   server major version
+1     CARD8                   server minor version
+22                            unused
+
+<emphasis role="bold">ScreenSaverQueryInfo</emphasis>
+1     CARD8                   screen saver opcode
+1     1                       minor opcode
+2     2                       request length
+4     DRAWABLE                drawable associated with screen
+->
+1     1                       Reply
+1     CARD8                   state
+      0          Off
+      1          On
+      3          Disabled
+2     CARD16                  sequence number
+4     0                       reply length
+4     WINDOW                  saver window
+4     CARD32                  milliseconds until saver or since saver
+4     CARD32                  milliseconds since last user device input
+4     SETofSCREENSAVEREVENT   event mask
+1     CARD8                   kind
+      0          Blanked
+      1          Internal
+      2          External
+10               unused
+
+<emphasis role="bold">ScreenSaverSelectInput</emphasis>
+1     CARD8                   screen saver opcode
+1     2                       minor opcode
+2     3                       request length
+4     DRAWABLE                drawable associated with screen
+4     SETofSCREENSAVEREVENT   event mask
+
+<emphasis role="bold">ScreenSaverSetAttributes</emphasis>
+1     CARD8                   screen saver opcode
+1     3                       minor opcode
+2     6+n                     request length
+4     DRAWABLE                drawable associated with screen
+2     INT16                   x
+2     INT16                   y
+2     CARD16                  width
+2     CARD16                  height
+2     CARD16                  border-width
+1                             class
+      0          CopyFromParent
+      1          InputOutput
+      2          InputOnly
+1     CARD8                   depth
+4     VISUALID                visual
+      0          CopyFromParent
+4     BITMASK                 value-mask (has n bits set to 1)
+      encodings are the same as for core CreateWindow
+4n    LISTofVALUE             value-list
+      encodings are the same as for core CreateWindow
+
+<emphasis role="bold">ScreenSaverUnsetAttributes</emphasis>
+1     CARD8                   screen saver opcode
+1     4                       minor opcode
+2     3                       request length
+4     DRAWABLE                drawable associated with screen
+</literallayout>
+</sect2>
+
+<sect2 id="Events">
+<title>Events</title>
+
+<literallayout class="monospaced">
+<emphasis role="bold">ScreenSaverNotify</emphasis>
+1     CARD8                   code assigned by core
+1     CARD8                   state
+      0          Off
+      1          On
+      2          Cycle
+2     CARD16                  sequence number
+4     TIMESTAMP               time
+4     WINDOW                  root
+4     WINDOW                  screen saver window
+1     CARD8                   kind
+      0          Blanked
+      1          Internal
+      2          External
+1     BOOL                    forced
+14                            unused
+</literallayout>
+</sect2>
+</sect1>
+
+<sect1 id="Inter_Client_Communications_Conventions_">
+<title>Inter-Client Communications Conventions</title>
+<para>
+Screen saver clients should create at least one resource value whose
+identifier can be stored in a property named
+<emphasis role="bold">_SCREEN_SAVER_ID</emphasis>
+on the root of each screen it is managing.
+This property should have one 32-bit value corresponding to the resource
+identifier; the type of the property should indicate the type of the
+resource and should be one of the following:
+<emphasis role="bold">WINDOW</emphasis>,
+<emphasis role="bold">PIXMAP</emphasis>,
+<emphasis role="bold">CURSOR</emphasis>,
+<emphasis role="bold">FONT</emphasis>, or
+<emphasis role="bold">COLORMAP</emphasis>.
+</para>
+</sect1>
+
+<sect1 id="C_language_binding">
+<title>C language binding</title>
+
+<para>
+The C binding for this extension simply provide access to the protocol; they
+add no semantics beyond what is described above.
+</para>
+
+<para>
+The include file for this extension is
+<emphasis role="bold">&lt;X11/extensions/scrnsaver.h&gt;</emphasis>.
+</para>
+
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Bool <function>XScreenSaverQueryExtension</function></funcdef>
+    <paramdef>Display <parameter>*display</parameter></paramdef>
+    <paramdef>int <parameter>*event_base</parameter></paramdef>
+    <paramdef>int <parameter>*error_base</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+This routine returns
+<emphasis role="bold">True</emphasis>
+if the specified <emphasis remap='I'>display</emphasis> supports the
+SCREEN-SAVER extension; otherwise it returns
+<emphasis role="bold">False</emphasis>.
+If the extension is supported, the event number for
+<function>ScreenSaverNotify</function>
+events is returned in the value pointed to by
+<emphasis remap='I'>event_base</emphasis>.  Since
+no additional errors are defined by this extension, the results
+of <emphasis remap='I'>error_base</emphasis> are not defined.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XScreenSaverQueryVersion</function></funcdef>
+    <paramdef>Display <parameter>*display</parameter></paramdef>
+    <paramdef>int <parameter>*major</parameter></paramdef>
+    <paramdef>int <parameter>*minor</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+If the specified <emphasis remap='I'>display</emphasis> supports the
+extension, the version numbers of the protocol
+expected by the server are returned in
+<emphasis remap='I'>major</emphasis> and
+<emphasis remap='I'>minor</emphasis> and
+a non-zero value is returned.  Otherwise, the arguments are not
+set and 0 is returned.
+</para>
+
+<para>XScreenSaverInfo *</para>
+<para>XScreenSaverAllocInfo()</para>
+
+<para>
+This routine allocates and returns an
+<emphasis role="bold">XScreenSaverInfo</emphasis> structure
+for use in calls to <function>XScreenSaverQueryInfo</function>.
+All fields in the
+structure are initialized to zero.  If insufficient memory is available,
+NULL is returned.  The results of this routine can be released
+using <emphasis remap='I'>XFree</emphasis>.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XScreenSaverQueryInfo</function></funcdef>
+    <paramdef>Display <parameter>*display</parameter></paramdef>
+    <paramdef>Drawable <parameter>drawable</parameter></paramdef>
+    <paramdef>XScreenSaverInfo <parameter>*saver_info</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+If the specified <emphasis remap='I'>display</emphasis> supports the extension,
+information about the current state of the
+screen server is returned in <emphasis remap='I'>saver_info</emphasis> and a non-zero value is
+returned.  The <function>XScreenSaverInfo</function> structure is
+defined as follows:
+</para>
+
+<literallayout class="monospaced">
+typedef struct {
+    Window window;                /* screen saver window */
+    int state;                    /* ScreenSaver{Off,On,Disabled} */
+    int kind;                     /* ScreenSaver{Blanked,Internal,External} */
+    unsigned long til_or_since;   /* milliseconds */
+    unsigned long idle;           /* milliseconds */
+    unsigned long event_mask;     /* events */
+} XScreenSaverInfo;
+</literallayout>
+
+<para>
+See the <function>ScreenSaverQueryInfo</function> request for a
+description of the fields.  If the extension is not supported,
+<emphasis remap='I'>saver_info</emphasis> is not changed and 0
+is returned.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function>XScreenSaverSelectInput</function></funcdef>
+    <paramdef>Display <parameter>*display</parameter></paramdef>
+    <paramdef>Drawable <parameter>drawable</parameter></paramdef>
+    <paramdef>unsigned long <parameter>event_mask</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+If the specified <emphasis remap='I'>display</emphasis> supports the extension,
+this routine asks that events related to
+the screen saver be generated for this client.
+The format of the events generated is:
+</para>
+
+<literallayout class="monospaced">
+typedef struct {
+    int type;               /* of event */
+    unsigned long serial;   /* # of last request processed by server */
+    Bool send_event;        /* true if this came frome a SendEvent request */
+    Display *display;       /* Display the event was read from */
+    Window window;          /* screen saver window */
+    Window root;            /* root window of event screen */
+    int state;              /* ScreenSaver{Off,On,Cycle} */
+    int kind;               /* ScreenSaver{Blanked,Internal,External} */
+    Bool forced;            /* extents of new region */
+    Time time;              /* event timestamp */
+} XScreenSaverNotifyEvent;
+</literallayout>
+
+<para>
+See the definition of the
+<function>ScreenSaverSelectInput</function> request for descriptions
+of the allowed event masks.   <!-- xref ? -->
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function>XScreenSaverSetAttributes</function></funcdef>
+    <paramdef>Display <parameter>*dpy</parameter></paramdef>
+    <paramdef>Drawable <parameter>drawable</parameter></paramdef>
+    <paramdef>int <parameter>x</parameter></paramdef>
+    <paramdef>int <parameter>y</parameter></paramdef>
+    <paramdef>unsigned int <parameter>width</parameter></paramdef>
+    <paramdef>unsigned int <parameter>height</parameter></paramdef>
+    <paramdef>unsigned int <parameter>border_width</parameter></paramdef>
+    <paramdef>int <parameter>depth</parameter></paramdef>
+    <paramdef>unsigned int <parameter>class</parameter></paramdef>
+    <paramdef>Visual <parameter>*visual</parameter></paramdef>
+    <paramdef>unsigned long <parameter>valuemask</parameter></paramdef>
+    <paramdef>XSetWindowAttributes <parameter>*attributes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+If the specified <emphasis remap='I'>display</emphasis> supports the
+extension, this routine sets the attributes to be used
+the next time the external screen saver is activated.  See the definition
+of the <function>ScreenSaverSetAttributes</function> request for a
+description of each of the arguments.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function>XScreenSaverUnsetAttributes</function></funcdef>
+    <paramdef>Display <parameter>*display</parameter></paramdef>
+    <paramdef>Drawable <parameter>drawable</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+If the specified <emphasis remap='I'>display</emphasis> supports the
+extension, this routine instructs the server to discard
+any previous screen saver window attributes set by this client.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XScreenSaverRegister</function></funcdef>
+    <paramdef>Display <parameter>*display</parameter></paramdef>
+    <paramdef>int <parameter>screen</parameter></paramdef>
+    <paramdef>XID <parameter>xid</parameter></paramdef>
+    <paramdef>Atom <parameter>type</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+This routine stores the given <emphasis remap='I'>XID</emphasis> in the
+<emphasis role="bold">_SCREEN_SAVER_ID</emphasis> property (of the given
+<emphasis remap='I'>type</emphasis>) on the root window of the specified
+<emphasis remap='I'>screen</emphasis>.  It returns zero if an error
+is encountered and the property is not changed, otherwise it returns
+non-zero.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XScreenSaverUnregister</function></funcdef>
+    <paramdef>Display <parameter>*display</parameter></paramdef>
+    <paramdef>int <parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+This routine removes any <function>_SCREEN_SAVER_ID</function> from the
+root window of the specified <emphasis remap='I'>screen</emphasis>.
+It returns zero if an error is encountered and the property is changed,
+otherwise it returns non-zero.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XScreenSaverGetRegistered</function></funcdef>
+    <paramdef>Display <parameter>*display</parameter></paramdef>
+    <paramdef>int <parameter>screen</parameter></paramdef>
+    <paramdef>XID <parameter>*xid</parameter></paramdef>
+    <paramdef>ATOM <parameter>*type</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<para>
+This routine returns the
+<emphasis remap='I'>XID</emphasis> and
+<emphasis remap='I'>type</emphasis> stored in the
+<emphasis role="bold">_SCREEN_SAVER_ID</emphasis> property on the
+root window of the specified <emphasis remap='I'>screen</emphasis>.
+It returns zero if an error
+is encountered or if the property does not exist or is not of the correct
+format; otherwise it returns non-zero.
+</para>
+
+</sect1>
+</chapter>
+</book>