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 <[email protected]> --- .gitignore | 2 + configure.ac | 1 + doc/Makefile.am | 2 +- doc/man/Makefile.am | 45 +++++++++++++++++++++ doc/man/wl_display_connect.xml | 88 ++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 137 insertions(+), 1 deletion(-) create mode 100644 doc/man/Makefile.am create mode 100644 doc/man/wl_display_connect.xml 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 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd";> + +<!-- + Written 2012 by David Herrmann <[email protected]> + Dedicated to the Public Domain +--> + +<refentry id="wl_display_connect"> + <refentryinfo> + <title>wl_display_connect</title> + <productname>wayland-client</productname> + <date>September 2012</date> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>David</firstname> + <surname>Herrmann</surname> + <email>[email protected]</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>wl_display_connect</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>wl_display_connect</refname> + <refname>wl_display_connect_to_fd</refname> + <refpurpose>Connect to a wayland socket</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + + <funcsynopsisinfo>#include <wayland-client.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>struct wl_display *<function>wl_display_connect</function></funcdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>struct wl_display *<function>wl_display_connect_to_fd</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para><function>wl_display_connect</function> connects to a wayland socket + that was previously opened by a wayland server. The server socket must + be placed in <envar>XDG_RUNTIME_DIR</envar> for this function to + find it. The <varname>name</varname> argument specifies the name of + the socket or <constant>NULL</constant> to use the default (which is + <constant>"wayland-0"</constant>). The environment variable + <envar>WAYLAND_DISPLAY</envar> replaces the default value. If + <envar>WAYLAND_SOCKET</envar> is set, this function behaves like + <function>wl_display_connect_to_fd</function> with the file-descriptor + number taken from the environment variable.</para> + + <para><function>wl_display_connect_to_fd</function> connects to a wayland + socket with an explicit file-descriptor. The file-descriptor is passed + as argument <varname>fd</varname>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para><function>wl_display_connect</function> and + <function>wl_display_connect_to_fd</function> return a new display + context object or NULL on failure. <varname>errno</varname> is set + correspondingly.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>wayland-client</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>wl_display_disconnect</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>wl_display_iterate</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> +</refentry> -- 1.7.12.1 _______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
