From 982ac918afe6a1c02d5cf735d7b6c56443a048cc Mon Sep 17 00:00:00 2001 From: marha Date: Fri, 7 Feb 2014 23:28:38 +0100 Subject: xkbcomp xkeyboard-config libxcb libxtrans fontconfig libX11 libxcb mesa xserver git update 7 Feb 2014 Update to openssl1.0.1f xserver commit 83e38eb73fd8c852513aac2da2975b4c01070ec2 libxcb commit d7eb0bdf3b5b11ee9f40ee5e73df8fc0bdfa59f3 xkeyboard-config commit 7596672b96315465df8d8d691e3a567a52f70743 libX11 commit aacf95dacc7c598e7297894580d4d655593813b2 xkbcomp commit 31b90ee4ffc774e0da540277907fc5540c0b012c libxtrans commit 3f0de269abe59353acbd7a5587d68ce0da91db67 fontconfig commit e310d2fac2d874d5aa76c609df70cc7b871c0b6d mesa commit dd2229d4c68ed78a50104637aef904f8ab6d7dd3 --- libxcb/Makefile.am | 2 +- libxcb/configure.ac | 163 ++++++++++++++++++++--------------------- libxcb/doc/Makefile.am | 6 +- libxcb/m4/xcb.m4 | 89 ----------------------- libxcb/man/.gitignore | 1 + libxcb/man/Makefile.am | 18 +++++ libxcb/man/xcb-examples.man | 59 +++++++++++++++ libxcb/man/xcb-requests.man | 165 ++++++++++++++++++++++++++++++++++++++++++ libxcb/src/Makefile.am | 19 ++--- libxcb/src/c_client.py | 52 +++++++------ libxcb/src/man/.gitignore | 5 +- libxcb/src/man/xcb-examples.3 | 59 --------------- libxcb/src/man/xcb-requests.3 | 165 ------------------------------------------ 13 files changed, 370 insertions(+), 433 deletions(-) create mode 100644 libxcb/man/.gitignore create mode 100644 libxcb/man/Makefile.am create mode 100644 libxcb/man/xcb-examples.man create mode 100644 libxcb/man/xcb-requests.man delete mode 100644 libxcb/src/man/xcb-examples.3 delete mode 100644 libxcb/src/man/xcb-requests.3 (limited to 'libxcb') diff --git a/libxcb/Makefile.am b/libxcb/Makefile.am index 1cb3d9a7b..387c2f28e 100644 --- a/libxcb/Makefile.am +++ b/libxcb/Makefile.am @@ -1,6 +1,6 @@ ACLOCAL_AMFLAGS=-I m4 -SUBDIRS=src tests doc +SUBDIRS=src tests doc man pkgconfigdir = $(libdir)/pkgconfig diff --git a/libxcb/configure.ac b/libxcb/configure.ac index 6d0f844b8..68c3b2f0c 100644 --- a/libxcb/configure.ac +++ b/libxcb/configure.ac @@ -1,42 +1,51 @@ -# -*- Autoconf -*- -# Process this file with autoconf to produce a configure script. +dnl Process this file with autoconf to produce a configure script. # Initialize Autoconf AC_PREREQ([2.60]) -AC_INIT([libxcb], - 1.10, - [xcb@lists.freedesktop.org]) +AC_INIT([libxcb],[1.10], + [https://bugs.freedesktop.org/enter_bug.cgi?product=xcb], + [libxcb]) AC_CONFIG_AUX_DIR([build-aux]) AC_CONFIG_MACRO_DIR([m4]) AC_CONFIG_SRCDIR([xcb.pc.in]) +AC_CONFIG_HEADERS([src/config.h]) # Initialize Automake AM_INIT_AUTOMAKE([foreign dist-bzip2]) -m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES([yes])]) +AM_PATH_PYTHON([2.6]) # Set common system defines for POSIX extensions, such as _GNU_SOURCE # Must be called before any macros that run the compiler (like AC_PROG_LIBTOOL) # to avoid autoconf errors. AC_USE_SYSTEM_EXTENSIONS -AM_PATH_PYTHON([2.6]) +# Initialize libtool +LT_PREREQ([2.2]) +LT_INIT([win32-dll]) + +# Require xorg-macros minimum of 1.18 - Initial version +m4_ifndef([XORG_MACROS_VERSION], + [m4_fatal([must install xorg-macros 1.18 or later before running autoconf/autogen])]) +XORG_MACROS_VERSION(1.18) +XORG_DEFAULT_OPTIONS +XORG_ENABLE_DEVEL_DOCS +XORG_WITH_DOXYGEN + +# The dot drawing tool is checked by XORG_WITH_DOXYGEN, needed for xcb manual +if test x"$HAVE_DOT" = xno; then + AC_MSG_WARN([dot not found - doxygen targets will be skipped]) +fi PKG_CHECK_MODULES(CHECK, [check >= 0.9.4], [HAVE_CHECK=yes], [HAVE_CHECK=no]) AM_CONDITIONAL(HAVE_CHECK, test x$HAVE_CHECK = xyes) -AC_CONFIG_HEADERS([src/config.h]) - -AC_LIBTOOL_WIN32_DLL -AC_PROG_LIBTOOL -AC_PROG_CC - XSLTPROC=no HTML_CHECK_RESULT=no if test x"$HAVE_CHECK" = xyes; then - AC_PATH_PROG(XSLTPROC, xsltproc, no) - if test x"$XSLTPROC" != xno; then - HTML_CHECK_RESULT=yes - fi + AC_PATH_PROG(XSLTPROC, xsltproc, no) + if test x"$XSLTPROC" != xno; then + HTML_CHECK_RESULT=yes + fi fi AC_SUBST(HTML_CHECK_RESULT) @@ -47,17 +56,17 @@ PKG_CHECK_MODULES(NEEDED, $NEEDED) have_xdmcp="no" PKG_CHECK_MODULES(XDMCP, xdmcp, - AC_CHECK_LIB(Xdmcp, XdmcpWrap, - [ - AC_DEFINE(HASXDMAUTH,1,[Has Wraphelp.c needed for XDM AUTH protocols]) - NEEDED="$NEEDED xdmcp" - have_xdmcp="yes" - ], - [ - XDMCP_CFLAGS= - XDMCP_LIBS= - ], [$XDMCP_LIBS]), - [AC_MSG_RESULT(no)]) + AC_CHECK_LIB(Xdmcp, XdmcpWrap, + [ + AC_DEFINE(HASXDMAUTH,1,[Has Wraphelp.c needed for XDM AUTH protocols]) + NEEDED="$NEEDED xdmcp" + have_xdmcp="yes" + ], + [ + XDMCP_CFLAGS= + XDMCP_LIBS= + ], [$XDMCP_LIBS]), + [AC_MSG_RESULT(no)]) AC_SUBST(NEEDED) @@ -82,12 +91,12 @@ AC_SEARCH_LIBS(getaddrinfo, socket) AC_SEARCH_LIBS(connect, socket) AC_ARG_ENABLE(sendfds, AS_HELP_STRING([--disable-sendfds], [Support FD passing (default: auto)]), - [sendfds=$enableval], [sendfds=auto]) + [sendfds=$enableval], [sendfds=auto]) case x$sendfds in xauto) - AC_SEARCH_LIBS(sendmsg, socket, [sendfds="yes"], [sendfds="no"]) - ;; + AC_SEARCH_LIBS(sendmsg, socket, [sendfds="yes"], [sendfds="no"]) + ;; esac # XPG4v2/UNIX95 added msg_control - check to see if we need to define @@ -134,12 +143,12 @@ have_win32="no" lt_enable_auto_import="" case $host_os in mingw*) - have_win32="yes" - lt_enable_auto_import="-Wl,--enable-auto-import" - ;; + have_win32="yes" + lt_enable_auto_import="-Wl,--enable-auto-import" + ;; linux*) - AC_DEFINE([HAVE_ABSTRACT_SOCKETS], 1, [Define if your platform supports abstract sockets]) - ;; + AC_DEFINE([HAVE_ABSTRACT_SOCKETS], 1, [Define if your platform supports abstract sockets]) + ;; esac AC_SUBST(lt_enable_auto_import) @@ -147,7 +156,7 @@ AM_CONDITIONAL([XCB_HAVE_WIN32], [test "x${have_win32}" = "xyes"]) dnl define buffer queue size AC_ARG_WITH([queue-size], - AC_HELP_STRING([--with-queue-size=SIZE], + AS_HELP_STRING([--with-queue-size=SIZE], [Set the XCB buffer queue size (default is 16384)]), [xcb_queue_buffer_size="$withval"], [xcb_queue_buffer_size=16384]) @@ -156,11 +165,11 @@ AC_DEFINE_UNQUOTED(XCB_QUEUE_BUFFER_SIZE, [$xcb_queue_buffer_size], dnl check for the sockaddr_un.sun_len member AC_CHECK_MEMBER([struct sockaddr_un.sun_len], - [AC_DEFINE(HAVE_SOCKADDR_SUN_LEN,1,[Have the sockaddr_un.sun_len member.])], - [], - [ #include - #include - ]) + [AC_DEFINE(HAVE_SOCKADDR_SUN_LEN,1,[Have the sockaddr_un.sun_len member.])], + [], + [ #include + #include + ]) dnl check for support for Solaris Trusted Extensions AC_CHECK_HEADERS([tsol/label.h]) @@ -168,52 +177,39 @@ AC_CHECK_FUNCS([is_system_labeled]) dnl check for IOV_MAX, and fall back to UIO_MAXIOV on BSDish systems AC_CHECK_DECL([IOV_MAX], [], - [AC_CHECK_DECL([UIO_MAXIOV], [AC_DEFINE([IOV_MAX], [UIO_MAXIOV])], - [AC_DEFINE([IOV_MAX], [16], [Define if not provided by ])], - [[#include ]])], - [[#include ]]) + [AC_CHECK_DECL([UIO_MAXIOV], [AC_DEFINE([IOV_MAX], [UIO_MAXIOV])], + [AC_DEFINE([IOV_MAX], [16], [Define if not provided by ])], + [[#include ]])], + [[#include ]]) xcbincludedir='${includedir}/xcb' AC_SUBST(xcbincludedir) -if test "x$GCC" = xyes ; then - CWARNFLAGS="-Wall -Wpointer-arith -Wold-style-definition \ - -Wstrict-prototypes -Wmissing-declarations -Wnested-externs" -else - AC_CHECK_DECL([__SUNPRO_C], [SUNCC="yes"], [SUNCC="no"]) - if test "x$SUNCC" = "xyes"; then - CWARNFLAGS="-v -fd" - fi -fi -AC_SUBST(CWARNFLAGS) - XCB_CHECK_VISIBILITY() -XCB_CHECK_DOXYGEN() - AC_CHECK_FUNC(getaddrinfo, [AC_DEFINE(HAVE_GETADDRINFO, 1, [getaddrinfo() function is available])], ) case $host_os in - # darwin through Snow Leopard has poll() but can't be used to poll character devices. - darwin@<:@789@:>@*|darwin10*) ;; - darwin*) - _ac_xorg_macosx_version_min="" - if echo $CPPFLAGS $CFLAGS | grep -q mmacosx-version-min ; then - _ac_xorg_macosx_version_min=`echo $CPPFLAGS $CFLAGS | sed 's/^.*-mmacosx-version-min=\(@<:@^ @:>@*\).*$/\1/'` - else - _ac_xorg_macosx_version_min=$MACOSX_DEPLOYMENT_TARGET - fi - case $_ac_xorg_macosx_version_min in - 10.@<:@0123456@:>@|10.@<:@0123456@:>@.*) ;; - *) - AC_CHECK_FUNC(poll, [AC_DEFINE(USE_POLL, 1, [poll() function is available])], ) - ;; - esac - unset _ac_xorg_macosx_version_min - ;; - *) - AC_CHECK_FUNC(poll, [AC_DEFINE(USE_POLL, 1, [poll() function is available])], ) - ;; + # darwin through Snow Leopard has poll() but can't be used to poll character devices. + darwin@<:@789@:>@*|darwin10*) ;; + darwin*) + _ac_xorg_macosx_version_min="" + if echo $CPPFLAGS $CFLAGS | grep -q mmacosx-version-min ; then + _ac_xorg_macosx_version_min=`echo $CPPFLAGS $CFLAGS | sed 's/^.*-mmacosx-version-min=\(@<:@^ @:>@*\).*$/\1/'` + else + _ac_xorg_macosx_version_min=$MACOSX_DEPLOYMENT_TARGET + fi + case $_ac_xorg_macosx_version_min in + 10.@<:@0123456@:>@|10.@<:@0123456@:>@.*) ;; + *) + AC_CHECK_FUNC(poll, [AC_DEFINE(USE_POLL, 1, [poll() function is available])], ) + ;; + esac + unset _ac_xorg_macosx_version_min + ;; + *) + AC_CHECK_FUNC(poll, [AC_DEFINE(USE_POLL, 1, [poll() function is available])], ) + ;; esac XCB_EXTENSION(Composite, "yes") @@ -245,17 +241,18 @@ XCB_EXTENSION(XvMC, "yes") AC_ARG_WITH(launchd, AS_HELP_STRING([--with-launchd], [Build with support for Apple's launchd (default: auto)]), [LAUNCHD=$withval], [LAUNCHD=auto]) if test "x$LAUNCHD" = xauto; then - unset LAUNCHD - AC_CHECK_PROG(LAUNCHD, [launchd], [yes], [no], [$PATH$PATH_SEPARATOR/sbin]) + unset LAUNCHD + AC_CHECK_PROG(LAUNCHD, [launchd], [yes], [no], [$PATH$PATH_SEPARATOR/sbin]) fi if test "x$LAUNCHD" = xyes ; then - AC_DEFINE(HAVE_LAUNCHD, 1, [launchd support available]) + AC_DEFINE(HAVE_LAUNCHD, 1, [launchd support available]) fi AC_CONFIG_FILES([ Makefile doc/Makefile +man/Makefile src/Makefile tests/Makefile ]) @@ -338,7 +335,7 @@ echo "" echo " Used CFLAGS:" echo " CPPFLAGS............: ${CPPFLAGS}" echo " CFLAGS..............: ${CFLAGS}" -echo " Warning CFLAGS......: ${CWARNFLAGS}" +echo " Warning CFLAGS......: ${BASE_CFLAGS}" echo "" echo " Installation:" echo " Prefix..............: ${prefix}" diff --git a/libxcb/doc/Makefile.am b/libxcb/doc/Makefile.am index dbe2e0b0c..f3c934a72 100644 --- a/libxcb/doc/Makefile.am +++ b/libxcb/doc/Makefile.am @@ -8,7 +8,9 @@ xkb_issues docdirs = $(srcdir)/tutorial -if BUILD_DOCS +if ENABLE_DEVEL_DOCS +if HAVE_DOXYGEN +if HAVE_DOT docdirs += manual @@ -21,6 +23,8 @@ clean-local: rm -rf manual/ endif +endif +endif all-local: $(docdirs) diff --git a/libxcb/m4/xcb.m4 b/libxcb/m4/xcb.m4 index ad24bc2e5..32e852dd5 100644 --- a/libxcb/m4/xcb.m4 +++ b/libxcb/m4/xcb.m4 @@ -31,95 +31,6 @@ extern void f(int); CFLAGS=${save_CFLAGS} ]) -dnl Configure script for doxygen -dnl Vincent Torri 2006-05-11 -dnl -dnl XCB_CHECK_DOXYGEN([ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]]) -dnl Test for the doxygen program, and define BUILD_DOCS and DOXYGEN. -dnl -AC_DEFUN([XCB_CHECK_DOXYGEN], -[ -DOXYGEN="doxygen" - -dnl -dnl Disable the build of the documentation -dnl -AC_ARG_ENABLE( - [build_docs], - AC_HELP_STRING( - [--disable-build-docs], - [Disable the build of the documentation]), - [if test x"$enableval" != x"yes" ; then - enable_build_docs="no" - else - enable_build_docs="yes" - fi], - [enable_build_docs="yes"]) - -if test "$enable_build_docs" = "no" ; then - BUILD_DOCS=no -else -dnl -dnl Get the prefix where doxygen is installed. -dnl -AC_ARG_WITH( - [doxygen], - AC_HELP_STRING( - [--with-doxygen=FILE], - [doxygen program to use (eg /usr/bin/doxygen)]), - dnl - dnl Check the given doxygen program. - dnl - [DOXYGEN=${withval} - AC_CHECK_PROG( - [BUILD_DOCS], - [${DOXYGEN}], - [yes], - [no]) - if test $BUILD_DOCS = no; then - echo "WARNING:" - echo "The doxygen program you specified:" - echo "$DOXYGEN" - echo "was not found. Please check the path and make sure " - echo "the program exists and is executable." - AC_MSG_WARN( - [Warning: no doxygen detected. Documentation will not be built]) - fi], - [AC_CHECK_PROG( - [BUILD_DOCS], - [${DOXYGEN}], - [yes], - [no]) - if test ${BUILD_DOCS} = no; then - echo "WARNING:" - echo "The doxygen program was not found in your execute" - echo "You may have doxygen installed somewhere not covered by your path." - echo "" - echo "If this is the case make sure you have the packages installed, AND" - echo "that the doxygen program is in your execute path (see your" - echo "shell manual page on setting the \$PATH environment variable), OR" - echo "alternatively, specify the program to use with --with-doxygen." - AC_MSG_WARN( - [Warning: no doxygen detected. Documentation will not be built]) - fi]) - AC_PATH_PROG(DOT, dot, no) - if test "$DOT" = "no"; then - AC_MSG_WARN([Warning: no dot detected. Documentation will not be built]) - BUILD_DOCS="no" - fi -fi -AC_MSG_CHECKING([whether documentation is built]) -AC_MSG_RESULT([${BUILD_DOCS}]) - -dnl -dnl Substitution -dnl -AC_SUBST([DOXYGEN]) - -AM_CONDITIONAL(BUILD_DOCS, test "x$BUILD_DOCS" = "xyes") - -]) - dnl Detection and configuration of the visibility feature of gcc dnl Vincent Torri 2006-02-11 dnl diff --git a/libxcb/man/.gitignore b/libxcb/man/.gitignore new file mode 100644 index 000000000..181f3143c --- /dev/null +++ b/libxcb/man/.gitignore @@ -0,0 +1 @@ +*.[0-9] diff --git a/libxcb/man/Makefile.am b/libxcb/man/Makefile.am new file mode 100644 index 000000000..16bf51c55 --- /dev/null +++ b/libxcb/man/Makefile.am @@ -0,0 +1,18 @@ + +libmandir = $(LIB_MAN_DIR) + +libman_PRE = \ + xcb-examples.man \ + xcb-requests.man + +libman_DATA = $(libman_PRE:man=$(LIB_MAN_SUFFIX)) + +EXTRA_DIST = $(libman_PRE) + +CLEANFILES = $(libman_DATA) + +# String replacements in MAN_SUBSTS now come from xorg-macros.m4 via configure +SUFFIXES = .$(LIB_MAN_SUFFIX) .man + +.man.$(LIB_MAN_SUFFIX): + $(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@ diff --git a/libxcb/man/xcb-examples.man b/libxcb/man/xcb-examples.man new file mode 100644 index 000000000..87a71f27f --- /dev/null +++ b/libxcb/man/xcb-examples.man @@ -0,0 +1,59 @@ +.TH xcb-examples __libmansuffix__ __xorgversion__ "XCB examples" +.ad l +.SH NAME +xcb-examples \- manpage examples +.SH DESCRIPTION +Many of the XCB manpages contain example code. These examples intend to explain +how to use one particular part of XCB. They almost never represent a standalone +(or even useful) program - X11 programs are relatively involved and +thus beyond the scope of a manpage example. + +.SH ENVIRONMENT + +Every example assumes you have an \fIxcb_connection\fP and possibly other +variables at hand. For illustrating how \fIxcb_get_property\fP works, you need +the window of which you want to get the property, for example. To make it clear +that these variables are your responsibility, these examples consist of a +single function which takes the necessary variables as parameters. + +.SH FLUSHING + +Flushing means calling \fIxcb_flush\fP to clear the XCB-internal write buffer +and send all pending requests to the X11 server. You don't explicitly need to +flush before using a reply function (like \fIxcb_query_pointer_reply\fP), but +you do need to flush before entering the event loop of your program. + +There are only two cases when XCB flushes by itself. The first case is when +its write buffer becomes full, the second case is when you are asking for +the reply of a request which wasn't flushed out yet (like +\fIxcb_query_pointer_reply\fP). This last point also includes +xcb_request_check(). Please note that waiting for an event does \fBNOT\fP +flush. + +Examples generally include the \fIxcb_flush\fP call where appropriate (for +example after setting a property). Therefore, including these functions and +calling them in your application should just work. However, you might get +better results when flushing outside of the function, depending on the +architecture of your program. + +.SH COMPILATION + +If an example does not compile (without warnings) when using \fI-std=c99\fP, +that is considered a documentation bug. Similarly, not handling errors or +leaking memory is also considered a documentation bug. Please inform us about +it on xcb@lists.freedesktop.org. + +.SH CODING STYLE + +Every example uses 4 spaces for indentation. + +Comments are in asterisks, like /* this */. + +No line is longer than 80 characters (including indentation). + +.SH SEE ALSO +.BR xcb_connect (__libmansuffix__), +.BR xcb_get_property (__libmansuffix__), +.BR xcb_flush (__libmansuffix__) +.SH AUTHOR +Michael Stapelberg diff --git a/libxcb/man/xcb-requests.man b/libxcb/man/xcb-requests.man new file mode 100644 index 000000000..8d4a1dc5f --- /dev/null +++ b/libxcb/man/xcb-requests.man @@ -0,0 +1,165 @@ +.TH xcb-requests __libmansuffix__ __xorgversion__ "XCB examples" +.ad l +.SH NAME +xcb-requests \- about request manpages +.SH DESCRIPTION +Every request in X11, like \fIMapWindow\fP, corresponds to a number of +functions and data structures in XCB. For \fIMapWindow\fP, XCB provides the +function \fIxcb_map_window\fP, which fills the \fIxcb_map_window_request_t\fP +data structure and writes that to the X11 connection. Since the \fIMapWindow\fP +request does not have a reply, this is the most simple case. + +.SH REPLIES + +Many requests have replies. For each reply, XCB provides at least a +corresponding data structure and a function to return a pointer to a filled +data structure. Let's take the \fIInternAtom\fP request as an example: XCB +provides the \fIxcb_intern_atom_reply_t\fP data structure and +\fIxcb_intern_atom_reply\fP function. For replies which are more complex (for +example lists, such as in \fIxcb_list_fonts\fP), accessor functions are +provided. + +.SH COOKIES + +XCB returns a cookie for each request you send. This is an XCB-specific data +structure containing the sequence number with which the request was sent to the +X11 server. To get any reply, you have to provide that cookie (so that XCB +knows which of the waiting replies you want). Here is an example to illustrate +the use of cookies: + +.nf +.sp +void my_example(xcb_connection *conn) { + xcb_intern_atom_cookie_t cookie; + xcb_intern_atom_reply_t *reply; + + cookie = xcb_intern_atom(conn, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME"); + /* ... do other work here if possible ... */ + if ((reply = xcb_intern_atom_reply(conn, cookie, NULL))) { + printf("The _NET_WM_NAME atom has ID %u\n", reply->atom); + } + free(reply); +} +.fi + +.SH CHECKED VS. UNCHECKED + +The checked and unchecked suffixes for functions determine which kind of error +handling is used for this specific request. + +For requests which have no reply (for example \fIxcb_map_window\fP), errors +will be delivered to the event loop (you will receive an X11 event of type 0 +when calling \fIxcb_poll_for_event\fP). +If you want to explicitly check for errors in a blocking fashion, call the +_checked version of the function (for example \fIxcb_map_window_checked\fP) and +use \fIxcb_request_check\fP. + +For requests which have a reply (for example \fIxcb_intern_atom\fP), errors +will be checked when calling the reply function. To get errors in the event +loop instead, use the _unchecked version of the function (for example +\fIxcb_intern_atom_unchecked\fP). + +Here is an example which illustrates the four different ways of handling errors: + +.nf +.sp +/* + * Request without a reply, handling errors in the event loop (default) + * + */ +void my_example(xcb_connection *conn, xcb_window_t window) { + /* This is a request without a reply. Errors will be delivered to the event + * loop. Getting an error to xcb_map_window most likely is a bug in our + * program, so we don't need to check for that in a blocking way. */ + xcb_map_window(conn, window); + + /* ... of course your event loop would not be in the same function ... */ + while ((event = xcb_wait_for_event(conn)) != NULL) { + if (event->response_type == 0) { + fprintf("Received X11 error %d\\n", error->error_code); + free(event); + continue; + } + + /* ... handle a normal event ... */ + } +} + +/* + * Request without a reply, handling errors directly + * + */ +void my_example(xcb_connection *conn, xcb_window_t deco, xcb_window_t window) { + /* A reparenting window manager wants to know whether a new window was + * successfully reparented. If not (because the window got destroyed + * already, for example), it does not make sense to map an empty window + * decoration at all, so we need to know this right now. */ + xcb_void_cookie_t cookie = xcb_reparent_window_checked(conn, window, + deco, 0, 0); + xcb_generic_error_t *error; + if ((error = xcb_request_check(conn, cookie))) { + fprintf(stderr, "Could not reparent the window\\n"); + free(error); + return; + } + + /* ... do window manager stuff here ... */ +} + +/* + * Request with a reply, handling errors directly (default) + * + */ +void my_example(xcb_connection *conn, xcb_window_t window) { + xcb_intern_atom_cookie_t cookie; + xcb_intern_atom_reply_t *reply; + xcb_generic_error_t *error; + + cookie = xcb_intern_atom(c, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME"); + /* ... do other work here if possible ... */ + if ((reply = xcb_intern_atom_reply(c, cookie, &error))) { + printf("The _NET_WM_NAME atom has ID %u\n", reply->atom); + free(reply); + } else { + fprintf(stderr, "X11 Error %d\\n", error->error_code); + free(error); + } +} + +/* + * Request with a reply, handling errors in the event loop + * + */ +void my_example(xcb_connection *conn, xcb_window_t window) { + xcb_intern_atom_cookie_t cookie; + xcb_intern_atom_reply_t *reply; + + cookie = xcb_intern_atom_unchecked(c, 0, strlen("_NET_WM_NAME"), + "_NET_WM_NAME"); + /* ... do other work here if possible ... */ + if ((reply = xcb_intern_atom_reply(c, cookie, NULL))) { + printf("The _NET_WM_NAME atom has ID %u\n", reply->atom); + free(reply); + } + + /* ... of course your event loop would not be in the same function ... */ + while ((event = xcb_wait_for_event(conn)) != NULL) { + if (event->response_type == 0) { + fprintf("Received X11 error %d\\n", error->error_code); + free(event); + continue; + } + + /* ... handle a normal event ... */ + } +} +.fi + +.SH SEE ALSO +.BR xcb_map_window (__libmansuffix__), +.BR xcb_intern_atom (__libmansuffix__), +.BR xcb_list_fonts (__libmansuffix__), +.BR xcb_poll_for_event (__libmansuffix__), +.BR xcb_request_check (__libmansuffix__) +.SH AUTHOR +Michael Stapelberg diff --git a/libxcb/src/Makefile.am b/libxcb/src/Makefile.am index f2875dd18..5a3c52abd 100644 --- a/libxcb/src/Makefile.am +++ b/libxcb/src/Makefile.am @@ -4,7 +4,7 @@ EXTSOURCES = xproto.c \ bigreq.c \ xc_misc.c -AM_CFLAGS = $(CWARNFLAGS) $(NEEDED_CFLAGS) $(XDMCP_CFLAGS) +AM_CFLAGS = $(BASE_CFLAGS) $(NEEDED_CFLAGS) $(XDMCP_CFLAGS) libxcb_la_LIBADD = $(NEEDED_LIBS) $(XDMCP_LIBS) libxcb_la_SOURCES = \ xcb_conn.c xcb_out.c xcb_in.c xcb_ext.c xcb_xid.c \ @@ -241,15 +241,16 @@ endif nodist_xcbinclude_HEADERS = $(EXTHEADERS) noinst_HEADERS = xcbint.h -STATIC_MANS = man/xcb-examples.3 man/xcb-requests.3 -BUILT_MANS = man/xcb_*.3 -man_MANS = $(STATIC_MANS) $(BUILT_MANS) -EXTRA_DIST = $(STATIC_MANS) +BUILT_MAN_PAGES = man/xcb_* +libmandir = $(LIB_MAN_DIR) +libman_DATA = $(BUILT_MAN_PAGES) -BUILT_SOURCES = $(EXTSOURCES) $(BUILT_MANS) -CLEANFILES = $(EXTSOURCES) $(EXTHEADERS) $(BUILT_MANS) +BUILT_SOURCES = $(EXTSOURCES) $(BUILT_MAN_PAGES) +CLEANFILES = $(EXTSOURCES) $(EXTHEADERS) $(BUILT_MAN_PAGES) $(EXTSOURCES): c_client.py $(XCBPROTO_XCBINCLUDEDIR)/$(@:.c=.xml) - $(PYTHON) $(srcdir)/c_client.py -p $(XCBPROTO_XCBPYTHONDIR) $(XCBPROTO_XCBINCLUDEDIR)/$(@:.c=.xml) + $(AM_V_GEN)$(PYTHON) $(srcdir)/c_client.py -c "$(PACKAGE_STRING)" -l "$(XORG_MAN_PAGE)" \ + -s "$(LIB_MAN_SUFFIX)" -p $(XCBPROTO_XCBPYTHONDIR) \ + $(XCBPROTO_XCBINCLUDEDIR)/$(@:.c=.xml) -$(man_MANS): $(EXTSOURCES) +$(BUILT_MAN_PAGES): $(EXTSOURCES) diff --git a/libxcb/src/c_client.py b/libxcb/src/c_client.py index 161cbf59d..aaaab2e4a 100644 --- a/libxcb/src/c_client.py +++ b/libxcb/src/c_client.py @@ -2344,18 +2344,18 @@ def _man_request(self, name, cookie_type, void, aux): func_name = self.c_request_name if not aux else self.c_aux_name def create_link(linkname): - name = 'man/%s.3' % linkname + name = 'man/%s.%s' % (linkname, section) if manpaths: sys.stdout.write(name) f = open(name, 'w') - f.write('.so man3/%s.3' % func_name) + f.write('.so man%s/%s.%s' % (section, func_name, section)) f.close() if manpaths: - sys.stdout.write('man/%s.3 ' % func_name) + sys.stdout.write('man/%s.%s ' % (func_name, section)) # Our CWD is src/, so this will end up in src/man/ - f = open('man/%s.3' % func_name, 'w') - f.write('.TH %s 3 %s "XCB" "XCB Requests"\n' % (func_name, today)) + f = open('man/%s.%s' % (func_name, section), 'w') + f.write('.TH %s %s "%s" "%s" "XCB Requests"\n' % (func_name, section, center_footer, left_footer)) # Left-adjust instead of adjusting to both sides f.write('.ad l\n') f.write('.SH NAME\n') @@ -2680,14 +2680,14 @@ def _man_request(self, name, cookie_type, void, aux): 'have to be handled in the event loop.\n\nIf you want to ' 'handle errors directly with \\fIxcb_request_check\\fP ' 'instead, use \\fI%s_checked\\fP. See ' - '\\fBxcb-requests(3)\\fP for details.\n') % (base_func_name)) + '\\fBxcb-requests(%s)\\fP for details.\n') % (base_func_name, section)) else: f.write(('Returns an \\fI%s\\fP. Errors have to be handled when ' 'calling the reply function \\fI%s\\fP.\n\nIf you want to ' 'handle errors in the event loop instead, use ' - '\\fI%s_unchecked\\fP. See \\fBxcb-requests(3)\\fP for ' + '\\fI%s_unchecked\\fP. See \\fBxcb-requests(%s)\\fP for ' 'details.\n') % - (cookie_type, self.c_reply_name, base_func_name)) + (cookie_type, self.c_reply_name, base_func_name, section)) f.write('.SH ERRORS\n') if hasattr(self, "doc") and self.doc: for errtype, errtext in self.doc.errors.items(): @@ -2705,18 +2705,18 @@ def _man_request(self, name, cookie_type, void, aux): f.write('.fi\n') f.write('.SH SEE ALSO\n') if hasattr(self, "doc") and self.doc: - see = ['.BR %s (3)' % 'xcb-requests'] + see = ['.BR %s (%s)' % ('xcb-requests', section)] if self.doc.example: - see.append('.BR %s (3)' % 'xcb-examples') + see.append('.BR %s (%s)' % ('xcb-examples', section)) for seename, seetype in self.doc.see.items(): if seetype == 'program': see.append('.BR %s (1)' % seename) elif seetype == 'event': - see.append('.BR %s (3)' % _t(('xcb', seename, 'event'))) + see.append('.BR %s (%s)' % (_t(('xcb', seename, 'event')), section)) elif seetype == 'request': - see.append('.BR %s (3)' % _n(('xcb', seename))) + see.append('.BR %s (%s)' % (_n(('xcb', seename)), section)) elif seetype == 'function': - see.append('.BR %s (3)' % seename) + see.append('.BR %s (%s)' % (seename, section)) else: see.append('TODO: %s (type %s)' % (seename, seetype)) f.write(',\n'.join(see) + '\n') @@ -2726,10 +2726,10 @@ def _man_request(self, name, cookie_type, void, aux): def _man_event(self, name): if manpaths: - sys.stdout.write('man/%s.3 ' % self.c_type) + sys.stdout.write('man/%s.%s ' % (self.c_type, section)) # Our CWD is src/, so this will end up in src/man/ - f = open('man/%s.3' % self.c_type, 'w') - f.write('.TH %s 3 %s "XCB" "XCB Events"\n' % (self.c_type, today)) + f = open('man/%s.%s' % (self.c_type, section), 'w') + f.write('.TH %s %s "%s" "%s" "XCB Events"\n' % (self.c_type, section, center_footer, left_footer)) # Left-adjust instead of adjusting to both sides f.write('.ad l\n') f.write('.SH NAME\n') @@ -2835,18 +2835,18 @@ def _man_event(self, name): f.write('.fi\n') f.write('.SH SEE ALSO\n') if hasattr(self, "doc") and self.doc: - see = ['.BR %s (3)' % 'xcb_generic_event_t'] + see = ['.BR %s (%s)' % ('xcb_generic_event_t', section)] if self.doc.example: - see.append('.BR %s (3)' % 'xcb-examples') + see.append('.BR %s (%s)' % ('xcb-examples', section)) for seename, seetype in self.doc.see.items(): if seetype == 'program': see.append('.BR %s (1)' % seename) elif seetype == 'event': - see.append('.BR %s (3)' % _t(('xcb', seename, 'event'))) + see.append('.BR %s (%s)' % (_t(('xcb', seename, 'event')), section)) elif seetype == 'request': - see.append('.BR %s (3)' % _n(('xcb', seename))) + see.append('.BR %s (%s)' % (_n(('xcb', seename)), section)) elif seetype == 'function': - see.append('.BR %s (3)' % seename) + see.append('.BR %s (%s)' % (seename, section)) else: see.append('TODO: %s (type %s)' % (seename, seetype)) f.write(',\n'.join(see) + '\n') @@ -2978,13 +2978,19 @@ output = {'open' : c_open, # Check for the argument that specifies path to the xcbgen python package. try: - opts, args = getopt.getopt(sys.argv[1:], 'p:m') + opts, args = getopt.getopt(sys.argv[1:], 'c:l:s:p:m') except getopt.GetoptError as err: print(err) - print('Usage: c_client.py [-p path] file.xml') + print('Usage: c_client.py -c center_footer -l left_footer -s section [-p path] file.xml') sys.exit(1) for (opt, arg) in opts: + if opt == '-c': + center_footer=arg + if opt == '-l': + left_footer=arg + if opt == '-s': + section=arg if opt == '-p': sys.path.insert(1, arg) elif opt == '-m': diff --git a/libxcb/src/man/.gitignore b/libxcb/src/man/.gitignore index b36be7f44..f000a81f7 100644 --- a/libxcb/src/man/.gitignore +++ b/libxcb/src/man/.gitignore @@ -1,3 +1,2 @@ -*.3 -!xcb-examples.3 -!xcb-requests.3 +*.[0-9] +*.[0-9]x diff --git a/libxcb/src/man/xcb-examples.3 b/libxcb/src/man/xcb-examples.3 deleted file mode 100644 index c02fc0199..000000000 --- a/libxcb/src/man/xcb-examples.3 +++ /dev/null @@ -1,59 +0,0 @@ -.TH xcb-examples 3 2011-12-11 "XCB" "XCB examples" -.ad l -.SH NAME -xcb-examples \- manpage examples -.SH DESCRIPTION -Many of the XCB manpages contain example code. These examples intend to explain -how to use one particular part of XCB. They almost never represent a standalone -(or even useful) program - X11 programs are relatively involved and -thus beyond the scope of a manpage example. - -.SH ENVIRONMENT - -Every example assumes you have an \fIxcb_connection\fP and possibly other -variables at hand. For illustrating how \fIxcb_get_property\fP works, you need -the window of which you want to get the property, for example. To make it clear -that these variables are your responsibility, these examples consist of a -single function which takes the necessary variables as parameters. - -.SH FLUSHING - -Flushing means calling \fIxcb_flush\fP to clear the XCB-internal write buffer -and send all pending requests to the X11 server. You don't explicitly need to -flush before using a reply function (like \fIxcb_query_pointer_reply\fP), but -you do need to flush before entering the event loop of your program. - -There are only two cases when XCB flushes by itself. The first case is when -its write buffer becomes full, the second case is when you are asking for -the reply of a request which wasn't flushed out yet (like -\fIxcb_query_pointer_reply\fP). This last point also includes -xcb_request_check(). Please note that waiting for an event does \fBNOT\fP -flush. - -Examples generally include the \fIxcb_flush\fP call where appropriate (for -example after setting a property). Therefore, including these functions and -calling them in your application should just work. However, you might get -better results when flushing outside of the function, depending on the -architecture of your program. - -.SH COMPILATION - -If an example does not compile (without warnings) when using \fI-std=c99\fP, -that is considered a documentation bug. Similarly, not handling errors or -leaking memory is also considered a documentation bug. Please inform us about -it on xcb@lists.freedesktop.org. - -.SH CODING STYLE - -Every example uses 4 spaces for indentation. - -Comments are in asterisks, like /* this */. - -No line is longer than 80 characters (including indentation). - -.SH SEE ALSO -.BR xcb_connect (3), -.BR xcb_get_property (3), -.BR xcb_flush (3) -.SH AUTHOR -Michael Stapelberg diff --git a/libxcb/src/man/xcb-requests.3 b/libxcb/src/man/xcb-requests.3 deleted file mode 100644 index 278bcff13..000000000 --- a/libxcb/src/man/xcb-requests.3 +++ /dev/null @@ -1,165 +0,0 @@ -.TH xcb-requests 3 2011-12-11 "XCB" "XCB examples" -.ad l -.SH NAME -xcb-requests \- about request manpages -.SH DESCRIPTION -Every request in X11, like \fIMapWindow\fP, corresponds to a number of -functions and data structures in XCB. For \fIMapWindow\fP, XCB provides the -function \fIxcb_map_window\fP, which fills the \fIxcb_map_window_request_t\fP -data structure and writes that to the X11 connection. Since the \fIMapWindow\fP -request does not have a reply, this is the most simple case. - -.SH REPLIES - -Many requests have replies. For each reply, XCB provides at least a -corresponding data structure and a function to return a pointer to a filled -data structure. Let's take the \fIInternAtom\fP request as an example: XCB -provides the \fIxcb_intern_atom_reply_t\fP data structure and -\fIxcb_intern_atom_reply\fP function. For replies which are more complex (for -example lists, such as in \fIxcb_list_fonts\fP), accessor functions are -provided. - -.SH COOKIES - -XCB returns a cookie for each request you send. This is an XCB-specific data -structure containing the sequence number with which the request was sent to the -X11 server. To get any reply, you have to provide that cookie (so that XCB -knows which of the waiting replies you want). Here is an example to illustrate -the use of cookies: - -.nf -.sp -void my_example(xcb_connection *conn) { - xcb_intern_atom_cookie_t cookie; - xcb_intern_atom_reply_t *reply; - - cookie = xcb_intern_atom(conn, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME"); - /* ... do other work here if possible ... */ - if ((reply = xcb_intern_atom_reply(conn, cookie, NULL))) { - printf("The _NET_WM_NAME atom has ID %u\n", reply->atom); - } - free(reply); -} -.fi - -.SH CHECKED VS. UNCHECKED - -The checked and unchecked suffixes for functions determine which kind of error -handling is used for this specific request. - -For requests which have no reply (for example \fIxcb_map_window\fP), errors -will be delivered to the event loop (you will receive an X11 event of type 0 -when calling \fIxcb_poll_for_event\fP). -If you want to explicitly check for errors in a blocking fashion, call the -_checked version of the function (for example \fIxcb_map_window_checked\fP) and -use \fIxcb_request_check\fP. - -For requests which have a reply (for example \fIxcb_intern_atom\fP), errors -will be checked when calling the reply function. To get errors in the event -loop instead, use the _unchecked version of the function (for example -\fIxcb_intern_atom_unchecked\fP). - -Here is an example which illustrates the four different ways of handling errors: - -.nf -.sp -/* - * Request without a reply, handling errors in the event loop (default) - * - */ -void my_example(xcb_connection *conn, xcb_window_t window) { - /* This is a request without a reply. Errors will be delivered to the event - * loop. Getting an error to xcb_map_window most likely is a bug in our - * program, so we don't need to check for that in a blocking way. */ - xcb_map_window(conn, window); - - /* ... of course your event loop would not be in the same function ... */ - while ((event = xcb_wait_for_event(conn)) != NULL) { - if (event->response_type == 0) { - fprintf("Received X11 error %d\\n", error->error_code); - free(event); - continue; - } - - /* ... handle a normal event ... */ - } -} - -/* - * Request without a reply, handling errors directly - * - */ -void my_example(xcb_connection *conn, xcb_window_t deco, xcb_window_t window) { - /* A reparenting window manager wants to know whether a new window was - * successfully reparented. If not (because the window got destroyed - * already, for example), it does not make sense to map an empty window - * decoration at all, so we need to know this right now. */ - xcb_void_cookie_t cookie = xcb_reparent_window_checked(conn, window, - deco, 0, 0); - xcb_generic_error_t *error; - if ((error = xcb_request_check(conn, cookie))) { - fprintf(stderr, "Could not reparent the window\\n"); - free(error); - return; - } - - /* ... do window manager stuff here ... */ -} - -/* - * Request with a reply, handling errors directly (default) - * - */ -void my_example(xcb_connection *conn, xcb_window_t window) { - xcb_intern_atom_cookie_t cookie; - xcb_intern_atom_reply_t *reply; - xcb_generic_error_t *error; - - cookie = xcb_intern_atom(c, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME"); - /* ... do other work here if possible ... */ - if ((reply = xcb_intern_atom_reply(c, cookie, &error))) { - printf("The _NET_WM_NAME atom has ID %u\n", reply->atom); - free(reply); - } else { - fprintf(stderr, "X11 Error %d\\n", error->error_code); - free(error); - } -} - -/* - * Request with a reply, handling errors in the event loop - * - */ -void my_example(xcb_connection *conn, xcb_window_t window) { - xcb_intern_atom_cookie_t cookie; - xcb_intern_atom_reply_t *reply; - - cookie = xcb_intern_atom_unchecked(c, 0, strlen("_NET_WM_NAME"), - "_NET_WM_NAME"); - /* ... do other work here if possible ... */ - if ((reply = xcb_intern_atom_reply(c, cookie, NULL))) { - printf("The _NET_WM_NAME atom has ID %u\n", reply->atom); - free(reply); - } - - /* ... of course your event loop would not be in the same function ... */ - while ((event = xcb_wait_for_event(conn)) != NULL) { - if (event->response_type == 0) { - fprintf("Received X11 error %d\\n", error->error_code); - free(event); - continue; - } - - /* ... handle a normal event ... */ - } -} -.fi - -.SH SEE ALSO -.BR xcb_map_window (3), -.BR xcb_intern_atom (3), -.BR xcb_list_fonts (3), -.BR xcb_poll_for_event (3), -.BR xcb_request_check (3) -.SH AUTHOR -Michael Stapelberg -- cgit v1.2.3