Commit 8cf9a367 authored by Jon Cruz's avatar Jon Cruz Committed by Bryce Harrington

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: default avatarJon A. Cruz <jonc@osg.samsung.com>
parent b5fca036
.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) $@
......
......@@ -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) $@
......
<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>
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment