[PATCH RFC] protocol: add xslt stylesheet to prettify the protocol
Peter Hutterer
peter.hutterer at who-t.net
Wed Feb 22 21:58:37 PST 2012
Includes rudimentary styling only.
Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
A few things to note:
- I'm not a designer
- Having a html version of the protocol makes it a lot easier to read, and
it certainly reveals missing bits of documentation in the protocol
- the .css file is the one from wayland.freedesktop.org, someone could
easily fix it to prettify the result a bit.
Makefile.am | 2 +-
configure.ac | 6 +-
protocol/Makefile.am | 7 ++
protocol/protocol.xsl | 204 +++++++++++++++++++++++++++++++++++++++++++++++++
protocol/wayland.css | 41 ++++++++++
5 files changed, 258 insertions(+), 2 deletions(-)
create mode 100644 protocol/Makefile.am
create mode 100644 protocol/protocol.xsl
create mode 100644 protocol/wayland.css
diff --git a/Makefile.am b/Makefile.am
index 4461e48..016bb76 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,4 +1,4 @@
-SUBDIRS = src
+SUBDIRS = src protocol
ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS}
diff --git a/configure.ac b/configure.ac
index a1c9d2a..fc623e8 100644
--- a/configure.ac
+++ b/configure.ac
@@ -48,9 +48,13 @@ if test "x$enable_scanner" = "xyes"; then
AC_SUBST(EXPAT_LIBS)
fi
+AC_PATH_PROG(XSLTPROC, xsltproc)
+AM_CONDITIONAL([HAVE_XSLTPROC], [test $XSLTPROC != ""])
+
AC_CONFIG_FILES([Makefile
wayland-scanner.m4
src/Makefile
src/wayland-server.pc
- src/wayland-client.pc])
+ src/wayland-client.pc
+ protocol/Makefile])
AC_OUTPUT
diff --git a/protocol/Makefile.am b/protocol/Makefile.am
new file mode 100644
index 0000000..9b57441
--- /dev/null
+++ b/protocol/Makefile.am
@@ -0,0 +1,7 @@
+if HAVE_XSLTPROC
+doc_DATA = wayland.html wayland.css
+
+wayland.html: wayland.xml protocol.xsl
+ $(AM_V_GEN)$(XSLTPROC) protocol.xsl wayland.xml > $@
+
+endif
diff --git a/protocol/protocol.xsl b/protocol/protocol.xsl
new file mode 100644
index 0000000..b2867f0
--- /dev/null
+++ b/protocol/protocol.xsl
@@ -0,0 +1,204 @@
+<?xml version="1.0" ?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+<xsl:output method="html" indent="yes" encoding="UTF-8"/>
+<xsl:preserve-space elements="copyright"/>
+<xsl:template match="/">
+<html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
+ <link href="wayland.css" rel="stylesheet" type="text/css" />
+ <title>Wayland</title>
+ </head>
+ <body>
+ <h1><img src="wayland.png" alt="Wayland logo" /></h1>
+ <h1>Wayland Protocol Specification</h1>
+
+ <!-- Copyright blurb -->
+ <xsl:apply-templates select="protocol/copyright"/>
+
+ <!-- TOC -->
+ <xsl:apply-templates select="protocol" mode="toc" />
+
+ <!-- Interface descriptions -->
+ <xsl:apply-templates select="protocol/interface" mode="interface_description" />
+
+ </body>
+</html>
+</xsl:template>
+
+<!-- Copyright blurb -->
+<xsl:template match="copyright">
+ <div>
+ <pre class="copyright">
+ <xsl:value-of select="." disable-output-escaping="yes"/>
+ </pre>
+ </div>
+</xsl:template>
+
+<!-- TOC -->
+<xsl:template match="protocol" mode="toc">
+ <div class="toc">
+ <h2>Table of Contents</h2>
+ <ul>
+ <xsl:apply-templates select="interface" mode="toc" />
+ </ul>
+ </div>
+</xsl:template>
+
+<!-- interface in TOC -->
+<xsl:template match="interface" mode="toc">
+ <li>
+ <xsl:call-template name="link">
+ <xsl:with-param name="which" select="'href'" />
+ </xsl:call-template>
+
+ <!-- request list -->
+ <xsl:if test="request">
+ <div>
+ Requests:
+ <ul>
+ <xsl:apply-templates select="request" mode="toc"/>
+ </ul>
+ </div>
+ </xsl:if>
+
+ <!-- event list -->
+ <xsl:if test="event">
+ <div>
+ Events:
+ <ul>
+ <xsl:apply-templates select="event" mode="toc"/>
+ </ul>
+ </div>
+ </xsl:if>
+
+ <!-- enum list -->
+ <xsl:if test="enum">
+ <div>
+ Enums:
+ <ul>
+ <xsl:apply-templates select="enum" mode="toc"/>
+ </ul>
+ </div>
+ </xsl:if>
+ </li>
+</xsl:template>
+
+<!--
+ Template to create a <a> tag in the form
+ #<interfacename>-<request|event>-<request/event name>
+ the '#' prefix is added if $which is 'href'
+ $which decides which attribute name (href or name) of <a> to set
+-->
+<xsl:template name="link" >
+ <xsl:param name="which" />
+ <a>
+ <xsl:attribute name="{$which}">
+ <xsl:if test="$which = 'href'">#</xsl:if>
+ <xsl:value-of select="../@name"/>
+ <xsl:text>-</xsl:text> <!-- xsl:text needed to avoid whitespace -->
+ <xsl:value-of select="name()"/>
+ <xsl:text>-</xsl:text> <!-- xsl:text needed to avoid whitespace -->
+ <xsl:value-of select="@name"/></xsl:attribute>
+ <!-- only display link text for href links -->
+ <xsl:if test="$which = 'href'">
+ <span class="mono"><xsl:value-of select="@name"/></span>
+ <xsl:if test="description/@summary"> - <xsl:value-of select="description/@summary"/></xsl:if>
+ </xsl:if>
+ </a>
+</xsl:template>
+
+<!-- requests and events in TOC -->
+<xsl:template match="request|event|enum" mode="toc">
+ <li>
+ <xsl:call-template name="link">
+ <xsl:with-param name="which" select="'href'" />
+ </xsl:call-template>
+ </li>
+</xsl:template>
+
+<!-- Interface descriptions -->
+<xsl:template match="protocol/interface" mode="interface_description">
+ <div class="interface">
+ <xsl:call-template name="link">
+ <xsl:with-param name="which" select="'name'" />
+ </xsl:call-template>
+ <h1>
+ <span class="mono"><xsl:value-of select="@name" /></span>
+ <!-- only show summary if it exists -->
+ <xsl:if test="description/@summary">
+ - <xsl:value-of select="description/@summary" />
+ </xsl:if>
+ </h1>
+ <p class="version">Version: <xsl:value-of select="@version" /></p>
+ <p><xsl:value-of select="description"/></p>
+ <xsl:if test="request">
+ <div class="requests">
+ <h2>Requests</h2>
+ <!-- Request list -->
+ <xsl:apply-templates select="request" mode="interface_description" />
+ </div>
+ </xsl:if>
+
+ <xsl:if test="event">
+ <div class="events">
+ <h2>Events</h2>
+ <!-- Event list -->
+ <xsl:apply-templates select="event" mode="interface_description" />
+ </div>
+ </xsl:if>
+
+ <xsl:if test="enum">
+ <div class="enums">
+ <h2>Enums</h2>
+ <!-- enum list -->
+ <xsl:apply-templates select="enum" mode="interface_description"/>
+ </div>
+ </xsl:if>
+ </div>
+</xsl:template>
+
+<!-- table contents for request/event arguments or enum values -->
+<xsl:template match="arg|entry">
+ <tr>
+ <td class="arg_name"><xsl:value-of select="@name"/></td>
+ <xsl:if test="name() = 'arg'" >
+ <td class="arg_type"><xsl:value-of select="@type"/></td>
+ </xsl:if>
+ <xsl:if test="name() = 'entry'" >
+ <td class="arg_value"><xsl:value-of select="@value"/></td>
+ </xsl:if>
+ <td class="arg_desc"><xsl:value-of select="@summary"/></td>
+ </tr>
+</xsl:template>
+
+<!-- Request/event list -->
+<xsl:template match="request|event|enum" mode="interface_description">
+ <div>
+ <xsl:call-template name="link">
+ <xsl:with-param name="which" select="'name'" />
+ </xsl:call-template>
+ <h3>
+ <span class="mono"><xsl:value-of select="../@name"/>::<xsl:value-of select="@name" /></span>
+ <xsl:if test="description/@summary">
+ - <xsl:value-of select="description/@summary" />
+ </xsl:if>
+ </h3>
+ <p><xsl:value-of select="description"/></p>
+ <xsl:if test="arg">
+ Arguments:
+ <table>
+ <xsl:apply-templates select="arg"/>
+ </table>
+ </xsl:if>
+ <xsl:if test="entry">
+ Values:
+ <table>
+ <xsl:apply-templates select="entry"/>
+ </table>
+ </xsl:if>
+ </div>
+</xsl:template>
+</xsl:stylesheet>
+
+<!-- vim: set expandtab shiftwidth=2: -->
diff --git a/protocol/wayland.css b/protocol/wayland.css
new file mode 100644
index 0000000..91f458a
--- /dev/null
+++ b/protocol/wayland.css
@@ -0,0 +1,41 @@
+body { padding: 0px 150px; }
+h1 { margin: 40px 0px; color: #aaa; }
+p { margin: 20px 0px; }
+h1 img { vertical-align: middle; border-width: 0px; }
+h2 { font-family: sans; color: #888; }
+h3 { font-family: sans; color: #888; font-style: italic; }
+a { color: #444; }
+a:hover { color: #888; }
+a:visited { color: #666; }
+li { margin: 10px 0px };
+table { border: 1px solid gray;}
+
+.version { font-size: small }
+div.interface { padding: 2% }
+
+div.requests div:nth-child(even) { background-color: #eeeeee; }
+div.requests div { margin-left: 2%; padding-left: 2%; }
+div.requests table { border: 0px; margin: 10px; }
+div.requests table th { padding: 5px }
+div.requests table td { padding: 5px }
+
+div.events div:nth-child(even) { background-color: #eeeeee; }
+div.events div { margin-left: 2%; padding-left: 2%; }
+div.events table { border: 0px; margin: 10px; }
+div.events table th { padding: 5px }
+div.events table td { padding: 5px }
+
+div.enums div:nth-child(even) { background-color: #eeeeee; }
+div.enums div { margin-left: 2%; padding-left: 2%; }
+div.enums table { border: 0px; margin: 10px; }
+div.enums table th { padding: 5px }
+div.enums table td { padding: 5px }
+
+.arg_name { font-family: monospace; padding:5px}
+.arg_type { font-family: monospace; color: #338833; padding:5px }
+.arg_value { font-family: monospace; color: #338833; padding:5px }
+.arg_desc { font-style: italic;padding:5px; }
+.mono { font-family: monospace; font-weight: bold; }
+
+div.toc span { font-size: 11pt; line-height: 150%; }
+div.toc li li { line-height: 100%; margin: 0%; }
--
1.7.7.6
More information about the wayland-devel
mailing list