mirror of
https://gitlab.freedesktop.org/wayland/wayland.git
synced 2025-10-29 05:40:16 -04:00
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>
This commit is contained in:
Jon Cruz
Bryce Harrington
parent
b5fca036cc
commit
8cf9a367c9
4 changed files with 134 additions and 35 deletions
|
|
@ -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) $@
|
||||
|
|
|
|||
|
|
@ -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) $@
|
||||
|
|
|
|||
64
doc/publican/merge-mapcoords.xsl
Normal file
64
doc/publican/merge-mapcoords.xsl
Normal file
|
|
@ -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>
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue