[PATCH RFC] protocol: add xslt stylesheet to prettify the protocol
Kristian Høgsberg
hoegsberg at gmail.com
Fri Feb 24 07:04:32 PST 2012
On Fri, Feb 24, 2012 at 2:42 AM, Peter Hutterer
<peter.hutterer at who-t.net> wrote:
> 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.
That is really cool, that's pretty much exactly what I had in mind. I
found a pdf generated by publican, it looks like this:
http://jfearn.fedorapeople.org/en-US/Publican/2.6/pdf/Users_Guide/Publican-2.6-Users_Guide-en-US.pdf
which is pretty cool. There are various other themes (brand packages)
available so we could probably create our own eventually. And in any
case, how we go from docbook to pdf/html/etc is something we could
change later, but I don't see a problem with publican (*suppressing
comment about source code in svn*).
Thanks,
Kristian
> 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