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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
"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>
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>
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.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>
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>
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>
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>
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>
There is only one page written. Having manually-written man pages duplicates
information with doc comments. Besides, man pages are already generated by
Doxygen.
Signed-off-by: Simon Ser <contact@emersion.fr>
Closes: https://gitlab.freedesktop.org/wayland/wayland/-/issues/156
Meson is a next generation build system, simpler than Autotools and also faster
and more portable. Most importantly, it will make integrating ASan easier in
CI.
The goal is to maintain feature parity of the Meson build with the
Autotools build, until such time when we can drop the latter.
Add a script which generates the desired Doxygen configuration for our various
output formats and executes it using that configuration. This is not something
Meson can or should do.
Fixes: https://gitlab.freedesktop.org/wayland/wayland/issues/80
[daniels: Changed to bump version, use GitLab issues URL, remove header
checks not used in any code, remove pre-pkg-config Expat
support, added missing include paths to wayland-egl and
cpp-compile-test, added GitLab CI.
Bumped version, removed unnecessary pkg-config paths.]
[daniels: Properly install into mandir/man3 via some gross
paramaterisation, generate real stamp files.]
Pekka:
- squashed patches
- removed MAKEFLAGS from meson CI
- remove unused PACKAGE* defines
- fix up scanner dependency handling
- instead of host_scanner option, build wayland-scanner twice when cross-compiling
- changed .pc files to match more closely the autotools versions
- reorder doxygen man sources to reduce diff to autotools
- fix pkgconfig.generate syntax warnings (new in Meson)
- bump meson version to 0.47 for configure_file(copy) and run_command(check)
- move doc tool checks into doc/meson.build, needed in more places
- make all doc tools mandatory if building docs
- check dot and doxygen versions
- add build files under doc/publican
- reindent to match Weston Meson style
Simon:
- Remove install arg from configure_file
- Don't build wayland-scanner twice during cross-build
- Fix naming of the threads dependency
- Store tests in dict
- Add missing HAVE_* decls for functions
- Remove unused cc_native variable
- Make doxygen targets a dict
- Make dot_gv a dict
- Use dicts in man_pages
- Make decls use dicts
- Make generated_headers use dicts
- Align Meson version number with autotool's
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Signed-off-by: Simon Ser <contact@emersion.fr>
Make considers a variable called VPATH when trying to satisfy
dependencies, e.g. for a target 'foo', it will consider the target
extant if VPATH is '../../bar' and '../../bar/foo' exists.
Part of the doc build, the '$(alldirs)' target, exists to create the
target directories if they do not exist. For example, before generating
xml/wayland-architecture.png, it will ensure the 'xml' target is
considered up-to-date thanks to the target dependency.
Creating $(srcdir)/doc/doxygen/xml thus means that the 'xml' dependency
will be satisfied, so we'll never create the output directory, and the
doc build will fail.
Change the alldirs target list to be absolute paths, so VPATH will not
be consulted and defeat the entire point of what we're trying to do.
This fixes the Meson build, where we later create
doc/doxygen/xml/meson.build.
Signed-off-by: Daniel Stone <daniels@collabora.com>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Out of the context it is reasonably clear that "hw" is indeed an abbreviation
for "hardware".
The use of "hw" in this place doesn't seem to be a stylistic choice, but rather
an oversight.
Signed-off-by: Paul Scharnofske <asynts@gmail.com>
When wayland-scanner encounters a new_id field with no corresponding
interface name defined, instead of emitting a function whose signature
lines up with the usual case (a uint32_t ID), it adds the interface name
as a string and the version number so that the interface can be
identified from the protcol message.
Without docs, this was previously left for the interprid wire protocol
implementor (e.g. me an hour ago) to discover when Wayland clients send
them apparently bogus messages.
I would have preferred if a different primitive type were used here
(e.g. typed_new_id) to reflect the fact that the wire protocol is
different, but I felt it unwise to add a new primitive to wayland.xml in
$current_year.
The docbook-xsl package includes all the stylesheets required to build
the docs without internet access.
Test:
One way to emulate missing style sheets is to move /etc/xml/catalog file
to a different location. Doing so should cause configure to fail with
"checking for docbook stylesheets... no"
v2: add AC_MSG_RESULT (Pekka)
Signed-off-by: Harish Krupo <harishkrupo@gmail.com>
Use a more official one, served over HTTP rather than FTP.
Reviewed-by: Matheus Santana <embs@cin.ufpe.br>
Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Gitlab expects a CONTRIBUTING.md in the root directory, so move our
guide there.
Conversion to proper markup is a follow-up patch.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Daniel Stone <daniels@collabora.com>
This is a rough intro to what Xwayland is and does, with just one
implementation detail so far (Window identification).
I paid no attention to formatting details, those can be polished in
follow-ups. I just want the prose out.
I also just quickly whacked up the diagram, would be happy to see
someone replace it with a nicer one. I just didn't have time to learn
dot for now.
v2:
- typo fix
- rephrase "talking to hardware" as "driving the displays"
- mention circular dependency in intro
- add section to explain rootless and rootful modes
- remove paragraph about Xwayland protocol usage
- move TBD part to the end under a new section header
v3:
- use "advantage" and "disadvantage" instead of "pro" and "con"
- slight rewording on rootful mode and rootless mode paragraphs
- removed the paragraph about the lack of shell and special Wayland
protocol extensions
- removed the commented out list of ideas to write
v4:
- typo fixes pointed out by Yong
Cc: Olivier Fourdan <ofourdan@redhat.com>
Cc: Jonas Ådahl <jadahl@gmail.com>
Cc: Daniel Stone <daniel@fooishbar.org>
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
In order to support system compositor instances, it is necessary to
allow clients' wl_display_connect() to find the compositor's listening
socket somewhere outside of XDG_RUNTIME_DIR. For a full account, see
the discussion beginning here:
https://lists.freedesktop.org/archives/wayland-devel/2017-November/035664.html
This change adjusts the client-side connection logic so that, if
WAYLAND_DISPLAY is formatted as an absolute pathname, the socket
connection attempt is made to just $WAYLAND_DISPLAY rather than
usual user-private location $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY.
This change is based on Davide Bettio's submission of the same concept
at:
https://lists.freedesktop.org/archives/wayland-devel/2015-August/023838.html.
v4 changes:
* Improved internal comments and some boundary-condition
error checks in test case.
* Refer to compositor as "Wayland server" rather than "Wayland
display" in wl_display_connect() doxygen comments.
* Remove redundant descriptions of parameter-interpretation
mechanics from wl_display_connect() manpage. Reworked things
to make it clear that 'name' and $WAYLAND_DISLAY are each
capable of encoding absolute server socket paths.
* Remove callout to reference implementation behavior in protocol
documented. In its place there is now a simple statement that
implementations can optionally support absolute socket paths.
v3 changes:
* Added test case.
* Clarified documentation to note that 'name' parameter to wl_display_connect()
can also be an absolute path.
v2 changes:
* Added backward incompatibility note to wl_display_connect() manpage.
* Rephased wl_display_connect() manpage changes to precisely match actual
changed behavior.
* Added mention of new absolute path behavior in wl_display_connect()
doxygen comments.
* Mentioned new absolute path interpretation of WAYLAND_DISPLAY in
protocol documentation.
Signed-off-by: Matt Hoosier <matt.hoosier@gmail.com>
Acked-by: Jonas Ådahl <jadahl@gmail.com>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
There is a lot of files created with .so links to non-installed
files, making most of installed pages useless. The files
referenced in .so links are not suitable for installation nor
do they contain any useful information for them to be worth
fixing.
Signed-off-by: Armin Krezović <krezovic.armin@gmail.com>
Acked-by: Daniel Stone <daniels@collabora.com>
