aboutsummaryrefslogtreecommitdiffstats
path: root/doc
Commit message (Collapse)AuthorAgeFilesLines
* doc: restore missing image files in docbookHEADmainJulian Orth4 days3-0/+31
| | | | Signed-off-by: Julian Orth <ju.orth@gmail.com>
* doc: turn captions into third-level headers in bookJulian Orth4 days1-81/+81
| | | | Signed-off-by: Julian Orth <ju.orth@gmail.com>
* doc: reword docbook foreword to capture new scopeJulian Orth4 days1-2/+1
| | | | Signed-off-by: Julian Orth <ju.orth@gmail.com>
* doc: remove most content from docbookJulian Orth4 days49-6284/+0
| | | | Signed-off-by: Julian Orth <ju.orth@gmail.com>
* doc: link to website in doxygenJulian Orth4 days1-2/+2
| | | | Signed-off-by: Julian Orth <ju.orth@gmail.com>
* doc: add meson.build for bookJulian Orth4 days2-0/+60
| | | | Signed-off-by: Julian Orth <ju.orth@gmail.com>
* doc: rewrite the book forewordJulian Orth4 days1-4/+56
| | | | Signed-off-by: Julian Orth <ju.orth@gmail.com>
* doc: copy images to mdbookJulian Orth4 days40-0/+3254
| | | | Signed-off-by: Julian Orth <ju.orth@gmail.com>
* doc: add copyright notice to mdbookJulian Orth11 days1-0/+23
| | | | Signed-off-by: Julian Orth <ju.orth@gmail.com>
* doc: run docbook -> mdbook conversion toolJulian Orth11 days12-0/+1695
| | | | | | | To reproduce this commit, delete the contents of the src directory and run the tool. Signed-off-by: Julian Orth <ju.orth@gmail.com>
* doc: make DocBook validation optionalPekka Paalanen12 days1-1/+6
| | | | | | | | | | | | 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>
* doc: update GPU buffer exchange sectionJulian Orth2026-01-292-50/+99
| | | | | | Finally, a buffer exchange mechanism for the 21st century. Signed-off-by: Julian Orth <ju.orth@gmail.com>
* doc/css: adjust code and userinput stylesPekka Paalanen2026-01-221-1/+9
| | | | | | | | | | | | | | | | | | | 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>
* doc: document the Wayland XML dialectPekka Paalanen2026-01-223-0/+930
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* doc: fix a root element validation errorPekka Paalanen2026-01-221-1/+1
| | | | | | | | | | | 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>
* doc: Add a chapter on content updatesSebastian Wick2026-01-2238-0/+3645
| | | | | | | | | 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>
* doc: drop non-existing refs from CSSPekka Paalanen2026-01-211-31/+4
| | | | | | | | | | | | | | | 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>
* doc: remove unused CSS filesPekka Paalanen2026-01-214-147/+0
| | | | | | I could not find them referenced anywhere. Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
* doc: remove Revision_History.xmlPekka Paalanen2026-01-202-8/+0
| | | | | | This was never used. Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
* doc: remove Preface.xmlPekka Paalanen2026-01-203-22/+0
| | | | | | This was never filled out, so might as well just delete it. Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
* doc: validate doc XML againPekka Paalanen2025-12-291-1/+0
| | | | | | | 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>
* doc/xsl: rearrange member doc generationPekka Paalanen2025-12-291-13/+18
| | | | | | | | | | | | | | | | | | | | 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>
* build/doc: explain two XML conversionsPekka Paalanen2025-12-291-4/+8
| | | | | | | | | | 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>
* doc/xsl: include static inline functionsPekka Paalanen2025-12-291-2/+10
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* doc: fix Xwayland image validityPekka Paalanen2025-12-291-7/+5
| | | | | | | | | | | | | | | | 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>
* doc: reinstate image mapsPekka Paalanen2025-12-292-5/+14
| | | | | | | | 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>
* doc/xsl: fix malformed <variablelist>Pekka Paalanen2025-12-291-5/+7
| | | | | | | | | | | | | | | | | | | | | | | | | 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>
* doc: remove HTML_TIMESTAMPPekka Paalanen2025-12-291-1/+0
| | | | | | | | | | | | 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>
* doc: Refactor the build system for complete build dir docsSebastian Wick2025-11-2737-162/+134
| | | | | | | | 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>
* doc: add a section on color managementPekka Paalanen2025-06-123-0/+141
| | | | | | | | I think the docbook deserves an introduction to how color management is designed in Wayland, aimed at people who are familiar with pixels but new to the topic. Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
* doc: Further explain typical display socket lookupManuel Stoeckl2025-06-081-1/+3
| | | | | | | | This change mentions the case where WAYLAND_SOCKET is used, which helps people avoid just testing 'getenv(WAYLAND_DISPLAY)' to see if a Wayland compositor is available; Signed-off-by: Manuel Stoeckl <code@mstoeckl.com>
* Fix typosTobias Stoeckmann2025-05-201-1/+1
| | | | | | Typos found with codespell and during code audit. Signed-off-by: Tobias Stoeckmann <tobias@stoeckmann.org>
* connection: Reject strings containing NUL bytesDemi Marie Obenour2024-08-181-1/+2
| | | | | | | | | | | | libwayland cannot construct these messages as it uses strlen() to determine string lengths. libwayland is also guaranteed to misinterpret these messages, since message handlers only get a pointer and no length. Therefore, reject strings containing NUL bytes. Also remove a redundant check from the unmarshalling code. The zero-length case has already been checked for. Signed-off-by: Demi Marie Obenour <demi@invisiblethingslab.com>
* doc: Require strings to be UTF-8Sebastian Wick2024-08-091-3/+3
| | | | | | | Nothing checks this yet but this gives us the opportunity to do so when we want. Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
* doc: Improve wording for packed IDsMikhail Gusarov2024-01-221-3/+4
| | | | | | | | | | | | "is incompatible with the implementation in libwayland" is a common source of confusion as evidenced by repeated discussions in IRC channel. Improve the wording by making clear that - packing IDs is a protocol requirement - there are implementations (including libwayland) that enforce it Signed-off-by: Mikhail Gusarov <dottedmag@dottedmag.net>
* Document which type are nullable, and wire format for null valueIan Douglas Scott2022-07-141-2/+3
| | | | Signed-off-by: Ian Douglas Scott <idscott@system76.com>
* docs/publican: ensure output encoding is UTF-8Simon Ser2022-05-111-0/+1
| | | | | | | | | Without this, DocBook picks the output encoding and on some setups we end up with ISO-8859-1. Tested by booting a fresh Alpine VM, verifying that the generated HTML is using the incorrect charset, applying the patch, and verifying that the generated HTML is fixed. Signed-off-by: Simon Ser <contact@emersion.fr>
* build: sanity check optionsSimon Ser2022-05-101-0/+4
| | | | | | | | Fail when tests/documentation is enabled without libraries. Fail when neither scanner nor libraries is enabled, because we don't build anything in that case. Signed-off-by: Simon Ser <contact@emersion.fr>
* meson: use absolute paths for doxygen stamp filesSimon Ser2022-02-051-2/+4
| | | | | | The relative paths are incorrect when running as a subproject. Signed-off-by: Simon Ser <contact@emersion.fr>
* meson: use project build root for doxygen outputSimon Ser2022-02-051-1/+1
| | | | | | | | | | | | meson.build_root() returns the parent's build directory if Wayland is a subproject. This fails with: error: tag OUTPUT_DIRECTORY: Output directory '<parent-build-dir>/doc/doxygen' does not exist and cannot be created Instead, use meson.project_build_root(), which returns the subproject's build directory. Signed-off-by: Simon Ser <contact@emersion.fr>
* build: explicitly set check arg in run_command()Simon Ser2022-02-021-1/+1
| | | | | | | | | | | Fixes the following warning: WARNING: You should add the boolean check kwarg to the run_command call. It currently defaults to false, but it will default to true in future releases of meson. See also: https://github.com/mesonbuild/meson/issues/9300 Signed-off-by: Simon Ser <contact@emersion.fr>
* doc: Clarify that null terminator is included in string lengthMikhail Gusarov2021-12-181-3/+3
| | | | Signed-off-by: Mikhail Gusarov <dottedmag@dottedmag.net>
* doc: Clarify position of file descriptors in the streamMikhail Gusarov2021-12-121-0/+15
| | | | | | | | | | The specification left the position and order of file descriptors unspecified. Specify that - order of file descriptors is maintained - position of file descriptors is bounded, but loose Signed-off-by: Mikhail Gusarov <dottedmag@dottedmag.net>
* build: drop autotoolsSimon Ser2021-03-053-283/+0
| | | | | | Meson now replaces autotools. Signed-off-by: Simon Ser <contact@emersion.fr>
* doc: fix typosMaxime Roussin-Bélanger2020-12-174-6/+6
|
* doc: make reproducibleAlyssa Ross2020-10-291-0/+1
| | | | | | | This setting makes Docbook section IDs consistent, and should allow Wayland builds that include documentation to be fully reproducible. Signed-off-by: Alyssa Ross <hi@alyssa.is>
* doc: Document libwayland-cursor with mesonEmmanuel Gil Peyrot2020-06-052-1/+12
| | | | Signed-off-by: Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
* doc: Document libwayland-cursor with autotoolsEmmanuel Gil Peyrot2020-06-051-1/+10
| | | | Signed-off-by: Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
* doc: fix and clarify pointer image behaviourYann Dirson2020-06-031-4/+8
| | | | Signed-off-by: Yann Dirson <ydirson@free.fr>
* Replace initial 8 spaces with a tab for all xml filesPeter Hutterer2020-04-296-31/+31
| | | | | | | | | This is the style used in wayland.xml which is the only file we really care about for git blame information. So let's adjust all others to that style for consistency and fix editorconfig to avoid messing this up in the future. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
generated by cgit v1.2.3-70-g09d2 (git 2.53.0) at 2026-02-16 06:52:51 +0000