[PATCH] man: add man-page infrastructure

Tue Sep 25 08:24:19 PDT 2012

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 <dh.herrmann at googlemail.com>
> ---
>  .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 <dh.herrmann at googlemail.com>
> +  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>dh.herrmann at googlemail.com</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
> 