doc: Intro text for doxygen output in it's own file

(This patch has been modified to apply atop current master)

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 demonstrates 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.
Reviewed-by: Jon A. Cruz <jonc@osg.samsung.com>
Tested-by: Jon A. Cruz <jonc@osg.samsung.com>

5 files changed, 155 insertions, 46 deletions

diff --git a/doc/publican/Makefile.am b/doc/publican/Makefile.am
index 4a7f225..c16a716 100644
--- a/doc/publican/Makefile.am
+++ b/doc/publican/Makefile.am
@@ -26,7 +26,9 @@ publican_sources = \
 	$(srcdir)/sources/Protocol.xml \
 	$(srcdir)/sources/Compositors.xml \
 	$(srcdir)/sources/images/icon.svg  \
-	$(srcdir)/sources/images/wayland.png
+	$(srcdir)/sources/images/wayland.png \
+	$(srcdir)/sources/Client.xml \
+	$(srcdir)/sources/Server.xml
 
 processed_sources := \
 	$(srcdir)/sources/Architecture.xml \
diff --git a/doc/publican/doxygen-to-publican.xsl b/doc/publican/doxygen-to-publican.xsl
index cbcb281..7c3b507 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..a1e3341
--- /dev/null
+++ b/doc/publican/sources/Client.xml
@@ -0,0 +1,92 @@
+<?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..f627d64
--- /dev/null
+++ b/doc/publican/sources/Server.xml
@@ -0,0 +1,49 @@
+<?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..2f47f13 100644
--- a/doc/publican/sources/Wayland.xml
+++ b/doc/publican/sources/Wayland.xml
@@ -12,7 +12,6 @@
   <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>
-