From: David Herrmann Date: Mon, 24 Sep 2012 11:18:38 +0000 (+0200) Subject: man: add man-page infrastructure X-Git-Tag: 0.99.0~61 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=49dee9a86c39b8e656fdc628591cfc5257c1b8c2;p=platform%2Fupstream%2Fwayland.git man: add man-page infrastructure This adds a man-page infrastructure based on Docbook XML files. This allows us to integrate the man-pages into the publican books later. An example page for wl_display_connect() (with an alias wl_display_connect_to_fd()) is also added. Feel free to add more man-pages. Function calls are put in man3 and overview pages into man7. All pages (including aliases) have to be added to the Makefile. Docbook does generate aliases automatically from the additional names that were put in the XML file. However, a small SED script is needed to fixup the include-paths in the generated troff files. If someone knows how to avoid that (or even install them gzip'ped), please fix it up. Signed-off-by: David Herrmann --- diff --git a/.gitignore b/.gitignore index 0f449f5..4f7a934 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,8 @@ *.pc *.so *.swp +*.3 +*.7 *~ .libs cscope.out diff --git a/configure.ac b/configure.ac index 46b3cdf..4261ae6 100644 --- a/configure.ac +++ b/configure.ac @@ -88,6 +88,7 @@ AC_CONFIG_FILES([Makefile cursor/wayland-cursor-uninstalled.pc doc/Makefile doc/Wayland/Makefile + doc/man/Makefile src/Makefile src/wayland-server-uninstalled.pc src/wayland-client-uninstalled.pc diff --git a/doc/Makefile.am b/doc/Makefile.am index f8046e7..f7d7813 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1 +1 @@ -SUBDIRS = Wayland +SUBDIRS = Wayland man diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am new file mode 100644 index 0000000..7d00b06 --- /dev/null +++ b/doc/man/Makefile.am @@ -0,0 +1,45 @@ +# +# This generates man-pages out of the Docbook XML files. Simply add your files +# to the $MANPAGES array. If aliases are created, please add them to the +# MANPAGES_ALIASES array so they get installed correctly. +# + +MANPAGES = \ + wl_display_connect.3 +MANPAGES_ALIASES = \ + wl_display_connect_to_fd.3 + +wl_display_connect_to_fd.3: wl_display_connect.3 + +XML_FILES = \ + ${patsubst %.1,%.xml,${patsubst %.3,%.xml,${patsubst %.5,%.xml,${patsubst %.7,%.xml,$(MANPAGES)}}}} +CLEANFILES = $(MANPAGES) $(MANPAGES_ALIASES) +EXTRA_DIST = $(MANPAGES) $(MANPAGES_ALIASES) $(XML_FILES) +man_MANS = $(MANPAGES) $(MANPAGES_ALIASES) + +if HAVE_XSLTPROC + +XSLTPROC_FLAGS = \ + --stringparam man.authors.section.enabled 0 \ + --stringparam man.copyright.section.enabled 0 \ + --stringparam funcsynopsis.style ansi \ + --stringparam man.output.quietly 1 + +XSLTPROC_PROCESS_MAN = \ + $(AM_V_GEN)$(MKDIR_P) $(dir $@) && \ + $(XSLTPROC) -o $@ $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< && \ + $(SED) -i -e 's/^\.so \(.*\)\.\(.\)$$/\.so man\2\/\1\.\2/' $(MANPAGES_ALIASES) + +%.1: %.xml + $(XSLTPROC_PROCESS_MAN) + +%.3: %.xml + $(XSLTPROC_PROCESS_MAN) + +%.5: %.xml + $(XSLTPROC_PROCESS_MAN) + +%.7: %.xml + $(XSLTPROC_PROCESS_MAN) + +endif # HAVE_XSLTPROC diff --git a/doc/man/wl_display_connect.xml b/doc/man/wl_display_connect.xml new file mode 100644 index 0000000..b02abf0 --- /dev/null +++ b/doc/man/wl_display_connect.xml @@ -0,0 +1,88 @@ + + + + + + + + wl_display_connect + wayland-client + September 2012 + + + Developer + David + Herrmann + dh.herrmann@googlemail.com + + + + + + wl_display_connect + 3 + + + + wl_display_connect + wl_display_connect_to_fd + Connect to a wayland socket + + + + + + #include <wayland-client.h> + + + struct wl_display *wl_display_connect + const char *name + + + + struct wl_display *wl_display_connect_to_fd + int fd + + + + + + + Description + wl_display_connect connects to a wayland socket + that was previously opened by a wayland server. The server socket must + be placed in XDG_RUNTIME_DIR for this function to + find it. The name argument specifies the name of + the socket or NULL to use the default (which is + "wayland-0"). The environment variable + WAYLAND_DISPLAY replaces the default value. If + WAYLAND_SOCKET is set, this function behaves like + wl_display_connect_to_fd with the file-descriptor + number taken from the environment variable. + + wl_display_connect_to_fd connects to a wayland + socket with an explicit file-descriptor. The file-descriptor is passed + as argument fd. + + + + Return Value + wl_display_connect and + wl_display_connect_to_fd return a new display + context object or NULL on failure. errno is set + correspondingly. + + + + See Also + + wayland-client7, + wl_display_disconnect3, + wl_display_iterate3 + + +