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>
The event loop timer test has very precise sequencing and timing
constraints, which make it difficult to pass reliably on loaded systems.
Since this test isn't providing much value, remove it to prevent the
erroneous errors.
Signed-off-by: Joshua Watt <JPEWhacker@gmail.com>
By structuring things differently, it becomes possible to have a
complete build of the docs in the build dir, without having to install
anything.
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
This version will be required in the next commit.
Bumps the CI image to get the required version from the debian package
instead of from pip.
Removes the bindir builtin directory from pkgconfig.generate() which is
deprecated since 0.62.0. It will be automatically included when
referenced.
Use `meson setup` everywhere instead of relying on deprecated automatic
detection of the setup command.
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
This commit defines a new discard_constraints request. This request is
intended to be used by clients that use the wp-fifo and wp-commit-timing
protocols for frame pacing but want to be able to respond immediately to
resize requests.
Consider a client using wp-fifo presenting to a display with refresh
rate 1 (unitless). The client has allocated 3 buffers O1, O2, and O3.
The client receives a resize request at time T+2. The client allocates
new buffers N1, N2, and N3 with the new size.
The following sequence of requests and events can be observed in
WAYLAND_DEBUG output:
T+0: release(O1)
T+0: -> attach(O1)
T+1: release(O2)
T+1: -> attach(O2)
T+2: release(O3)
T+2: -> attach(O3)
T+2: resize request
T+2: -> attach(N1)
T+2: -> attach(N2)
T+2: -> attach(N3)
T+3: release(O1)
T+4: release(O2)
T+5: release(O3)
T+6: release(N1)
T+6: -> attach(N1)
Due to the lack of backpressure, all newly created buffers are attached
immediately at T+2. Since O1, O2, and O3 are still equeued, the content
update containing N1 will only be applied at T+5 and therefore cannot be
released any earlier than T+6, creating a presentation bubble between
T+3 and T+6.
Furthermore, even if the client did not attach N2 immediately at T+2, N1
would not become visible until T+5, which means that the client
effectively does not respond to the resize request until T+5.
This effect can be observed with the following command:
vkcube --present_mode 2
Resizing the application window causes easily visible stutters on
displays with low refresh rates.
Note that the queue can grow unbounded if the client receives an
unbounded number of resize requests between refresh cycles.
To remedy this, this commit allows the client to hint to the compositor
that it should discard all existing constraints, if able. Since
compositor architectures might impose limitations on which constraints
the compositor is able to discard, this is left to compositor policy. It
is expected that most compositors should be able to discard wp-fifo and
wp-commit-timing constraints. Some compositors might be able to discard
buffer constraints if the buffer in question is superseded by another
buffer in a later content update.
I had considered creating per-interface requests, such as
wp_fifo_v1.discard_constraints, however, such constraints are often
created by WSI layers and an update of the WSI layer could introduce new
constraints that the client would not be aware of. To discard all
constraints, the WSI layer would have to invoke these requests and there
are no APIs for the client to communicate to the WSI layer which
behavior is desired.
Signed-off-by: Julian Orth <ju.orth@gmail.com>
As well as wl_display_dispatch_queue_pending_single.
The motivation is writing libwayland bindings for a dynamic language
with exceptions/non-local returns. Since it is invalid for a
wl_dispatcher_func_t callback provided to libwayland to not return,
there is no way to prevent dispatching of further events in the case of
an exception in the dynamic language event handler.
Furthermore, since creating/destroying Wayland objects in an event
handler affects the dispatching of subsequent events by libwayland,
it is not possible to collect Wayland events in a queue outside
libwayland and dispatch them one-by-one after
wl_display_dispatch_pending() returns.
Adding libwayland API to dispatch at most one pending event solves this
problem cleanly. The bindings can have libwayland dispatch a single
event, wait for wl_display_dispatch_pending_single() to return, run the
dynamic language event handler (which may longjmp away), and continue
the loop for as long as there are more events to dispatch.
References: https://codeberg.org/ifreund/janet-wayland
Signed-off-by: Isaac Freund <mail@isaacfreund.com>
