Wayland 1.25 was recently released. The repository holds the fundamental interface definitions (wayland.xml) for the protocol, the inter-process communication library (libwayland), and some documentation that we used to call "the Wayland DocBook", for lack of a better name. I want to highlight the documentation changes in this release because the documentation had not been touched much in years.

Three new chapters were written for the documentation:

• Message Definition Language finally provides an official specification of the Wayland XML dialect; what XML tags and attributes exist and what they mean. This should help protocol authors and especially developers of code generation tools. Previously one had to infer things from wayland-scanner source code and the DTD. Adding new XML features is also easier, given that there is a specification to edit. I authored this chapter.

• Content Updates completely re-writes how we think about updates to wl_surface state and image contents. Also wayland.xml was updated to follow the new terminology. The earlier descriptions about how sub-surface updates work (written by me more than a decade ago) were inadequate so much that they were outright incorrect for nested sub-surfaces. Now we have a solid theory on how things should work with sub-surfaces. More work will be needed to cater for commit-timing and fifo protocols though. Sebastian Wick authored this chapter.

• Color Management chapter is a 10 km altitude overview of how we designed color management to work on Wayland. More details can be found in the color-and-hdr repository, particularly the design goals, comparison with X11, and the proposed compositor color management model. I wrote this chapter.

That bundle of documentation, published at wayland.freedesktop.org, was written in DocBook XML. I would presume that this format in itself was already a high barrier to contributing to the documentation. Julian Orth proposed to convert the documentation into mdBook instead, which you might recognize from the Rust documentation. The temporary conversion tool can be found in the git history. Now the Wayland documentation has a modern look, and being in Markdown makes it easy to edit.

Some DocBook still remains. These are the parts that the documentation build generates from wayland.xml and Doxygen XML output with custom XSLT scripts. I hope we have the opportunity to convert these as well into a better form.

Related Posts

Weston 15.0 is here: Lua shells, Vulkan rendering, and a smoother display stack

12 years of incubating Wayland color management

Wine on Wayland: A year in review (and a look ahead)

Related Posts

Weston 15.0 is here: Lua shells, Vulkan rendering, and a smoother display stack

12 years of incubating Wayland color management

Wine on Wayland: A year in review (and a look ahead)