[PATCH 2/2] doc: Create hot-linked areas in documents.
Jon A. Cruz
jonc at osg.samsung.com
Fri Dec 12 14:19:12 PST 2014
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 at osg.samsung.com>
---
doc/doxygen/Makefile.am | 10 +++--
doc/publican/Makefile.am | 21 ++++++++--
doc/publican/merge-mapcoords.xsl | 64 ++++++++++++++++++++++++++++++
doc/publican/sources/Architecture.xml | 74 +++++++++++++++++++++--------------
4 files changed, 133 insertions(+), 36 deletions(-)
create mode 100644 doc/publican/merge-mapcoords.xsl
diff --git a/doc/doxygen/Makefile.am b/doc/doxygen/Makefile.am
index f0cded3..8584406 100644
--- a/doc/doxygen/Makefile.am
+++ b/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
@@ -22,6 +22,7 @@ scanned_src_files_server = \
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
@@ -31,14 +32,14 @@ dist_man3_MANS = $(shell test -d man && find man/man3 -name "wl_*.3" -printf "ma
# Listing various directories that might need to be created.
alldirs := xml xml/client xml/server man/man3
-xml/client/index.xml: $(scanned_src_files_client) wayland.doxygen $(diagrams) | xml/client
+xml/client/index.xml: $(scanned_src_files_client) wayland.doxygen $(diagrams) $(diagram_maps) | xml/client
$(AM_V_GEN)(cat wayland.doxygen; \
echo "GENERATE_XML=YES"; \
echo "XML_OUTPUT=xml/client"; \
echo "INPUT= $(scanned_src_files_client)"; \
) | $(DOXYGEN) -
-xml/server/index.xml: $(scanned_src_files_server) wayland.doxygen $(diagrams) | xml/server
+xml/server/index.xml: $(scanned_src_files_server) wayland.doxygen $(diagrams) $(diagram_maps) | xml/server
$(AM_V_GEN)(cat wayland.doxygen; \
echo "GENERATE_XML=YES"; \
echo "XML_OUTPUT=xml/server"; \
@@ -56,6 +57,9 @@ man/man3/wl_display.3: $(scanned_src_files_client) $(scanned_src_files_server) w
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) $@
diff --git a/doc/publican/Makefile.am b/doc/publican/Makefile.am
index 058767a..741d562 100644
--- a/doc/publican/Makefile.am
+++ b/doc/publican/Makefile.am
@@ -25,14 +25,16 @@ 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/Library.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 \
@@ -48,6 +50,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)
@@ -64,8 +70,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 $@
@@ -127,6 +135,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) $@
diff --git a/doc/publican/merge-mapcoords.xsl b/doc/publican/merge-mapcoords.xsl
new file mode 100644
index 0000000..7adaca3
--- /dev/null
+++ b/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>
</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>	 </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>	 </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>
</xsl:text>
+ </xsl:for-each>
+ <!-- -->
+ <xsl:text>	 </xsl:text>
+ </xsl:element>
+ </xsl:template>
+</xsl:stylesheet>
diff --git a/doc/publican/sources/Architecture.xml b/doc/publican/sources/Architecture.xml
index 5b9300f..5d9ada0 100644
--- a/doc/publican/sources/Architecture.xml
+++ b/doc/publican/sources/Architecture.xml
@@ -16,19 +16,27 @@
<para>
This is where we are now with X:
</para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/x-architecture.png" format="PNG" />
- </imageobject>
- <textobject>
- <phrase>
- X architecture diagram
- </phrase>
- </textobject>
- </mediaobject>
+ <figure>
+ <title>X architecture diagram</title>
+ <mediaobjectco>
+ <imageobjectco>
+ <areaspec id="map1" units="other" otherunits="imagemap">
+ <area id="area1_1" linkends="x_flow_1" x_steal="#step_1"/>
+ <area id="area1_2" linkends="x_flow_2" x_steal="#step_2"/>
+ <area id="area1_3" linkends="x_flow_3" x_steal="#step_3"/>
+ <area id="area1_4" linkends="x_flow_4" x_steal="#step_4"/>
+ <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>
- <imageobject>
- <imagedata fileref="images/wayland-architecture.png" format="PNG" />
- </imageobject>
- <textobject>
- <phrase>
- Wayland architecture diagram
- </phrase>
- </textobject>
- </mediaobject>
+ <figure>
+ <title>Wayland architecture diagram</title>
+ <mediaobjectco>
+ <imageobjectco>
+ <areaspec id="mapB" units="other" otherunits="imagemap">
+ <area id="areaB_1" linkends="wayland_flow_1" x_steal="#step_1"/>
+ <area id="areaB_2" linkends="wayland_flow_2" x_steal="#step_2"/>
+ <area id="areaB_3" linkends="wayland_flow_3" x_steal="#step_3"/>
+ <area id="areaB_4" linkends="wayland_flow_4" x_steal="#step_4"/>
+ </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
--
1.9.1
More information about the wayland-devel
mailing list