Add libXcomposite man page (converted from protocol specs)

Translate protocol specs + header into library/API documentation in
Docbook/XML format

Convert XML -> nroff/man at dist time so that only maintainers and
developers building from git need xmlto installed.

5 files changed, 484 insertions, 1 deletions

diff --git a/Makefile.am b/Makefile.am
index 8f18770..bb67cf6 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -21,7 +21,7 @@
 #  TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 #  PERFORMANCE OF THIS SOFTWARE.
 
-SUBDIRS = src
+SUBDIRS = src man
 
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = xcomposite.pc
diff --git a/configure.ac b/configure.ac
index bedf4d2..62100d4 100644
--- a/configure.ac
+++ b/configure.ac
@@ -44,6 +44,10 @@ AM_CONFIG_HEADER(config.h)
 AC_PROG_CC
 AC_PROG_LIBTOOL
 
+AC_ARG_VAR([XMLTO], [Path to xmlto command])
+AC_PATH_PROG([XMLTO], [xmlto])
+AM_CONDITIONAL([HAVE_XMLTO], [test "x$XMLTO" != "x"])
+
 # Check compositeext configuration, strip extra digits from package version to
 # find the required protocol version
 
@@ -56,9 +60,11 @@ PKG_CHECK_MODULES(XCOMPOSITE, [compositeproto >= $COMPOSITEEXT_VERSION] x11 xfix
 AC_SUBST(XCOMPOSITE_CFLAGS)
 AC_SUBST(XCOMPOSITE_LIBS)
 
+XORG_MANPAGE_SECTIONS
 XORG_RELEASE_VERSION
 
 AC_OUTPUT([Makefile
 	   src/Makefile
+	   man/Makefile
            xcomposite.pc])
 
diff --git a/man/.gitignore b/man/.gitignore
new file mode 100644
index 0000000..2dcc75c
--- /dev/null
+++ b/man/.gitignore
@@ -0,0 +1,6 @@
+shadows.DONE
+*.3
+*~
+Xcomposite.man
+Makefile
+Makefile.in
diff --git a/man/Makefile.am b/man/Makefile.am
new file mode 100644
index 0000000..0cd6d0a
--- /dev/null
+++ b/man/Makefile.am
@@ -0,0 +1,78 @@
+libmandir = $(LIB_MAN_DIR)
+
+LIB_MAN_DIR_SUFFIX = $(LIB_MAN_DIR:@mandir@/man%=%)
+
+libman_xml = Xcomposite.xml
+
+libman_PRE = $(libman_xml:xml=man)
+
+Xcomposite_man_aliases = 			\
+	XCompositeQueryExtension		\
+	XCompositeQueryVersion			\
+	XCompositeVersion			\
+	XCompositeRedirectWindow		\
+	XCompositeRedirectSubwindows		\
+	XCompositeUnredirectWindow		\
+	XCompositeUnredirectSubwindows		\
+	XCompositeCreateRegionFromBorderClip	\
+	XCompositeNameWindowPixmap		\
+	XCompositeGetOverlayWindow		\
+	XCompositeReleaseOverlayWindow
+
+libman_DATA = $(libman_PRE:man=@LIB_MAN_SUFFIX@) \
+	      $(Xcomposite_man_aliases:=.@LIB_MAN_SUFFIX@)
+
+EXTRA_DIST  = $(libman_PRE) $(libman_xml)
+
+CLEANFILES  = $(libman_DATA)
+
+MAINTAINERCLEANFILES = $(libman_PRE)
+
+# Generate man page shadow files (Replaces InstallManPageAliases from Imake)
+
+BUILT_SOURCES = shadows.DONE
+
+shadows.DONE:
+	-rm -f $(Xcomposite_man_aliases:=.@LIB_MAN_SUFFIX@)
+	(for i in $(Xcomposite_man_aliases:=.@LIB_MAN_SUFFIX@) ; do \
+	echo .so man$(LIB_MAN_DIR_SUFFIX)/Xcomposite.$(LIB_MAN_SUFFIX) > $$i; \
+	done)
+	touch shadows.DONE
+
+CLEANFILES += shadows.DONE
+
+# Substitute system-specific values in man pages
+
+XORGRELSTRING = @PACKAGE_STRING@
+  XORGMANNAME = X Version 11
+
+MAN_SUBSTS = \
+	-e 's|"__vendorversion__"|"$(XORGRELSTRING)" "$(XORGMANNAME)"|' \
+	-e 's|__xorgversion__|"$(XORGRELSTRING)" "$(XORGMANNAME)"|' \
+	-e 's|__xservername__|Xorg|g' \
+	-e 's|__xconfigfile__|xorg.conf|g' \
+	-e 's|__projectroot__|$(prefix)|g' \
+	-e 's|__apploaddir__|$(appdefaultdir)|' \
+	-e 's|__appmansuffix__|$(APP_MAN_SUFFIX)|g' \
+	-e 's|__libmansuffix__|$(LIB_MAN_SUFFIX)|g' \
+	-e 's|__adminmansuffix__|$(ADMIN_MAN_SUFFIX)|g' \
+	-e 's|__miscmansuffix__|$(MISC_MAN_SUFFIX)|g' \
+	-e 's|__filemansuffix__|$(FILE_MAN_SUFFIX)|g'
+
+SUFFIXES = .$(LIB_MAN_SUFFIX) .man
+
+.man.$(LIB_MAN_SUFFIX):
+	sed $(MAN_SUBSTS) < $< > $@
+
+# Generate nroff sources from DocBook/xml
+
+dist-hook: $(libman_PRE)
+
+if HAVE_XMLTO
+SUFFIXES += .xml
+
+.xml.man:
+	$(XMLTO) man $< && mv $*.__libmansuffix__ $@
+
+
+endif HAVE_XMLTO
diff --git a/man/Xcomposite.xml b/man/Xcomposite.xml
new file mode 100644
index 0000000..f849f6a
--- /dev/null
+++ b/man/Xcomposite.xml
@@ -0,0 +1,393 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+            "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" >
+<reference>
+<!--
+ Based on proto/compositeproto/compositeproto.txt
+
+ Conversion to DocBook/XML API documentation is:
+
+ Copyright 2007 Sun Microsystems, Inc.  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, and/or sell copies of the Software, and to permit persons
+ to whom the Software is furnished to do so, provided that the above
+ copyright notice(s) and this permission notice appear in all copies of
+ the Software and that both the above copyright notice(s) and this
+ permission notice appear in supporting documentation.
+ 
+ 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
+ OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+ HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
+ INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
+ FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+ NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
+ WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ 
+ Except as contained in this notice, the name of a copyright holder
+ shall not be used in advertising or otherwise to promote the sale, use
+ or other dealings in this Software without prior written authorization
+ of the copyright holder.
+
+ -->
+<title>X Composite Extension Library</title>
+
+<refentry id='Xcomposite.man'>
+ <refentryinfo>
+  <productname>__vendorversion__</productname>
+  <pubdate>23 April 2007</pubdate>
+  <authorgroup>
+   <author><firstname>Keith</firstname><surname>Packard</surname>
+	   <contrib>Extension specification and implementation</contrib>
+	   <email>keithp@keithp.com</email>
+   </author>
+  </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+  <refentrytitle>Xcomposite</refentrytitle>
+  <manvolnum>__libmansuffix__</manvolnum>
+ </refmeta>
+ <refnamediv>
+  <refname>Xcomposite</refname>
+  <refpurpose>X Composite Extension library</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv><funcsynopsis>
+  <funcsynopsisinfo>#include &lt;X11/extensions/Xcomposite.h&gt;</funcsynopsisinfo>
+  <funcprototype>
+   <funcdef>Bool <function>XCompositeQueryExtension</function></funcdef>
+   <paramdef><type>Display *</type><parameter>dpy</parameter></paramdef>
+   <paramdef>int *<parameter>event_basep</parameter></paramdef>
+   <paramdef>int *<parameter>error_basep</parameter></paramdef>
+  </funcprototype>
+  <funcprototype>
+   <funcdef>Status <function>XCompositeQueryVersion</function></funcdef>
+   <paramdef>Display *<parameter>dpy</parameter></paramdef>
+   <paramdef>int *<parameter>major_versionp</parameter></paramdef>
+   <paramdef>int *<parameter>minor_versionp</parameter></paramdef>
+  </funcprototype>
+  <funcprototype>
+   <funcdef>int <function>XCompositeVersion</function></funcdef>
+   <void />
+  </funcprototype>
+  <funcprototype>
+   <funcdef>void <function>XCompositeRedirectWindow</function></funcdef>
+   <paramdef>Display *<parameter>dpy</parameter></paramdef>
+   <paramdef>Window <parameter>window</parameter></paramdef>
+   <paramdef>int <parameter>update</parameter></paramdef>
+  </funcprototype>
+  <funcprototype>
+   <funcdef>void <function>XCompositeRedirectSubwindows</function></funcdef>
+   <paramdef>Display *<parameter>dpy</parameter></paramdef>
+   <paramdef>Window <parameter>window</parameter></paramdef>
+   <paramdef>int <parameter>update</parameter></paramdef>
+  </funcprototype>
+  <funcprototype>
+   <funcdef>void <function>XCompositeUnredirectWindow</function></funcdef>
+   <paramdef>Display *<parameter>dpy</parameter></paramdef>
+   <paramdef>Window <parameter>window</parameter></paramdef>
+   <paramdef>int <parameter>update</parameter></paramdef>
+  </funcprototype>
+  <funcprototype>
+   <funcdef>void <function>XCompositeUnredirectSubwindows</function></funcdef>
+   <paramdef>Display *<parameter>dpy</parameter></paramdef>
+   <paramdef>Window <parameter>window</parameter></paramdef>
+   <paramdef>int <parameter>update</parameter></paramdef>
+  </funcprototype>
+  <funcprototype>
+   <funcdef>XserverRegion <function>XCompositeCreateRegionFromBorderClip</function></funcdef>
+   <paramdef>Display *<parameter>dpy</parameter></paramdef>
+   <paramdef>Window <parameter>window</parameter></paramdef>
+  </funcprototype>
+  <funcprototype>
+   <funcdef>Pixmap <function>XCompositeNameWindowPixmap</function></funcdef>
+   <paramdef>Display *<parameter>dpy</parameter></paramdef>
+   <paramdef>Window <parameter>window</parameter></paramdef>
+  </funcprototype>
+  <funcprototype>
+   <funcdef>Window <function>XCompositeGetOverlayWindow</function></funcdef>
+   <paramdef>Display *<parameter>dpy</parameter></paramdef>
+   <paramdef>Window <parameter>window</parameter></paramdef>
+  </funcprototype>
+  <funcprototype>
+   <funcdef>void <function>XCompositeReleaseOverlayWindow</function></funcdef>
+   <paramdef>Display *<parameter>dpy</parameter></paramdef>
+   <paramdef>Window <parameter>window</parameter></paramdef>
+  </funcprototype>
+ </funcsynopsis></refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para>
+The composite extension provides several related mechanisms:
+ <variablelist>
+  <varlistentry>
+   <term>Per-hierarchy storage</term>
+   <listitem><para>
+	The rendering of an entire hierarchy of windows
+ 	is redirected to off-screen storage. The pixels of that hierarchy
+	are available whenever it is viewable. Storage is automatically
+	reallocated when the top level window changes size. Contents beyond
+	the geometry of the top window are not preserved.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>Automatic shadow update</term>
+   <listitem><para>
+ 	When a hierarchy is rendered off-screen,
+ 	the X server provides an automatic mechanism for presenting those
+	contents within the parent window. The implementation is free to
+	make this update lag behind actual rendering operations by an
+	unspecified amount of time. This automatic update mechanism may
+	be disabled so that the parent window contents can be completely
+	determined by an external application.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>Composite Overlay Window</term>
+   <listitem><para>
+	Version 0.3 of the protocol adds the Composite Overlay Window, which
+	provides compositing managers with a surface on which to draw without
+	interference. This window is always above normal windows and is always
+	below the screen saver window. It is an InputOutput window whose width
+	and height are the screen dimensions. Its visual is the root visual
+	and its border width is zero.  Attempts to redirect it using the
+	composite extension are ignored.  This window does not appear in the
+	reply of the QueryTree request. It is also an override redirect window.
+	These last two features make it invisible to window managers and other
+	X11 clients. The only way to access the XID of this window is via the
+	CompositeGetOverlayWindow request. Initially, the Composite Overlay
+	Window is unmapped.
+   </para></listitem>
+  </varlistentry>
+ </variablelist>
+</para>
+<para>
+Per-hierarchy storage may be created for individual windows or for all
+children of a window. Manual shadow update may be selected by only a single
+application for each window; manual update may also be selected on a
+per-window basis or for each child of a window. Detecting when to update
+may be done with the Damage extension.
+</para>
+<para>
+The off-screen storage includes the window contents, its borders and the
+contents of all descendants.
+</para>
+</refsect1>
+<refsect1><title>Arguments</title>
+<para>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>display</parameter></term>
+   <listitem><para>
+    Pointer to the <type>Display</type> structure returned from 
+    <function>XOpenDisplay</function> for the connection to the X server.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>event_basep</parameter></term>
+   <listitem><para>
+    Pointer to integer where the base value for Composite Extension events
+    will be stored.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>error_basep</parameter></term>
+   <listitem><para>
+    Pointer to integer where the base value for Composite Extension errors
+    will be stored.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>major_versionp</parameter></term>
+   <listitem><para>
+    Pointer to integer where the major version of the Composite Extension
+    supported by the X server will be stored.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>minor_versionp</parameter></term>
+   <listitem><para>
+    Pointer to integer where the minor version of the Composite Extension
+    supported by the X server will be stored.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>window</parameter></term>
+   <listitem><para>
+    Specifies the window ID to operate on.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>update</parameter></term>
+   <listitem><para>
+    Specifies the mode for updating the window contents.   Must be either
+    <constant>CompositeRedirectAutomatic</constant> or
+    <constant>CompositeRedirectManual</constant>.
+   </para></listitem>
+  </varlistentry>
+ </variablelist>
+</para></refsect1>
+<refsect1><title>Functions</title>
+<para>
+ <variablelist>
+  <varlistentry>
+   <term><function>XCompositeQueryExtension</function></term>
+   <listitem><para>
+    <function>XCompositeQueryExtension</function> determines if the 
+    Composite Extension is available on the given display.   It returns 
+    <constant>True</constant> if the extension is supported, otherwise 
+    <constant>False</constant>.   If the extension is present, the base 
+    values for events and errors are returned, and can be used to 
+    decode incoming event and error values.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><function>XCompositeQueryVersion</function></term>
+   <listitem><para>
+    <function>XCompositeQueryVersion</function> determines if the X Server
+    supports a version of the X Composite Extension which is compatible 
+    with the client library. A non-zero Status is returned if a compatible
+    version of the extension is supported, otherwise a zero Status is returned.
+    If the extension is supported, the major and minor version numbers are 
+    returned to indicate the level of Composite Extension support.
+    No other XComposite functions (except XCompositeQueryExtension) may be 
+    called before this function.  If a client violates this  rule, the
+    effects of all subsequent XComposite calls that it makes are undefined.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><function>XCompositeVersion</function></term>
+   <listitem><para>
+    <function>XCompositeVersion</function> returns the version of the 
+    X Composite library.   The version number is encoded as:
+    <blockquote><para><code language="C">
+     (major * 10000) + (minor * 100) + revision
+    </code></para></blockquote>
+   </para>
+   <para>
+    For example, version 1.4.6 would be encoded as the integer 10406.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><function>XCompositeRedirectWindow</function></term>
+   <listitem><para>
+	<function>XCompositeRedirectWindow</function> requests the X server 
+	to direct the hierarchy starting at <parameter>window</parameter> to 
+	off-screen storage. 
+        The <parameter>update</parameter> argument specifies whether 
+        the contents are mirrored to the parent window automatically or not.
+        Only one client at a time may specify an update type of 
+	<constant>CompositeRedirectManual</constant>, another attempt will 
+	result in a <errorname>BadAccess</errorname> error.  When all clients 
+        enabling redirection terminate, the redirection will automatically be
+        disabled.
+   </para><para>
+	The root window may not be redirected. Doing so results in a 
+	<errorname>BadMatch</errorname>	error.  Specifying an invalid
+        window id will result in a <errorname>BadWindow</errorname> error.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><function>XCompositeRedirectSubwindows</function></term>
+   <listitem><para>
+	<function>XCompositeRedirectSubwindows</function> requests the X 
+	server to redirect hierarchies starting at all current and future 
+	children of <parameter>window</parameter> as in 
+	<function>XCompositeRedirectWindow</function>. 
+	If <parameter>update</parameter> is 
+	<constant>CompositeRedirectManual</constant>, then painting of the 
+	window background during window manipulation and ClearArea requests 
+	is inhibited.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><function>XCompositeUnredirectWindow</function></term>
+   <listitem><para>
+	<function>XCompositeUnredirectWindow</function> requests the X 
+	server to terminate redirection of <parameter>window</parameter>.
+	If the specified window was not selected for redirection by the
+	current client, a <errorname>BadValue</errorname> error results.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><function>XCompositeUnredirectSubwindows</function></term>
+   <listitem><para>
+	<function>XCompositeUnredirectWindow</function> requests the X 
+	server to terminate redirection of all children of
+	<parameter>window</parameter>.
+	If the specified window was not selected for sub-redirection by the
+	current client, a <errorname>BadValue</errorname> error results.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><function>XCompositeCreateRegionFromBorderClip</function></term>
+   <listitem><para>
+	<function>XCompositeCreateRegionFromBorderClip</function>
+	creates a region containing the "usual" border clip
+	value; that is the area of the window clipped against siblings and
+	the parent. This region can be used to restrict rendering to
+	suitable areas while updating only a single window. The region
+	is copied at the moment the request is executed; future changes
+	to the window hierarchy will not be reflected in this region.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><function>XCompositeNameWindowPixmap</function></term>
+   <listitem><para>
+	<function>XCompositeNameWindowPixmap</function> creates and returns
+	a pixmap id that serves as a reference to the off-screen storage for
+	<parameter>window</parameter>. This pixmap will remain allocated 
+	until freed, even if the window is unmapped, reconfigured or 
+	destroyed. However, the window will get a new pixmap allocated each 
+	time it is mapped or resized, so this function will need to be 
+	reinvoked for the client to continue to refer to the storage holding
+	the current window contents. Generates a 
+	<errorname>BadMatch</errorname>	error if <parameter>window</parameter>
+	is not redirected or is not visible.
+   </para><para>
+        The X server must support at least version 0.2 of the Composite
+	Extension for <function>XCompositeNameWindowPixmap</function>.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><function>XCompositeGetOverlayWindow</function></term>
+   <listitem><para>
+    <function>XCompositeGetOverlayWindow</function> returns the window ID
+    of the Composite Overlay Window for 
+    the screen specified by the argument <parameter>window</parameter>. 
+    This function notifies the X server that the client wishes to use 
+    the Composite Overlay Window of this screen. If this 
+    Composite Overlay Window has not yet been mapped, it is mapped by this 
+    request.
+   </para><para>
+    The Composite Overlay Window for a particular screen will be 
+    unmapped when all clients who have called this function have 
+    either called <function>XCompositeReleaseOverlayWindow</function>
+    for that screen, or terminated their connection to the X server.
+   </para><para>
+    The X server must support at least version 0.3 of the Composite
+    Extension for <function>XCompositeGetOverlayWindow</function>.
+   </para></listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><function>XCompositeReleaseOverlayWindow</function></term>
+   <listitem><para>
+    This request specifies that the client is no longer using the 
+    Composite Overlay Window on the screen specified by the 
+    argument <parameter>window</parameter>. A screen&apos;s Composite 
+    Overlay Window is unmapped when there are no longer any clients using it.
+   </para><para>
+    The X server must support at least version 0.3 of the Composite
+    Extension for <function>XCompositeReleaseOverlayWindow</function>.
+   </para></listitem>
+  </varlistentry>
+ </variablelist>
+</para>
+</refsect1>
+</refentry>
+</reference>