[PATCH V3] doc: Intro text for doxygen output in it's own file
Jon A. Cruz
jonc at osg.samsung.com
Thu Jan 29 14:57:10 PST 2015
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 <jonc at osg.samsung.com>
Tested-by: Jon A. Cruz <jonc at osg.samsung.com>
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>
>
>
More information about the wayland-devel
mailing list