[PATCH RFC] protocol: add xslt stylesheet to prettify the protocol

[Peter Hutterer]

On Tue, Feb 28, 2012 at 09:14:18AM -0500, Kristian Høgsberg wrote:
> 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.

yes, I've fixed a few things up now, patches will come in a second
 
Cheers,
  Peter