[PATCH RFC] protocol: add xslt stylesheet to prettify the protocol
Peter Hutterer
peter.hutterer at who-t.net
Thu Feb 23 23:42:02 PST 2012
On Thu, Feb 23, 2012 at 04:26:23PM -0500, Kristian Hoegsberg 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.
I've played around a bit today and the result is this:
http://people.freedesktop.org/~whot/Wayland/tmp/en-US/html/
I've copied over the Wayland Architecture page from the current website just
to have a proper chapter in there, the protocol documentation generated from
a modification of the xsl.
The whole lot is generated with publican, I've been assured that publican
can also produce pdf, epub, etc. And the source was relatively trivial, even
for someone with little docbook experience.
With a bit of targeted styling, I think this could become quite useful but
before I invest any more time in this I'd like to hear a yay/nay.
Cheers,
Peter
> 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