Commit 49dee9a8 authored by David Herrmann's avatar David Herrmann Committed by Kristian H. Kristensen

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: 's avatarDavid Herrmann <dh.herrmann@googlemail.com>
parent 35d8da8e
......@@ -6,6 +6,8 @@
*.pc
*.so
*.swp
*.3
*.7
*~
.libs
cscope.out
......
......@@ -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
......
SUBDIRS = Wayland
SUBDIRS = Wayland man
#
# 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
<?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@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@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 &lt;wayland-client.h&gt;</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>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment