[PATCH 1/4] doc: generate man pages from doxygen

[Peter Hutterer]

Create client-side and server-side man pages from doxygen. The doxygen
config options are virtually the same as for the XML output, but we do pass
in the specific options via stdin.

WL_EXPORT is predefined to the empty string, it makes the man page look
confusing and provides no value here anyway. This applies for both xml and
man output.

JAVADOC_AUTOBRIEF is disabled for man pages, the formatting in the resulting
man page is IMO hard to read.

Most of the server man pages are virtually empty, there's just not enough
documentation in the source files.

Interesting issue: the usage of @code in the protocol to reference the
parameter breaks the expansion of WL_EXPORT, thus leaving us with WL_EXPORT
in all the man pages.
Presumably this is an issue with doxygen interpreting this as a @code
command, but I already wasted enough time narrowing this down.

Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
 doc/doxygen/Makefile.am        | 71 ++++++++++++++++++++++++++++++++++++++++--
 doc/doxygen/wayland.doxygen.in |  6 ++--
 protocol/wayland.xml           |  2 +-
 3 files changed, 73 insertions(+), 6 deletions(-)

diff --git a/doc/doxygen/Makefile.am b/doc/doxygen/Makefile.am
index fdbb246..40dcecb 100644
--- a/doc/doxygen/Makefile.am
+++ b/doc/doxygen/Makefile.am
@@ -2,12 +2,79 @@
 noinst_DATA = xml/index.xml
 dist_noinst_DATA = wayland.doxygen.in
 
-scanned_src_files = 				\
+scanned_src_files_client = 				\
 	$(top_srcdir)/src/wayland-client.c	\
 	$(top_srcdir)/src/wayland-client.h
 
-xml/index.xml: $(scanned_src_files) wayland.doxygen
+scanned_src_files_server = 				\
+	$(top_srcdir)/src/wayland-server.c	\
+	$(top_srcdir)/src/wayland-server.h
+
+client_MANPAGES = \
+	man/man3/wl_display.3 \
+	man/man3/wl_display_connect.3 \
+	man/man3/wl_display_connect_to_fd.3 \
+	man/man3/wl_display_create_queue.3 \
+	man/man3/wl_display_disconnect.3 \
+	man/man3/wl_display_dispatch.3 \
+	man/man3/wl_display_dispatch_pending.3 \
+	man/man3/wl_display_dispatch_queue.3 \
+	man/man3/wl_display_dispatch_queue_pending.3 \
+	man/man3/wl_display_flush.3 \
+	man/man3/wl_display_get_error.3 \
+	man/man3/wl_display_get_fd.3 \
+	man/man3/wl_display_roundtrip.3 \
+	man/man3/wl_event_queue.3 \
+	man/man3/wl_event_queue_destroy.3 \
+	man/man3/wl_proxy.3 \
+	man/man3/wl_proxy_add_listener.3 \
+	man/man3/wl_proxy_create.3 \
+	man/man3/wl_proxy_destroy.3 \
+	man/man3/wl_proxy_get_class.3 \
+	man/man3/wl_proxy_get_id.3 \
+	man/man3/wl_proxy_get_user_data.3 \
+	man/man3/wl_proxy_marshal.3 \
+	man/man3/wl_proxy_set_queue.3 \
+	man/man3/wl_proxy_set_user_data.3
+
+server_MANPAGES = \
+	man/man3/wl_buffer.3 \
+	man/man3/wl_client.3 \
+	man/man3/wl_data_offer.3 \
+	man/man3/wl_data_source.3 \
+	man/man3/wl_global.3 \
+	man/man3/wl_keyboard.3 \
+	man/man3/wl_keyboard_grab.3 \
+	man/man3/wl_keyboard_grab_interface.3 \
+	man/man3/wl_listener.3 \
+	man/man3/wl_pointer.3 \
+	man/man3/wl_pointer_grab.3 \
+	man/man3/wl_pointer_grab_interface.3 \
+	man/man3/wl_resource.3 \
+	man/man3/wl_seat.3 \
+	man/man3/wl_signal.3 \
+	man/man3/wl_socket.3 \
+	man/man3/wl_surface.3 \
+	man/man3/wl_touch.3 \
+	man/man3/wl_touch_grab.3 \
+	man/man3/wl_touch_grab_interface.3
+
+man3_MANS= $(client_MANPAGES) $(server_MANPAGES)
+
+xml/index.xml: $(scanned_src_files_client) wayland.doxygen
 	doxygen wayland.doxygen
 
+doxygen.man: $(scanned_src_files_client) $(scanned_src_files_server)
+	(cat wayland.doxygen; \
+          echo "GENERATE_XML=NO"; \
+          echo "GENERATE_MAN=YES"; \
+          echo "MAN_OUTPUT=man"; \
+          echo "JAVADOC_AUTOBRIEF=NO"; \
+          echo "INPUT= $^"; \
+          ) | doxygen -
+
+$(client_MANPAGES) $(server_MANPAGES): doxygen.man
+
 clean-local:
 	rm -rf xml/
+	rm -rf man/
diff --git a/doc/doxygen/wayland.doxygen.in b/doc/doxygen/wayland.doxygen.in
index 12d0817..e700e3d 100644
--- a/doc/doxygen/wayland.doxygen.in
+++ b/doc/doxygen/wayland.doxygen.in
@@ -1453,13 +1453,13 @@ ENABLE_PREPROCESSING   = YES
 # compilation will be performed. Macro expansion can be done in a controlled
 # way by setting EXPAND_ONLY_PREDEF to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
 # then the macro expansion is limited to the macros specified with the
 # PREDEFINED and EXPAND_AS_DEFINED tags.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
 # pointed to by INCLUDE_PATH will be searched when a #include is found.
@@ -1487,7 +1487,7 @@ INCLUDE_FILE_PATTERNS  =
 # undefined via #undef or recursively expanded use the := operator
 # instead of the = operator.
 
-PREDEFINED             =
+PREDEFINED             = WL_EXPORT=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
 # this tag can be used to specify a list of macro names that should be expanded.
diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 9a0aa15..436d5b4 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -57,7 +57,7 @@
 	The error event is sent out when a fatal (non-recoverable)
 	error has occurred.  The @object_id argument is the object
 	where the error occurred, most often in response to a request
-	to that object.  The @code identifies the error and is defined
+	to that object.  The code identifies the error and is defined
 	by the object interface.  As such, each interface defines its
 	own set of error codes.  The @message is an brief description
 	of the error, for (debugging) convenience.
-- 
1.8.1.4