man: build static man pages using xorg patterns

The section number is no longer hard-coded, supplied by xorg-macros.
The left footer is now "X Version 11".
The center footer is the package name with the version, "libxcb 1.9"
The man directory is a sibbling to the doc directory. One can build
or clean the man pages without disturbing the library code.

Reviewed-by: Josh Triplett <josh@joshtriplett.org>
Signed-off-by: Gaetan Nadon <memsize@videotron.ca>

4 files changed, 243 insertions, 0 deletions

diff --git a/man/.gitignore b/man/.gitignore
new file mode 100644
index 0000000..181f314
--- /dev/null
+++ b/man/.gitignore
@@ -0,0 +1 @@
+*.[0-9]
diff --git a/man/Makefile.am b/man/Makefile.am
new file mode 100644
index 0000000..16bf51c
--- /dev/null
+++ b/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/man/xcb-examples.man b/man/xcb-examples.man
new file mode 100644
index 0000000..87a71f2
--- /dev/null
+++ b/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 <michael+xcb at stapelberg dot de>
diff --git a/man/xcb-requests.man b/man/xcb-requests.man
new file mode 100644
index 0000000..8d4a1dc
--- /dev/null
+++ b/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 <michael+xcb at stapelberg dot de>