[PATCH RFC] protocol: add xslt stylesheet to prettify the protocol
Peter Hutterer
peter.hutterer at who-t.net
Fri Feb 24 21:54:52 PST 2012
On 25/02/12 01:04 , Kristian Høgsberg wrote:
> 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*).
I should probably also note that jfearn (who's document you linked to)
sits about 3m away from me in the office. so if need be, there is
publican insider knowledge available.
I didn't point this out before but the source for the above link is in a
higher-level directory
http://people.freedesktop.org/~whot/Wayland/en-US/, the build was a
simple call to "publican build".
http://people.freedesktop.org/~whot/Wayland/en-US/Architecture.xml is
the source for the architecture chapter,
http://people.freedesktop.org/~whot/Wayland/en-US/Protocol.xml
is autogenerated from protocol/wayland.xml.
Cheers,
Peter
>
> 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