Wayland clients should not assume the format list will not grow, or
assume the format descriptions in the Wayland protocol are complete.
(The latter fact is clear for descriptionless enum entries like
XRGB8888_A8; but, for example, the full XRGB16161616F format
description explicitly requires IEEE 754 binary16 floats instead
of bfloat16 or ARM's alternative half precision variant.)
Signed-off-by: Manuel Stoeckl <code@mstoeckl.com>
Before, it worked if the client did set a queue on the proxy before any event was received.
Now we have the "warning: queue xxx destroyed while proxies still attached", then a crash if one of
the proxies is used to create a proxy.
Fixes: 674145dc3f ("client: Track the proxies attached to a queue")
Fixes: 0ba650202e ("client: Warn when a queue is destroyed with attached proxies")
Signed-off-by: Loïc Yhuel <loic.yhuel@softathome.com>
wl_region is not a frozen interface and therefore should have the
version of the parent object, wl_compositor.
Signed-off-by: Julian Orth <ju.orth@gmail.com>
This new request allows clients to get per-surface-commit buffer
release events. It supersedes wl_buffer.release.
This functionality is also available via the linux-explicit-synchronization
protocol, but requires the compositor to also support Linux
synchronization fences. Adding this new request to the core protocol
allows any compositor to implement the functionality.
Signed-off-by: Simon Ser <contact@emersion.fr>
Closes: https://gitlab.freedesktop.org/wayland/wayland/-/issues/203
References: https://gitlab.freedesktop.org/wayland/wayland/-/issues/46
It turns out that changes in the building environment, the version of
Doxygen being a prime suspect, can break the validation. Invalid DocBook
XML does lead to likely broken documentation, but perhaps it is better
than failing to build or having to disable documentation completely.
CI turns DocBook validation on, because the CI environment is stable and
known, and we do want to catch mistakes in hand-written DocBook files.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
The file used a mixture of tabs and spaces. According to .editorconfig,
all xml files should be indented with spaces, so this seems like the
correct choice if we wanted to reindent the file.
I used vim's :retab command to expand all tabs to 8 spaces.
Signed-off-by: Julian Orth <ju.orth@gmail.com>
I don't know why <code> was defined to be bold, it looks bad to me. The
same with <synopsis> which would inherit bold from <dt> when used inside
a variablelist term. So, to make the code snippets look better, force
them to use normal weight.
<userinput> should differentiate from normal code somehow, and italic
seems fine for it.
<literal> already has bold, and I think it's fine, so no need to touch
it.
These changes are mainly for the new XML dialect documentation chapter.
I didn't notice anything changing for the older or generated parts of the
docs.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
Document the XML tags used to describe Wayland protocols. Previously we
only had the informal specification in the Protocol chapter, and the
DTD. Better late than never.
I have looked into wayland-scanner and libwayland for various
limitations documented here possibly for the first time. I have also
forbid things that are not in use or are known broken, including
unspecified interface for a new_id in an event, or an object argument
with an unspecified interface.
I did investigate writing a RELAX NG compact schema for Wayland and
documenting everything there, then generating DocBook XML from it.
However, it seems generating documentation from schema is actually
really complicated. I found these tools:
- xs3p stylesheet: website looks dead, though Sourceforge still
has it. Produces XHTML, not DocBook. Has an unfamiliar license.
- xsddoc: the authors wrote that XSLT is not really sufficient, so they
abandoned this approach and went for Java to create xnsdoc.
- xnsdoc: seems to be proprietary licensed, although one could ask for a
free license for a FLOSS project.
All in all, it seems to be much easier to just write the documentation
in DocBook, copying the strcture from the DTD manually, than to generate
it. It's not doing to change often, anyway. It also allowed me to
leverage DocBook syntax in full.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Once I got XML validation working in VSCode, it found an error:
Document root element "preface", must match DOCTYPE root "chapter".
I guess DOCTYPE declares which element is used as root in the
file.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
It's unlikely that protocols/wayland.xml sees much change anymore, but
files in doc/ might. To make writing documentation easier, stick to an
unsurprising indentation style that is already in use in
wayland-protocols and for the XSL files.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
The behavior of content updates, specifically in combination with sync
subsrufaces and constrains can become quite complicated. This introduces
a chapter in the wayland book which explains the behavior of the core
specification in this regard, and shows examples.
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
The protocol currently is in a state where we define that commits create
content updates and they are queued up until they are applied, and the
old view that commit applies the state or caches it in the parent state.
This commit moves the protocol completely to the new model which retains
the old behavior when no constraints are being used but allows for
constraints to be used to hold back a group of synchronized content
updates.
To convince yourself that this indeed retains the original behavior I
suggest to play around with a few examples and look at the resulting
graphs, as is done here:
https://gitlab.freedesktop.org/wayland/wayland/-/issues/457#note_2403135
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
It seems these images were never in the repository. They might have
existed when the documentation was still built with Publican, but since
the migration to xmlto I think these have all been just 404.
Removing div.warning:before, div.note:before and div.important:before
would actually delete some unexpected empty space if the Docbook
<warning>, <note> or <important> elements were used. They are not used
now, but may be in the future.
.draft is never used, so I replaced the image with whatever.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Artifacts include the prefix directory, but it was empty: we
weren't running the install step. Run it to align Debian with
FreeBSD.
This allows reviewers to check the HTML documentation output.
Signed-off-by: Simon Ser <contact@emersion.fr>
The exact type behind these might depend on the architecture. For
instance, on ARMv7, struct timeval fields are long long int instead
of long int:
FAILED: tests/libtest-runner.a.p/test-compositor.c.o
cc -Itests/libtest-runner.a.p -Itests -I../tests -I. -I.. -Isrc -I../src -fdiagnostics-color=always -fsanitize=address,undefined -fno-omit-frame-pointer -D_FILE_OFFSET_BITS=64 -Wall -Winvalid-pch -Wextra -Werror -std=c99 -O0 -g -D_POSIX_C_SOURCE=200809L -Wno-unused-parameter -Wstrict-prototypes -Wmissing-prototypes -fvisibility=hidden -fPIC -pthread -MD -MQ tests/libtest-runner.a.p/test-compositor.c.o -MF tests/libtest-runner.a.p/test-compositor.c.o.d -o tests/libtest-runner.a.p/test-compositor.c.o -c ../tests/test-compositor.c
../tests/test-compositor.c: In function 'get_socket_name':
../tests/test-compositor.c:95:60: error: format '%ld' expects argument of type 'long int', but argument 5 has type '__time64_t' {aka 'long long int'} [-Werror=format=]
95 | snprintf(retval, sizeof retval, "wayland-test-%d-%ld%ld",
| ~~^
| |
| long int
| %lld
96 | getpid(), tv.tv_sec, tv.tv_usec);
| ~~~~~~~~~
| |
| __time64_t {aka long long int}
../tests/test-compositor.c:95:63: error: format '%ld' expects argument of type 'long int', but argument 6 has type '__suseconds64_t' {aka 'long long int'} [-Werror=format=]
95 | snprintf(retval, sizeof retval, "wayland-test-%d-%ld%ld",
| ~~^
| |
| long int
| %lld
96 | getpid(), tv.tv_sec, tv.tv_usec);
| ~~~~~~~~~~
| |
| __suseconds64_t {aka long long int}
Signed-off-by: Simon Ser <contact@emersion.fr>
This fixes a validation error in the documentation which are not fatal.
The idea is the same as in 12ec67a ("server: document listener fields
and a vfunc"), which seems to have missed the reference to the
wl_protocol_logger_func_t from the note in wl_log_func_t.
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
Now that all XML validation errors have been fixed, it is time to turn
the validation back on to make sure the errors stay out.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
Creating an empty <variablelist> is illegal. This can already be seen in
the XSL anywhere it is generated. The used XSL programming pattern
requires the look-up conditions to be repeated between the <xsl:if> and
<xsl:apply-templates> tags. Usually this is not a problem, but the
conditions for memberdef is too much to copy around.
The conditions between the if and the apply-templates have already
diverged, causing validation errors (that are currently suppressed).
Rearrange the XSL so that the applicable memberdef are stored in a
variable, so that both the if and the apply-templates operate on the
exact same set of matches. This avoids emitting empty <variablelist>.
As a result, the members of structures wl_argument, wl_interface,
wl_message, and wl_listener newly appear in the documentation.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
Adding these simple documentation comments allows us to have meaningful
link targets in the generated API documentation. That will help getting
rid of broken links which cause XML validation to fail.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
Now that I figured out what these do, I might as well add comments about
it for others.
The target names are changed to be more descriptive of what the target
does.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
When generating documentation, xmllint complained:
element link: validity error : IDREF attribute linkend references an
unknown ID "Server-structwl__signal_1afe73f44f7f1b517c9c0ba90829c93309"
element link: validity error : IDREF attribute linkend references an
unknown ID "Server-structwl__signal_1afe73f44f7f1b517c9c0ba90829c93309"
element link: validity error : IDREF attribute linkend references an
unknown ID "Server-structwl__signal_1aa8bcd3b8e250cfe35ed064d5af589096"
These were referring to wl_signal_add() and wl_signal_emit() I think,
which are static inlines in a public header.
The XSLT ignored static functions, probably assuming that they cannot be
public API. Internal (static) functions are present in the Doxygen XML,
so they do need to be excluded. Now we include static functions if their
body is in a header. We de not scan private headers, so they must be
public API.
Comparing the final generated HTML documentation, these functions are
added to both Client and Server APIs:
wl_fixed_to_double
wl_fixed_from_double
wl_fixed_to_int
wl_fixed_from_int
These functions are added to the Server API:
wl_signal_init
wl_signal_add
wl_signal_get
wl_signal_emit
Signed-off-by: Pekka Paalanen <pq@iki.fi>
xmllint complained:
element imageobjectco: validity error : Element imageobjectco content
does not follow the DTD, expecting (areaspec , imageobject ,
calloutlist*), got (imageobject )
This image has no callouts (clickable items explained in the text), so
it must not use the tags that assume callouts.
I probably cargo-culted this from the X11 and Wayland diagrams which
have callouts when writing Xwayland.xml.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
$ meson compile -C build -v xml-Server-doc
INFO: autodetecting backend as ninja
INFO: calculating backend command to run: /usr/bin/ninja -C /home/pq/git/wayland/build -v doc/doxygen/xml/Server/combine.xslt doc/doxygen/xml/Server/index.xml
ninja: Entering directory `/home/pq/git/wayland/build'
[1/1] /home/pq/git/wayland/doc/doxygen/gen-doxygen.py --builddir=doc/doxygen/xml/Server --section=Server --output-format=xml doc/doxygen/wayland.doxygen ../doc/doxygen/../../src/wayland-util.h ../doc/doxygen/../../src/event-loop.c ../doc/doxygen/../../src/wayland-server.c ../doc/doxygen/../../src/wayland-server.h ../doc/doxygen/../../src/wayland-server-core.h ../doc/doxygen/../../src/wayland-shm.c
/home/pq/git/wayland/src/wayland-server-core.h:394: warning: explicit link request to 'wl_signal_add' could not be resolved
I don't know why, but the "explicit link" mark-up fails, while the
automatic link mark-up works. This warning disappears.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
This fixes the errors during the compilation of Architecture.xml that
the .map files cannot be found. As a result, the architure diagrams
become clickable in the HTML document once again.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
For all requests and events that do not have any arguments, enabling XML
validation would lead to many errors like this:
/home/pq/git/wayland/build/doc/publican/Wayland.xml:5287: element
variablelist: validity error : Element variablelist content does not
follow the DTD, expecting (blockinfo? , (title , titleabbrev?)? ,
(caution | important | note | tip | warning | literallayout |
programlisting | programlistingco | screen | screenco | screenshot |
synopsis | cmdsynopsis | funcsynopsis | classsynopsis | fieldsynopsis |
constructorsynopsis | destructorsynopsis | methodsynopsis | formalpara |
para | simpara | address | blockquote | graphic | graphicco |
mediaobject | mediaobjectco | informalequation | informalexample |
informalfigure | informaltable | anchor | bridgehead | remark |
highlights | abstract | authorblurb | epigraph | indexterm | beginpage)*
, varlistentry+), got
The reason is that a <variablelist> without any <varlistentry> inside it
is illegal.
If there are no <arg> at all, do not emit the list paragraph.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
to fix the Doxygen message:
warning: Tag 'HTML_TIMESTAMP' at line 8 of file '-' has become
obsolete. To avoid this warning please remove this line from your
configuration file or upgrade it using "doxygen -u"
Observed with Doxygen 1.9.8.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
The XSL files are mostly indented with 2 spaces. Using the default
editorconfig rules in VSCode constantly tries to mix in tabs. Add the
2-space rule for .xsl files to fix this.
The .xsl files, like .xml files, use a tab character in place of 8
spaces. This complicates things, and the new rule will prefer just
spaces. To keep the existing sometimes-tab-indented code looking right,
the tab width must be explicitly set to 8.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
