On Mon, Sep 24, 2012 at 01:18:38PM +0200, David Herrmann wrote: > 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.
Very nice, thanks for starting this. Kristian > 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
