[PATCH RFC] protocol: add xslt stylesheet to prettify the protocol
Kristian Høgsberg
hoegsberg at gmail.com
Thu Feb 23 14:28:49 PST 2012
On Thu, Feb 23, 2012 at 4:26 PM, Kristian Hoegsberg <hoegsberg at gmail.com> wrote:
> 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.
I put it here:
http://wayland.freedesktop.org/protocol.html
Kristian
> 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