[PATCH RFC] protocol: add xslt stylesheet to prettify the protocol
Kristian Høgsberg
hoegsberg at gmail.com
Tue Feb 28 06:14:18 PST 2012
2012/2/25 Peter Hutterer <peter.hutterer at who-t.net>:
> 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.
Are the scripts you used to convert the protocol to docbook and merge
it all into one document in a state that you can share them? I'd like
to get this into git and automated so we can start building this
regularly.
thanks,
Kristian
>
> 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