doc: Create hot-linked areas in documents.

Added xslt processing to give DocBook output diagram image maps/hot-linked
areas consistent with those automatically generated by Doxygen.

Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>

doc/doxygen/Makefile.am

@@ -1,5 +1,5 @@
 
-.SUFFIXES = .gv .png
+.SUFFIXES = .gv .png .map
 
 noinst_DATA = xml/Client/index.xml xml/Server/index.xml
 dist_noinst_DATA = wayland.doxygen.in
@@ -27,6 +27,7 @@ scanned_src_files_man =					\
 diagramsdir := dot
 diagramssrc := $(wildcard $(diagramsdir)/*.gv)
 diagrams := $(patsubst $(diagramsdir)/%,xml/%,$(diagramssrc:.gv=.png))
+diagram_maps := $(patsubst $(diagramsdir)/%,xml/%,$(diagramssrc:.gv=.map))
 
 # find all man/man3/wl_foo.3 pages
 # for this to work, we need to create them before the man target (hence
@@ -38,7 +39,9 @@ alldirs := xml xml/Client xml/Server man/man3
 
 $(diagrams): $(diagramssrc)
 
-xml/%/index.xml: $(scanned_src_files_%) wayland.doxygen $(diagrams) | xml/%
+$(diagram_maps):  $(diagramssrc)
+
+xml/%/index.xml: $(scanned_src_files_%) wayland.doxygen $(diagrams) $(diagram_maps) | xml/%
 	$(AM_V_GEN)(cat wayland.doxygen; \
           echo "GENERATE_XML=YES"; \
           echo "XML_OUTPUT=xml/$*"; \
@@ -56,6 +59,9 @@ man/man3/wl_display.3: $(scanned_src_files_man) wayland.doxygen | man/man3
 xml/%.png: $(diagramsdir)/%.gv | xml
 	$(AM_V_GEN)$(DOT) -Tpng -o$@ $<
 
+xml/%.map: $(diagramsdir)/%.gv | xml
+	$(AM_V_GEN)$(DOT) -Tcmapx_np -o$@ $<
+
 # general rule to create one of the listed directories.
 $(alldirs):
 	$(AM_V_GEN)$(MKDIR_P) $@

doc/publican/Makefile.am

@@ -23,13 +23,15 @@ publican_sources = \
 	$(srcdir)/sources/Foreword.xml \
 	$(srcdir)/sources/Preface.xml \
 	$(srcdir)/sources/Revision_History.xml \
-	$(srcdir)/sources/Introduction.xml \
-	$(srcdir)/sources/Architecture.xml \
 	$(srcdir)/sources/Protocol.xml \
 	$(srcdir)/sources/Compositors.xml \
 	$(srcdir)/sources/images/icon.svg  \
 	$(srcdir)/sources/images/wayland.png
 
+processed_sources := \
+	$(srcdir)/sources/Architecture.xml \
+	$(srcdir)/sources/Introduction.xml
+
 css_sources = \
 	$(srcdir)/sources/css/brand.css \
 	$(srcdir)/sources/css/common.css \
@@ -45,6 +47,10 @@ doxygen_img_sources := \
 	$(doxydir)/xml/wayland-architecture.png \
 	$(doxydir)/xml/x-architecture.png
 
+map_sources := \
+	$(doxydir)/xml/x-architecture.map \
+	$(doxydir)/xml/wayland-architecture.map
+
 if HAVE_XMLTO
 if HAVE_XSLTPROC
 noinst_DATA = $(builddir)/Wayland $(publican_targets)
@@ -61,8 +67,10 @@ alldirs := $(builddir)/en-US $(builddir)/en-US/images $(html_destdir) $(html_des
 html_css_targets = $(addprefix $(html_destdir)/css/,$(notdir $(css_sources)))
 html_img_targets = $(addprefix $(html_destdir)/images/,$(notdir $(img_sources)))
 doxygen_img_targets := $(doxygen_img_sources:$(doxydir)/xml/%=$(html_destdir)/images/%)
+map_targets := $(map_sources:$(doxydir)/xml/%=$(builddir)/en-US/images/%)
+processed_targets := $(processed_sources:$(srcdir)/sources/%=$(builddir)/en-US/%)
 
-$(builddir)/Wayland: $(publican_targets) $(html_css_targets) $(html_img_targets) $(doxygen_img_targets) | $(builddir)/en-US
+$(builddir)/Wayland: $(publican_targets) $(html_css_targets) $(html_img_targets) $(processed_targets) $(doxygen_img_targets) | $(builddir)/en-US
 	$(AM_V_GEN)$(XMLTO) $(XMLTO_PARAM) html $(builddir)/en-US/Wayland.xml -o $(html_destdir)
 	@touch $@
 
@@ -111,6 +119,13 @@ $(builddir)/en-US/images/%: $(doxydir)/xml/% | $(builddir)/en-US/images
 	$(AM_V_GEN)cp -f $< $@
 	$(AM_V_at)chmod a+w $@
 
+# More specific rule to override explicitly listed targets and perform xslt
+# modifications on them.
+# Note that we can't use $< as all targets must be there
+$(processed_targets): $(processed_sources) $(map_targets) $(srcdir)/merge-mapcoords.xsl | $(builddir)/en-US/images
+	$(AM_V_GEN)$(XSLTPROC) --stringparam basedir $(builddir)/en-US \
+		$(srcdir)/merge-mapcoords.xsl $(addprefix $(srcdir)/sources/,$(notdir $@)) > $@
+
 # general rule to create one of the listed directories.
 $(alldirs):
 	$(AM_V_GEN)$(MKDIR_P) $@

doc/publican/merge-mapcoords.xsl

@@ -0,0 +1,64 @@
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+  <xsl:param name="basedir"/>
+  <xsl:output method="xml" encoding="utf-8" indent="yes"/>
+  <!-- -->
+  <!-- Template for the root so we can add a DOCTYPE -->
+  <xsl:template match="/">
+    <xsl:text disable-output-escaping="yes"><![CDATA[<!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">
+%BOOK_ENTITIES;
+]>
+]]></xsl:text>
+    <xsl:apply-templates select="@*|node()"/>
+  </xsl:template>
+  <!-- -->
+  <xsl:template match="@*|node()">
+    <xsl:copy>
+      <xsl:apply-templates select="@*|node()"/>
+    </xsl:copy>
+  </xsl:template>
+  <!-- -->
+  <!-- suppress existing image map areas -->
+  <xsl:template match="area"/>
+  <!-- -->
+  <xsl:template match="areaspec[area][name(..)='imageobjectco']">
+    <xsl:element name="areaspec">
+      <xsl:apply-templates select="@*"/>
+      <xsl:text>&#xa;</xsl:text>
+      <xsl:variable name="pngfile" select="../imageobject/imagedata/@fileref"/>
+      <xsl:variable name="mapfile" select="concat(substring($pngfile, 1, string-length($pngfile)-3), 'map')"/>
+      <xsl:variable name="maproot" select="document(concat($basedir, '/', $mapfile))"/>
+      <!-- -->
+      <!-- now emit the needed areas -->
+      <xsl:for-each select="area">
+	<xsl:variable name="anchor" select="."/>
+	<xsl:variable name="other" select="($maproot)//area[@href=($anchor)/@x_steal]"/>
+	<xsl:choose>
+	  <xsl:when test="$other">
+	    <xsl:text>&#x9;    </xsl:text>
+	    <xsl:element name="area">
+	      <xsl:attribute name="id">
+		<xsl:value-of select="@id"/>
+	      </xsl:attribute>
+	      <xsl:attribute name="linkends">
+		<xsl:value-of select="@linkends"/>
+	      </xsl:attribute>
+	      <xsl:attribute name="coords">
+		<xsl:value-of select="($other)/@coords"/>
+	      </xsl:attribute>
+	    </xsl:element>
+	  </xsl:when>
+	  <xsl:otherwise>
+	    <xsl:text>&#x9;    </xsl:text>
+	    <xsl:comment>
+	      <xsl:value-of select="concat('Warning: unable to locate area tagged ', ($anchor)/@x_steal)"/>
+	    </xsl:comment>
+	  </xsl:otherwise>
+	</xsl:choose>
+	<xsl:text>&#xa;</xsl:text>
+      </xsl:for-each>
+      <!-- -->
+      <xsl:text>&#x9;  </xsl:text>
+    </xsl:element>
+  </xsl:template>
+</xsl:stylesheet>

doc/publican/sources/Architecture.xml

@@ -16,19 +16,27 @@
     <para>
       This is where we are now with X:
     </para>
-    <mediaobject>
+    <figure>
-      <imageobject>
+      <title>X architecture diagram</title>
-	<imagedata fileref="images/x-architecture.png" format="PNG" />
+      <mediaobjectco>
-      </imageobject>
+	<imageobjectco>
-      <textobject>
+	  <areaspec id="map1" units="other" otherunits="imagemap">
-        <phrase>
+	    <area id="area1_1" linkends="x_flow_1" x_steal="#step_1"/>
-          X architecture diagram
+	    <area id="area1_2" linkends="x_flow_2" x_steal="#step_2"/>
-        </phrase>
+	    <area id="area1_3" linkends="x_flow_3" x_steal="#step_3"/>
-      </textobject>
+	    <area id="area1_4" linkends="x_flow_4" x_steal="#step_4"/>
-    </mediaobject>
+	    <area id="area1_5" linkends="x_flow_5" x_steal="#step_5"/>
+	    <area id="area1_6" linkends="x_flow_6" x_steal="#step_6"/>
+	  </areaspec>
+	  <imageobject>
+	    <imagedata fileref="images/x-architecture.png" format="PNG" />
+	  </imageobject>
+	</imageobjectco>
+      </mediaobjectco>
+    </figure>
     <para>
       <orderedlist>
-	<listitem>
+	<listitem id="x_flow_1">
 	  <para>
 	    The kernel gets an event from an input
 	    device and sends it to X through the evdev
@@ -39,7 +47,7 @@
 	    event standard.
 	  </para>
 	</listitem>
-	<listitem>
+	<listitem id="x_flow_2">
 	  <para>
 	    The X server determines which window the
 	    event affects and sends it to the clients
@@ -53,7 +61,7 @@
 	    etc).
 	  </para>
 	</listitem>
-	<listitem>
+	<listitem id="x_flow_3">
 	  <para>
 	    The client looks at the event and decides
 	    what to do. Often the UI will have to change
@@ -64,7 +72,7 @@
 	    X server.
 	  </para>
 	</listitem>
-	<listitem>
+	<listitem id="x_flow_4">
 	  <para>
 	    When the X server receives the rendering
 	    request, it sends it to the driver to let it
@@ -74,7 +82,7 @@
 	    the compositor as a damage event.
 	  </para>
 	</listitem>
-	<listitem>
+	<listitem id="x_flow_5">
 	  <para>
 	    The damage event tells the compositor that
 	    something changed in the window and that it
@@ -86,7 +94,7 @@
 	    to go through the X server to render this.
 	  </para>
 	</listitem>
-	<listitem>
+	<listitem id="x_flow_6">
 	  <para>
 	    The X server receives the rendering requests
 	    from the compositor and either copies the
@@ -125,19 +133,25 @@
       to the clients and lets the client send the damage event
       directly to the compositor:
     </para>
-    <mediaobject>
+    <figure>
-      <imageobject>
+      <title>Wayland architecture diagram</title>
-	<imagedata fileref="images/wayland-architecture.png" format="PNG" />
+      <mediaobjectco>
-      </imageobject>
+	<imageobjectco>
-      <textobject>
+	  <areaspec id="mapB" units="other" otherunits="imagemap">
-        <phrase>
+	    <area id="areaB_1" linkends="wayland_flow_1" x_steal="#step_1"/>
-          Wayland architecture diagram
+	    <area id="areaB_2" linkends="wayland_flow_2" x_steal="#step_2"/>
-        </phrase>
+	    <area id="areaB_3" linkends="wayland_flow_3" x_steal="#step_3"/>
-      </textobject>
+	    <area id="areaB_4" linkends="wayland_flow_4" x_steal="#step_4"/>
-    </mediaobject>
+	  </areaspec>
+	  <imageobject>
+	    <imagedata fileref="images/wayland-architecture.png" format="PNG" />
+	  </imageobject>
+	</imageobjectco>
+      </mediaobjectco>
+    </figure>
     <para>
       <orderedlist>
-	<listitem>
+	<listitem id="wayland_flow_1">
 	  <para>
 	    The kernel gets an event and sends
 	    it to the compositor. This
@@ -146,7 +160,7 @@
 	    input drivers in the kernel.
 	  </para>
 	</listitem>
-	<listitem>
+	<listitem id="wayland_flow_2">
 	  <para>
 	    The compositor looks through its
 	    scenegraph to determine which window
@@ -168,7 +182,7 @@
 	    transformation for the input events.
 	  </para>
 	</listitem>
-	<listitem>
+	<listitem id="wayland_flow_3">
 	  <para>
 	    As in the X case, when the client
 	    receives the event, it updates the
@@ -180,7 +194,7 @@
 	    updated.
 	  </para>
 	</listitem>
-	<listitem>
+	<listitem id="wayland_flow_4">
 	  <para>
 	    The compositor collects damage
 	    requests from its clients and then