doc: Auto-generate Protocol/Interfaces section instead

Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>

3 files changed, 66 insertions, 128 deletions

diff --git a/doc/Wayland/Makefile.am b/doc/Wayland/Makefile.am
index 6d73de8..600bf86 100644
--- a/doc/Wayland/Makefile.am
+++ b/doc/Wayland/Makefile.am
@@ -17,7 +17,7 @@ noinst_DATA = Wayland $(publican_targets)
 pubdir = $(docdir)/Wayland/en-US
 
 publican_targets = $(publican_sources:$(srcdir)/en_US%=$(builddir)/en-US%) \
-	en-US/ProtocolSpec.xml
+	en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml
 
 # The Protocol.xml is purely generated and required before running publican
 en-US/ProtocolSpec.xml: $(top_srcdir)/protocol/wayland.xml $(srcdir)/protocol-to-docbook.xsl
@@ -25,10 +25,16 @@ en-US/ProtocolSpec.xml: $(top_srcdir)/protocol/wayland.xml $(srcdir)/protocol-to
 	$(AM_V_GEN)$(XSLTPROC) $(srcdir)/protocol-to-docbook.xsl \
 		$(top_srcdir)/protocol/wayland.xml > en-US/ProtocolSpec.xml
 
+en-US/ProtocolInterfaces.xml: $(top_srcdir)/protocol/wayland.xml $(srcdir)/protocol-interfaces-to-docbook.xsl
+	$(AM_V_GEN)$(MKDIR_P) en-US/images
+	$(AM_V_GEN)$(XSLTPROC) $(srcdir)/protocol-interfaces-to-docbook.xsl \
+		$(top_srcdir)/protocol/wayland.xml > en-US/ProtocolInterfaces.xml
+
+
 # Copy the en_US source files into en-US destination
 # This is required for out-of-source-tree build as publican does not allow us
 # to specify the location of the source code.
-$(builddir)/en-US/%: $(srcdir)/en_US/% en-US/ProtocolSpec.xml $(publican_sources)
+$(builddir)/en-US/%: $(srcdir)/en_US/% en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml $(publican_sources)
 	$(AM_V_GEN)cp -f $< $@
 
 # Run publican for the builddir on the generated (or copied) source
@@ -38,7 +44,7 @@ Wayland: $(publican_targets)
 		--config $(srcdir)/publican.cfg
 	@touch Wayland
 
-CLEANFILES = en-US/ProtocolSpec.xml $(publican_targets)
+CLEANFILES = en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml $(publican_targets)
 
 clean-local:
 	$(AM_V_at)rm -fr en-US
diff --git a/doc/Wayland/en_US/Protocol.xml b/doc/Wayland/en_US/Protocol.xml
index 8927837..943dd3b 100644
--- a/doc/Wayland/en_US/Protocol.xml
+++ b/doc/Wayland/en_US/Protocol.xml
@@ -163,131 +163,7 @@
       </variablelist>
     </para>
   </section>
