[PATCH 5/8] doc: Intro text for doxygen output in it's own file
Bill Spitzak
spitzak at gmail.com
Fri Jan 2 18:29:19 PST 2015
This makes it considerably easier to edit the text and make it different
for each library.
To address previous concerns with this patch, I wrote some more complete
introductory text. This is based on my understanding of these libraries, which
may not be correct, and is pretty rudimentary for libwayland-server! However
this intro text should show how to create links to the doxygen-generated text.
It looks like you cannot link to methods easily as the link name contains a
hash number, but links to objects and classes work.
---
doc/publican/Makefile.am | 4 +-
doc/publican/doxygen-to-publican.xsl | 51 ++++---------------
doc/publican/sources/Client.xml | 93 ++++++++++++++++++++++++++++++++++
doc/publican/sources/Server.xml | 50 ++++++++++++++++++
doc/publican/sources/Wayland.xml | 4 +-
5 files changed, 157 insertions(+), 45 deletions(-)
create mode 100644 doc/publican/sources/Client.xml
create mode 100644 doc/publican/sources/Server.xml
diff --git a/doc/publican/Makefile.am b/doc/publican/Makefile.am
index 278da12..42bfb73 100644
--- a/doc/publican/Makefile.am
+++ b/doc/publican/Makefile.am
@@ -27,7 +27,9 @@ publican_sources = \
$(srcdir)/sources/images/icon.svg \
$(srcdir)/sources/images/wayland-architecture.png \
$(srcdir)/sources/images/wayland.png \
- $(srcdir)/sources/images/x-architecture.png
+ $(srcdir)/sources/images/x-architecture.png \
+ $(srcdir)/sources/Client.xml \
+ $(srcdir)/sources/Server.xml
css_sources = \
$(srcdir)/sources/css/brand.css \
diff --git a/doc/publican/doxygen-to-publican.xsl b/doc/publican/doxygen-to-publican.xsl
index a151628..ee57374 100644
--- a/doc/publican/doxygen-to-publican.xsl
+++ b/doc/publican/doxygen-to-publican.xsl
@@ -4,49 +4,16 @@
<xsl:param name="which" />
<xsl:template match="/">
- <!-- insert docbook's DOCTYPE blurb -->
- <xsl:text disable-output-escaping = "yes"><![CDATA[
-<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
- <!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
-%BOOK_ENTITIES;
-]>
-]]></xsl:text>
-
- <appendix id="sect-Library-$which">
- <xsl:attribute name="id">sect-Library-<xsl:value-of select="$which"/></xsl:attribute>
- <title><xsl:value-of select="$which"/> API</title>
-
- <para>
- The open-source reference implementation of Wayland protocol is
- split in two C libraries, <link
- linkend="sect-Library-Client">libwayland-client</link> and <link
- linkend="sect-Library-Server">libwayland-server</link>. Their
- main responsibility is to handle the Inter-process communication
- (<emphasis>IPC</emphasis>) with each other, therefore
- guaranteeing the protocol objects marshaling and messages
- synchronization.
- </para>
-
- <para>
- Following is the Wayland library classes for the
- <emphasis>libwayland-<xsl:value-of select="translate($which,
- 'SC', 'sc')"/></emphasis>. This appendix describes in detail
- the library's methods and their helpers, aiming implementors who
- are building a Wayland <xsl:value-of select="translate($which,
- 'SC', 'sc')"/>.
- </para>
-
- <xsl:apply-templates select="/doxygen/compounddef[@kind!='file' and @kind!='dir']" />
-
- <section id="{$which}-Functions">
- <title>Functions</title>
- <para />
- <variablelist>
- <xsl:apply-templates select="/doxygen/compounddef[@kind='file']/sectiondef/memberdef" />
- </variablelist>
- </section>
+ <xsl:apply-templates select="/doxygen/compounddef[@kind!='file' and @kind!='dir']" />
+
+ <section id="{$which}-Functions">
+ <title>Functions</title>
+ <para />
+ <variablelist>
+ <xsl:apply-templates select="/doxygen/compounddef[@kind='file']/sectiondef/memberdef" />
+ </variablelist>
+ </section>
- </appendix>
</xsl:template>
<xsl:template match="parameteritem">
diff --git a/doc/publican/sources/Client.xml b/doc/publican/sources/Client.xml
new file mode 100644
index 0000000..934cc4c
--- /dev/null
+++ b/doc/publican/sources/Client.xml
@@ -0,0 +1,93 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+ <!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
+ <!ENTITY doxygen SYSTEM "ClientAPI.xml">
+%BOOK_ENTITIES;
+]>
+<appendix id="sect-Library-Client">
+ <title>Client API</title>
+ <section><title>Introduction</title>
+ <para>
+ The open-source reference implementation of Wayland protocol is
+ split in two C libraries, libwayland-client and <link
+ linkend="sect-Library-Server">libwayland-server</link>. Their main
+ responsibility is to handle the Inter-process communication
+ (<emphasis>IPC</emphasis>) with each other, therefore guaranteeing
+ the protocol objects marshaling and messages synchronization.
+ </para>
+ <para>
+ A client uses libwayland-client to communicate with one or more
+ wayland servers. A <link
+ linkend="Client-classwl__display">wl_display</link> object is
+ created and manages each open connection to a server. At least one
+ <link linkend="Client-classwl__event__queue">wl_event_queue</link>
+ object is created for each wl_display, this holds events as they
+ are recieved from the server until they can be
+ processed. Multi-threading is supported by creating an additional
+ wl_event_queue for each additional thread, each object can have
+ it's events placed in a particular queue, so potentially a
+ different thread could be made to handle the events for each
+ object created.
+ </para>
+ <para>
+ Though some conveinence functions are provided, libwayland-client
+ is designed to allow the calling code to wait for events, so that
+ different polling mechanisms can be used. A file descriptor is
+ provided, when it becomes ready for reading the calling code can
+ ask libwayland-client to read the available events from it into
+ the wl_event_queue objects.
+ </para>
+ <para>
+ The library only provides low-level access to the wayland objects.
+ Each object created by the client is represented by a <link
+ linkend="Client-classwl__proxy">wl_proxy</link> object that this
+ library creates. This includes the id that is actually
+ communicated over the socket to the server, a void* data pointer
+ that is intended to point at a client's representation of the
+ object, and a pointer to a static <link
+ linkend="Client-structwl__interface">wl_interface</link> object,
+ which is generated from the xml and identifies the object's class
+ and can be used for introspection into the messages and events.
+ </para>
+ <para>
+ Messages are sent by calling wl_proxy_marshal. This will write a
+ message to the socket, by using the message id and the
+ wl_interface to identify the types of each argument and convert
+ them into stream format. Most software will call type-safe
+ wrappers generated from the xml description of the <link
+ linkend="appe-Wayland-Protocol">Wayland protocols</link>. For
+ instance the C header file generated from the xml defines the
+ following inline function to transmit the <link
+ linkend="protocol-spec-wl_surface-request-attach">wl_surface::attach</link>
+ message:
+ </para>
+ <programlisting>static inline void
+wl_surface_attach(struct wl_surface *wl_surface, struct wl_buffer *buffer, int32_t x, int32_t y)
+{
+ wl_proxy_marshal((struct wl_proxy *) wl_surface, WL_SURFACE_ATTACH, buffer, x, y);
+}</programlisting>
+ <para>
+ Events (messages from the server) are handled by calling a
+ "dispatcher" callback the client stores in the wl_proxy for each
+ event. A language binding for a string-based interpreter, such as
+ CPython, might have a dispatcher that uses the event name from the
+ wl_interface to identify the function to call. The default
+ dispatcher uses the message id number to index an array of
+ functions pointers, called a wl_listener, and the wl_interface to
+ convert data from the stream into arguments to the function. The
+ C header file generated from the xml defines a per-class structure
+ that forces the function pointers to be of the correct type, for
+ instance the <link
+ linkend="protocol-spec-wl_surface-event-enter">wl_surface::enter</link>
+ event defines this pointer in the wl_surface_listener object:
+ </para>
+ <programlisting>struct wl_surface_listener {
+ void (*enter)(void *data, struct wl_surface *, struct wl_output *);
+ ...
+}</programlisting>
+ <para>
+ </para>
+ </section>
+ &doxygen;
+</appendix>
+
diff --git a/doc/publican/sources/Server.xml b/doc/publican/sources/Server.xml
new file mode 100644
index 0000000..2050e9f
--- /dev/null
+++ b/doc/publican/sources/Server.xml
@@ -0,0 +1,50 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+ <!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
+ <!ENTITY doxygen SYSTEM "ServerAPI.xml">
+%BOOK_ENTITIES;
+]>
+<appendix id="sect-Library-Server">
+ <title>Server API</title>
+ <section><title>Introduction</title>
+ <para>
+ The open-source reference implementation of Wayland protocol is
+ split in two C libraries, <link
+ linkend="sect-Library-Client">libwayland-client</link> and
+ libwayland-server. Their main responsibility is to handle the
+ Inter-process communication (<emphasis>IPC</emphasis>) with each
+ other, therefore guaranteeing the protocol objects marshaling and
+ messages synchronization.
+ </para>
+ <para>
+ The server library is designed to work much like libwayland-client,
+ although it is considerably complicated due to the server needing
+ to support multiple versions of the protocol. It is best to learn
+ libwayland-client first.
+ </para>
+ <para>
+ Each open socket to a client is represented by a <link
+ linkend="Server-structwl__client">wl_client</link>. The equvalent
+ of the <link linkend="Client-classwl__proxy">wl_proxy</link> that
+ libwayland-client uses to represent an object is <link
+ linkend="Server-structwl__resource">wl_resource</link> for
+ client-created objects, and <link
+ linkend="Server-structwl__global">wl_global</link> for objects
+ created by the server.
+ </para>
+ <para>
+ Often a server is also a client for another Wayland server, and
+ thus must link with both libwayland-client and libwayland-server.
+ This produces some type name conflicts (such as the <link
+ linkend="Client-classwl__display">client wl_display</link> and
+ <link linkend="Server-structwl__display">server wl_display</link>,
+ but the duplicate-but-not-the-same types are opaque, and accessed
+ only inside the correct library where it came from. Naturally that
+ means that the program writer needs to always know if a pointer to
+ a wl_display is for the server or client side and use the
+ corresponding functions.
+ </para>
+ </section>
+ &doxygen;
+</appendix>
+
diff --git a/doc/publican/sources/Wayland.xml b/doc/publican/sources/Wayland.xml
index 5ae90bb..d789b43 100644
--- a/doc/publican/sources/Wayland.xml
+++ b/doc/publican/sources/Wayland.xml
@@ -12,7 +12,7 @@
<xi:include href="Architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Protocol.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="ProtocolSpec.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="ClientAPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
- <xi:include href="ServerAPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="Client.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="Server.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</book>
--
1.7.9.5
More information about the wayland-devel
mailing list