diff options
Diffstat (limited to 'libxcb/src')
| -rw-r--r-- | libxcb/src/Makefile.am | 19 | ||||
| -rw-r--r-- | libxcb/src/c_client.py | 52 | ||||
| -rw-r--r-- | libxcb/src/man/.gitignore | 5 | ||||
| -rw-r--r-- | libxcb/src/man/xcb-examples.3 | 59 | ||||
| -rw-r--r-- | libxcb/src/man/xcb-requests.3 | 165 |
5 files changed, 41 insertions, 259 deletions
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 794501a5d..9430c005a 100644 --- a/libxcb/src/c_client.py +++ b/libxcb/src/c_client.py @@ -2345,18 +2345,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') @@ -2681,14 +2681,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(): @@ -2706,18 +2706,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') @@ -2727,10 +2727,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') @@ -2836,18 +2836,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') @@ -2979,13 +2979,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 <michael+xcb at stapelberg dot de> 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 <michael+xcb at stapelberg dot de> |