Looks good as far as I can tell. I especially like that the content was moved out of the xsl and into data files.
Reviewed-by: Jon A. Cruz <[email protected]> Tested-by: Jon A. Cruz <[email protected]> On 01/28/2015 06:44 PM, Bill Spitzak wrote: > (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. > --- > 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 7e4fc48..2fa6773 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..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> > > _______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
