diff options
author | Jon Cruz <jonc@osg.samsung.com> | 2015-01-28 17:24:05 -0800 |
---|---|---|
committer | Bryce Harrington <bryce@osg.samsung.com> | 2015-01-28 17:43:18 -0800 |
commit | 8cf9a367c98756d4bdacc987573e23f13faf28e6 (patch) | |
tree | 3db4f91d803e214e6d9eb2a45cc8cd7148d40c79 | |
parent | b5fca036cc2bfc224a3db4724c00543d98008cb5 (diff) | |
download | wayland-8cf9a367c98756d4bdacc987573e23f13faf28e6.tar.gz |
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>
-rw-r--r-- | doc/doxygen/Makefile.am | 10 | ||||
-rw-r--r-- | doc/publican/Makefile.am | 21 | ||||
-rw-r--r-- | doc/publican/merge-mapcoords.xsl | 64 | ||||
-rw-r--r-- | doc/publican/sources/Architecture.xml | 74 |
4 files changed, 134 insertions, 35 deletions
diff --git a/doc/doxygen/Makefile.am b/doc/doxygen/Makefile.am index ea206b9..283e077 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 @@ -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) $@ diff --git a/doc/publican/Makefile.am b/doc/publican/Makefile.am index a4d6d58..7e4fc48 100644 --- a/doc/publican/Makefile.am +++ b/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) $@ 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 |