-  <section id="sect-Protocol-Interfaces">
-    <title>Interfaces</title>
-    <para>
-      The protocol includes several interfaces which are used for
-      interacting with the server.  Each interface provides requests,
-      events, and errors (which are really just special events) as described
-      above.  Specific compositor implementations may have their own
-      interfaces provided as extensions, but there are several which are
-      always expected to be present.
-    </para>
-    <para>
-      Core interfaces:
-      <variablelist>
-	<varlistentry>
-	  <term>wl_display</term>
-	  <listitem>
-	    <para>
-	      provides global functionality like object binding and
-	      fatal error events
-	    </para>
-	  </listitem>
-	</varlistentry>
-	<varlistentry>
-	  <term>wl_callback</term>
-	  <listitem>
-	    <para>
-	      callback interface for done events
-	    </para>
-	  </listitem>
-	</varlistentry>
-	<varlistentry>
-	  <term>wl_compositor</term>
-	  <listitem>
-	    <para>
-	      core compositor interface, allows surface creation
-	    </para>
-	  </listitem>
-	</varlistentry>
-	<varlistentry>
-	  <term>wl_shm</term>
-	  <listitem>
-	    <para>
-	      buffer management interface with buffer creation and format
-	      handling
-	    </para>
-	  </listitem>
-	</varlistentry>
-	<varlistentry>
-	  <term>wl_buffer</term>
-	  <listitem>
-	    <para>
-	      buffer handling interface for indicating damage and object
-	      destruction, also provides buffer release events from the
-	      server
-	    </para>
-	  </listitem>
-	</varlistentry>
-	<varlistentry>
-	  <term>wl_data_offer</term>
-	  <listitem>
-	    <para>
-	      for accepting and receiving specific mime types
-	    </para>
-	  </listitem>
-	</varlistentry>
-	<varlistentry>
-	  <term>wl_data_source</term>
-	  <listitem>
-	    <para>
-	      for offering specific mime types
-	    </para>
-	  </listitem>
-	</varlistentry>
-	<varlistentry>
-	  <term>wl_data_device</term>
-	  <listitem>
-	    <para>
-	      lets clients manage drag &amp; drop, provides pointer enter/leave events and motion
-	    </para>
-	  </listitem>
-	</varlistentry>
-	<varlistentry>
-	  <term>wl_data_device_manager</term>
-	  <listitem>
-	    <para>
-	      for managing data sources and devices
-	    </para>
-	  </listitem>
-	</varlistentry>
-	<varlistentry>
-	  <term>wl_shell</term>
-	  <listitem>
-	    <para>
-	      shell surface handling
-	    </para>
-	  </listitem>
-	</varlistentry>
-	<varlistentry>
-	  <term>wl_shell_surface</term>
-	  <listitem>
-	    <para>
-	      shell surface handling and desktop-like events (e.g. set a
-	      surface to fullscreen, display a popup, etc.)
-	    </para>
-	  </listitem>
-	</varlistentry>
-	<varlistentry>
-	  <term>wl_seat</term>
-	  <listitem>
-	    <para>
-	      cursor setting, motion, button, and key events, etc.
-	    </para>
-	  </listitem>
-	</varlistentry>
-	<varlistentry>
-	  <term>wl_output</term>
-	  <listitem>
-	    <para>
-	      events describing an attached output (subpixel orientation,
-	      current mode &amp; geometry, etc.) </para>
-	  </listitem>
-	</varlistentry>
-      </variablelist>
-    </para>
-  </section>
+  <xi:include href="ProtocolInterfaces.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
   <section id="sect-Protocol-Connect-Time">
     <title>Connect Time</title>
     <para>
diff --git a/doc/Wayland/protocol-interfaces-to-docbook.xsl b/doc/Wayland/protocol-interfaces-to-docbook.xsl
new file mode 100644
index 0000000..ad6bdda
--- /dev/null
+++ b/doc/Wayland/protocol-interfaces-to-docbook.xsl
@@ -0,0 +1,56 @@
+<?xml version="1.0" ?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+<xsl:output method="xml" indent="yes" encoding="UTF-8"/>
+<xsl:output method="xml" encoding="UTF-8" indent="yes" />
+
+<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>
+
+  <section id="sect-Protocol-Interfaces">
+    <title>Interfaces</title>
+    <para>
+      The protocol includes several interfaces which are used for
+      interacting with the server.  Each interface provides requests,
+      events, and errors (which are really just special events) as described
+      above.  Specific compositor implementations may have their own
+      interfaces provided as extensions, but there are several which are
+      always expected to be present.
+    </para>
+
+    <para>
+    Core interfaces:
+    <variablelist>
+    <xsl:apply-templates select="protocol/interface" />
+    </variablelist>
+    </para>
+  </section>
+</xsl:template>
+
+<!-- Interfaces summary -->
+<xsl:template match="interface" >
+<varlistentry>
+    <xsl:attribute name="id">protocol-summary-<xsl:value-of select="name()"/>-<xsl:value-of select="@name" />
+    </xsl:attribute>
+    <term>
+      <xsl:value-of select="@name" />
+      <xsl:if test="description/@summary">
+        - <xsl:value-of select="description/@summary" />
+      </xsl:if>
+    </term>
+    <listitem>
+    <para>
+      <xsl:value-of select="description"/>
+    </para>
+    </listitem>
+  </varlistentry>
+
+</xsl:template>
+
+</xsl:stylesheet>
+<!-- vim: set expandtab shiftwidth=2: -->