Add man pages for XTest*() functions

Converted xorg-docs/Xext/xtestlib.ms to man page formatting

4 files changed, 405 insertions, 2 deletions

diff --git a/Makefile.am b/Makefile.am
index 20760d4..ec888f5 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -19,7 +19,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 = xtst.pc
diff --git a/configure.ac b/configure.ac
index 554ab13..e7877bc 100644
--- a/configure.ac
+++ b/configure.ac
@@ -43,9 +43,11 @@ LINT_FLAGS="${LINT_FLAGS} ${XTST_CFLAGS}"
 
 AC_SUBST(XTST_CFLAGS)
 AC_SUBST(XTST_LIBS)
-		  
+
+XORG_MANPAGE_SECTIONS
 XORG_RELEASE_VERSION
 
 AC_OUTPUT([Makefile
+	   man/Makefile
 	   src/Makefile
            xtst.pc])
diff --git a/man/Makefile.am b/man/Makefile.am
new file mode 100644
index 0000000..274d706
--- /dev/null
+++ b/man/Makefile.am
@@ -0,0 +1,81 @@
+#
+# Copyright 2007 Sun Microsystems, Inc.  All rights reserved.
+# 
+# Permission to use, copy, modify, distribute, and sell this software and its
+# documentation for any purpose is hereby granted without fee, provided that
+# the above copyright notice appear in all copies and that both that
+# copyright notice and this permission notice appear in supporting
+# documentation.
+# 
+# The above copyright notice and this permission notice 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 OPEN GROUP 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.
+# 
+# Except as contained in this notice, the name of the copyright holders shall
+# not be used in advertising or otherwise to promote the sale, use or
+# other dealings in this Software without prior written authorization
+# from the copyright holders.
+# 
+
+libmandir = $(LIB_MAN_DIR)
+
+LIB_MAN_DIR_SUFFIX = $(LIB_MAN_DIR:@mandir@/man%=%)
+
+libman_PRE = XTest.man
+
+BUILT_SOURCES = shadows.DONE
+
+EXTRA_DIST = $(libman_PRE)
+
+CLEANFILES = $(libman_DATA) $(BUILT_SOURCES)
+
+libman_DATA = $(libman_PRE:man=@LIB_MAN_SUFFIX@) \
+	      $(XTest_shadows:=.@LIB_MAN_SUFFIX@)
+
+SED = sed
+
+# Strings to replace in man pages
+XORGRELSTRING = @PACKAGE_STRING@
+  XORGMANNAME = X Version 11
+
+MAN_SUBSTS = \
+	-e 's/__xorgversion__/"$(XORGRELSTRING)" "$(XORGMANNAME)"/' \
+	-e 's/__xservername__/Xorg/g' \
+	-e 's/__xconfigfile__/xorg.conf/g' \
+	-e 's/__appmansuffix__/$(APP_MAN_SUFFIX)/g' \
+	-e 's/__libmansuffix__/$(LIB_MAN_SUFFIX)/g' \
+	-e 's/__filemansuffix__/$(FILE_MAN_SUFFIX)/g'
+
+SUFFIXES = .$(LIB_MAN_SUFFIX) .man
+
+.man.$(LIB_MAN_SUFFIX):
+	sed $(MAN_SUBSTS) < $< > $@
+
+# Generate man page shadow files (Replaces InstallManPageAliases from Imake)
+
+XTest_shadows =	\
+	XTestQueryExtension                 \
+	XTestCompareCursorWithWindow        \
+	XTestCompareCurrentCursorWithWindow \
+	XTestFakeKeyEvent                   \
+	XTestFakeButtonEvent                \
+	XTestFakeMotionEvent                \
+	XTestFakeRelativeMotionEvent        \
+	XTestGrabControl                    \
+	XTestSetGContextOfGC                \
+	XTestSetVisualIDOfVisual            \
+	XTestDiscard
+
+shadows.DONE:
+	-rm -f $(XTest_shadows:=.@LIB_MAN_SUFFIX@)
+	(for i in $(XTest_shadows:=.@LIB_MAN_SUFFIX@) ; do \
+	 echo .so man$(LIB_MAN_DIR_SUFFIX)/XTest.$(LIB_MAN_SUFFIX) > $$i; \
+	 done)
+
diff --git a/man/XTest.man b/man/XTest.man
new file mode 100644
index 0000000..be43f8c
--- /dev/null
+++ b/man/XTest.man
@@ -0,0 +1,320 @@
+.\" Copyright \(co 1992 by UniSoft Group Ltd.
+.\" 
+.\" 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.  
+.\" UniSoft makes 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.
+.\" 
+.\" Copyright \(co 1992, 1994 X Consortium
+.\" 
+.\" 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 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 X CONSORTIUM 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.
+.\" 
+.\" Except as contained in this notice, the name of the X Consortium shall not
+.\" be used in advertising or otherwise to promote the sale, use or other 
+.\" dealings in this Software without prior written authorization from the 
+.\" X Consortium.
+.\"
+.\" edited for DP edits and code consistency w/ core protocol/xlib 4/2/96
+.\" Converted from xorg-docs/Xext/xtestlib.ms 6/6/07
+.\" $Xorg: xtestlib.ms,v 1.3 2000/08/17 19:42:37 cpqbld Exp $
+.TH XTest __libmansuffix__ __xorgversion__ "XTST FUNCTIONS"
+.SH NAME
+XTestQueryExtension, XTestCompareCursorWithWindow, XTestCompareCurrentCursorWithWindow, XTestFakeKeyEvent, XTestFakeButtonEvent, XTestFakeMotionEvent, XTestFakeRelativeMotionEvent, XTestGrabControl, XTestSetGContextOfGC, XTestSetVisualIDOfVisual, XTestDiscard \- XTest extension functions
+.SH SYNOPSIS
+.HP
+\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lXtst \fR [ \fIlibrary\fR ... ]
+.HP
+.B #include <X11/extensions/XTest.h>
+.HP
+Bool
+XTestQueryExtension(\fIdisplay\fP\^, \fIevent_base\fP\^, \fIerror_base\fP\^, \fImajor_version\fP\^, \fIminor_version\fP\^)
+.IP
+ Display *\fIdisplay\fP\^;
+ int *\fIevent_base\fP\^; /* RETURN */
+ int *\fIerror_base\fP\^; /* RETURN */
+ int *\fImajor_version\fP\^; /* RETURN */
+ int *\fIminor_version\fP\^; /* RETURN */
+.HP
+Bool
+XTestCompareCursorWithWindow(\fIdisplay\fP\^, \fIwindow\fP\^, \fIcursor\fP\^)
+.IP
+ Display *\fIdisplay\fP\^;
+ Window \fIwindow\fP\^;
+ Cursor \fIcursor\fP\^;
+.HP
+Bool
+XTestCompareCurrentCursorWithWindow(\fIdisplay\fP\^, \fIwindow\fP\^)
+.IP
+ Display *\fIdisplay\fP\^;
+ Window \fIwindow\fP\^;
+.HP
+int
+XTestFakeKeyEvent(\fIdisplay\fP\^, \fIkeycode\fP\^, \fIis_press\fP\^, \fIdelay\fP\^)
+.IP
+ Display *\fIdisplay\fP\^;
+ unsigned int \fIkeycode\fP\^;
+ Bool \fIis_press\fP\^;
+ unsigned long \fIdelay\fP\^;
+.HP
+int
+XTestFakeButtonEvent(\fIdisplay\fP\^, \fIbutton\fP\^, \fIis_press\fP\^, \fIdelay\fP\^)
+.IP
+ Display *\fIdisplay\fP\^;
+ unsigned int \fIbutton\fP\^;
+ Bool \fIis_press\fP\^;
+ unsigned long \fIdelay\fP\^;
+.HP
+int
+XTestFakeMotionEvent(\fIdisplay\fP\^, \fIscreen_number\fP\^, \fIx\fP\^, \
+\fIy\fP\^, \fIdelay\fP\^)
+.IP
+ Display *\fIdisplay\fP\^;
+ int \fIscreen_number\fP\^;
+ int \fIx\fP\^, \fIy\fP\^;
+ unsigned long \fIdelay\fP\^;
+.HP
+int
+XTestFakeRelativeMotionEvent(\fIdisplay\fP\^, \fIscreen_number\fP\^, \
+\fIx\fP\^, \fIy\fP\^, \fIdelay\fP\^)
+.IP
+ Display *\fIdisplay\fP\^;
+ int \fIscreen_number\fP\^;
+ int \fIx\fP\^, \fIy\fP\^;
+ unsigned long \fIdelay\fP\^;
+.HP
+int
+XTestGrabControl(\fIdisplay\fP\^, \fIimpervious\fP\^)
+.IP
+ Display *\fIdisplay\fP\^;
+ Bool \fIimpervious\fP\^;
+.HP
+void
+XTestSetGContextOfGC(\fIgc\fP\^, \fIgid\fP\^)
+.IP
+ GC \fIgc\fP\^;
+ GContext \fIgid\fP\^;
+.HP
+void
+XTestSetVisualIDOfVisual(\fIvisual\fP\^, \fIvisualid\fP\^)
+.IP
+ Visual *\fIvisual\fP\^;
+ VisualID \fIvisualid\fP\^;
+.HP
+Status 
+XTestDiscard(\fIdisplay\fP\^)
+.IP
+ Display *\fIdisplay\fP\^;
+.SH DESCRIPTION
+.LP
+This extension is a minimal set of client and server extensions
+required to completely test the X11 server with no user intervention.
+This extension is not intended to support general journaling and
+playback of user actions. 
+.LP
+The functions provided by this extension fall into two groups:
+.IP "\fBClient Operations\fP" .5i
+These routines manipulate otherwise hidden client-side behavior.  The
+actual implementation will depend on the details of the actual language
+binding and what degree of request buffering, GContext caching, and so on, is
+provided.  In the C binding, routines are provided
+to access the internals of two opaque data structures 
+.BR \*- GC s
+and
+.BR Visual s\*-
+and to discard any requests pending within the
+output buffer of a connection.  The exact details can be expected to differ for
+other language bindings.
+.IP "\fBServer Requests\fP" .5i
+The first of these requests is similar to that provided in most
+extensions: it allows a client to specify a major and minor version
+number to the server and for the server to respond with major and minor
+versions of its own.  The remaining two requests allow the following:
+.RS
+.IP \(bu 5
+Access to an otherwise \*Qwrite-only\*U server resource: the cursor
+associated with a given window
+.IP \(bu 5
+Perhaps most importantly, limited synthesis of input device events,
+almost as if a cooperative user had moved the pointing device
+or pressed a key or button.
+.RE
+.LP
+All XTEST extension functions and procedures, and all manifest
+constants and macros, will start with the string \*QXTest\*U.
+All operations are classified as
+server/client (Server) or client-only (Client).
+.FD 0
+.FN
+.LP
+.B XTestQueryExtension
+returns
+.B True
+if the specified display supports the XTEST extension, else
+.BR False .
+If the extension is supported, *event_base would be set to the event number for
+the first event for this extension and
+*error_base would be set to the error number for the first error for
+this extension.  As no errors or events are defined for this version of the extension,
+the values returned here are not defined (nor useful).
+If the extension is supported, *major_version and *minor_version are set to
+the major and minor version numbers of the extension supported by the
+display.  Otherwise, none of the arguments are set.
+.sp
+.LP
+If the extension is supported,
+.BR XTestCompareCursorWithWindow
+performs a comparison of the cursor
+whose ID is specified by cursor (which may be
+.BR None )
+with the cursor of the window specified by window returning
+.BR True
+if they are the same and
+.BR False
+otherwise. 
+If the extension is not supported, then the request is ignored and
+zero is returned.
+.sp
+.LP
+If the extension is supported, 
+.BR XTestCompareCurrentCursorWithWindow
+performs a comparison of the current cursor
+with the cursor of the specified window returning
+.BR True
+if they are the same and
+.BR False
+otherwise.
+If the extension is not supported, then the request is ignored and
+zero is returned.
+.sp
+.LP
+If the extension is supported,
+.BR XTestFakeKeyEvent
+requests the server to simulate either a
+.BR KeyPress
+(if is_press is
+.BR True )
+or a
+.BR KeyRelease
+(if is_press is
+.BR False )
+of the key with the specified keycode;
+otherwise, the request is ignored.
+.LP
+If the extension is supported,
+the simulated event will not be processed until delay milliseconds
+after the request is received (if delay is
+.BR CurrentTime ,
+then this is interpreted as no delay at all).  No other requests from
+this client will be processed until this delay, if any, has expired
+and subsequent processing of the simulated event has been completed.
+.sp
+.LP
+If the extension is supported,
+.BR XTestFakeButtonEvent
+requests the server to simulate either
+a
+.BR ButtonPress
+(if is_press is
+.BR True )
+or a
+.BR ButtonRelease
+(if is_press is
+.BR False )
+of the logical button numbered by the specified button;
+otherwise, the request is ignored.
+.LP
+If the extension is supported,
+the simulated event will not be processed until delay milliseconds
+after the request is received (if delay is
+.BR CurrentTime ,
+then this is interpreted as no delay at all).  No other requests from
+this client will be processed until this delay, if any, has expired
+and subsequent processing of the simulated event has been completed.
+.sp
+.LP
+If the extension is supported,
+.BR XTestFakeMotionEvent
+requests the server to simulate
+a movement of the pointer to the specified position (x, y) on the
+root window of screen_number;
+otherwise, the request is ignored.  If screen_number is -1, the
+current screen (that the pointer is on) is used.
+.LP
+If the extension is supported,
+the simulated event will not be processed until delay milliseconds
+after the request is received (if delay is
+.BR CurrentTime ,
+then this is interpreted as no delay at all).  No other requests from
+this client will be processed until this delay, if any, has expired
+and subsequent processing of the simulated event has been completed.
+.sp
+.LP
+If the extension is supported,
+.BR XTestFakeRelativeMotionEvent
+requests the server to simulate
+a movement of the pointer by the specified offsets (x, y) relative
+to the current pointer position on screen_number;
+otherwise, the request is ignored.  If screen_number is -1, the
+current screen (that the pointer is on) is used.
+.LP
+If the extension is supported,
+the simulated event will not be processed until delay milliseconds
+after the request is received (if delay is
+.BR CurrentTime ,
+then this is interpreted as no delay at all).  No other requests from
+this client will be processed until this delay, if any, has expired
+and subsequent processing of the simulated event has been completed.
+.sp
+
+.LP
+If impervious is
+.BR True ,
+then the executing client becomes impervious to server grabs.
+If impervious is
+.BR False ,
+then the executing client returns to the normal state of being
+susceptible to server grabs.
+.sp
+.LP
+.BR XTestSetGContextOfGC
+sets the GContext within the opaque datatype referenced by gc to
+be that specified by gid.
+.sp
+.LP
+.BR XTestSetVisualIDOfVisual
+sets the VisualID within the opaque datatype referenced by visual to
+be that specified by visualid.
+.sp
+.LP
+.BR XTestDiscard
+discards any requests within the output buffer for the specified display.
+It returns
+.BR True
+if any requests were discarded; otherwise, it returns
+.BR False .
+
+.SH RETURN VALUES
+All routines that have return type Status will return nonzero for
+\*Qsuccess\*U and zero for \*Qfailure.\*U  Even if the XTEST extension is
+supported, the server may withdraw such facilities arbitrarily; in which case
+they will subsequently return zero.
+
+