[PATCH RFC] protocol: add xslt stylesheet to prettify the protocol

Kristian Hoegsberg hoegsberg at gmail.com
Thu Feb 23 13:26:23 PST 2012


On Thu, Feb 23, 2012 at 03:58:37PM +1000, Peter Hutterer wrote:
> 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.

That is very nice.  As part of 1.0, we need to figure out a way to
combine the protocol and the spec document into something like docbook
and make pdf and html versions.  I don't think we want to stick with latex.

Anyway, for now, this is great and definitely highlights the missing
documentation.  Committed, and I'll try to setup a push hook to put
the html on the web site.

thanks,
Kristian

>  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
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel


More information about the wayland-devel mailing list