Wayland developer's documentation: miscellaneous updates

documentation/src/wayland.dox

@@ -28,14 +28,21 @@ CSD and SSD compositors. It bundles a library called \c libdecor charged of dete
 a CSD or a SSD compositor is active, and of drawing titlebars in the first case.
 
 Wayland is divided in various protocols that a given compositor may or may not support,
-although they all support the \c core protocol. The core protocol allows a client app
+although they all support the \c core protocol. Each protocol adds functionality not available
-to discover what protocols its compositor supports. Protocols can be stable,
+in the core protocol. The core protocol allows a client app
+to discover what protocols the connected compositor supports. Protocols can be stable,
 which means they have a defined API that will not change but can be expanded, or unstable.
 For example, mapping a window on a display is not done by the core protocol but by the
 <tt>xdg shell</tt> protocol which is stable. Unstable protocols are named beginning with
 letter 'z'. For example, the protocol FLTK uses to support CJK input methods is called
 \c zwp_text_input_v3 and is, unfortunately, unstable.
 
+Wayland makes intensive use of the 'listener' mechanism. A listener is a small array of pointers
+to FLTK-defined callback functions associated to a Wayland-defined object; Wayland
+calls these functions when defined events occur, and transmits relevant information to the client
+app as parameters of these calls. Each listener is first associated to its corresponding
+Wayland object by a call to a specific Wayland function of the form \c wl_XXX_add_listener().
+
 Wayland differs noticeably from X11 in that the position of a window in the display is
 completely hidden to the client app. Besides toplevel and sub-windows, Wayland
 allows to create popup windows positioned relatively to a previously mapped other window.
@@ -44,12 +51,6 @@ to pilot menus, because the previous algorithm conceived for other platforms ass
 the position of a window in the display to be known to the client app, which is wrong
 under Wayland.
 
-Wayland makes intensive use of the 'listener' mechanism. A listener is a small array of pointers
-to FLTK-defined callback functions associated to a Wayland-defined object; Wayland
-calls these functions when defined events occur and transmits relevant information to the client
-app as parameters of these calls. Each listener is first associated to its corresponding
-Wayland object by a call to a specific Wayland function of the form \c wl_XXX_add_listener().
-
 Wayland uses a trick of its own to handle lists of linked records. It defines the opaque type
 <tt>struct wl_list</tt> and a few macros (\c wl_list_init(), \c wl_list_for_each(), \c wl_list_insert(),
 \c wl_list_for_each_safe(), \c wl_list_remove()) to manage linked lists. Records put in these
@@ -106,6 +107,7 @@ The public C API to Wayland, xkb and libdecor libraries are obtained with
 #include <xkbcommon/xkbcommon-compose.h>
 #include <linux/input.h>
 #include "../../../libdecor/src/libdecor.h"
+#include "../../../libdecor/src/libdecor-plugin.h"
 \endcode
 as necessary.
 
@@ -201,11 +203,11 @@ stored as member \c wl_compositor of the \c Fl_Wayland_Screen_Driver object.
 and stores this information in static member variable \c Fl_Wayland_Screen_Driver::compositor.
 
 Finally, function \c wl_display_get_fd() is called to obtain the file descriptor of the Wayland socket
-and a call to Fl::add_fd() makes FLTK listen to this descriptor and associates function
+and a call to Fl::add_fd() makes FLTK listen to this descriptor in \c FL_READ mode and associates
-\c wayland_socket_callback()
+function \c wayland_socket_callback() from file \c Fl_Wayland_Screen_Driver.cxx with it.
-from file \c Fl_Wayland_Screen_Driver.cxx with it. This function calls \c wl_display_dispatch() which
+This function calls \c wl_display_dispatch() which reads and interprets data available from the
-asks the Wayland client library to process requests arrived in the socket. The \c wl_display_dispatch()
+file descriptor, and calls corresponding listeners.
-call is repeated as long as data are available for reading.
+The \c wl_display_dispatch() call is repeated as long as data are available for reading.
 
 The event loop is run by function \c Fl_Unix_System_Driver::wait() which is used by both
 the Wayland and X11 FLTK backends. Among various tasks, this function waits for data arriving
@@ -314,7 +316,7 @@ window has just been created or resized. In that case, FLTK calls member functio
 - a Wayland buffer;
 - a Cairo image surface.
 
-Each of these two objects bundles a byte array of the same size and the same memory layout
+Each of these two objects encapsulates a byte array of the same size and the same memory layout
 destined to contain the Fl_Window's graphics. The Cairo surface object is where FLTK draws.
 The Wayland buffer is what Wayland maps on the display. FLTK copies the Cairo surface's byte array
 to the Wayland buffer's byte array before beginning the mapping operation.
@@ -385,7 +387,7 @@ That's done by member function \c Fl_Wayland_Graphics_Driver::create_shm_buffer(
 which follows this 3-step procedure to create a "buffer factory" for FLTK and construct
 Wayland buffers from it:
 - Libdecor function <tt>os_create_anonymous_file(off_t size)</tt> creates an adequate file and mmap's
-it. FLTK initially sets this file size to \c pool_size = 10 MB. This file will be enlarged when and
+it. FLTK initially sets this file size to \c pool_size = 10 MB. This size will be increased when and
 if necessary.
 FLTK stores in variable \c pool_memory the address of the beginning of the mmap'ed memory structure.
 - Wayland function \c wl_shm_create_pool() has this mmap'ed memory shared with the
@@ -547,8 +549,10 @@ struct cursor_image {
   int offset;
 };
 \endcode
-This definition has been copied to the FLTK source code from file \c wayland-cursor.c of the
+This definition has been copied to the FLTK source code from file
-Wayland project source code because it's not accessible via Wayland header files.
+<a href=https://gitlab.freedesktop.org/wayland/wayland/-/blob/main/cursor/wayland-cursor.c>
+wayland-cursor.c</a> of the Wayland project source code
+because it's not accessible via Wayland header files.
 It shows that a pointer to a \c cursor_image object can also be viewed as a pointer to the
 embedded <tt>struct wl_cursor_image</tt> object, this one being part of the public Wayland API.
 It also shows that a <tt>struct cursor_image</tt> object has an associated
@@ -583,11 +587,11 @@ gets associated to a standard cursor or to a new custom cursor.
 
 \section wayland-text Text input
 
-The "Mouse handling" topic above mentionned function \c seat_capabilities() that Wayland calls when
+The "Mouse handling" section above mentionned function \c seat_capabilities() that Wayland calls when
 the app discovers its "seat". Presence of flag \c WL_SEAT_CAPABILITY_KEYBOARD in argument
-\c capabilities of this function indicates that a keyboard is available. This availability is
+\c capabilities of this function indicates that a keyboard is available. In that case, a call to
-stored in member \c wl_keyboard of the \ref seat object. Then, a call to
+\c wl_seat_get_keyboard() returns a pointer stored in member \c wl_keyboard of the \ref seat object,
-\c wl_keyboard_add_listener() installs a 6-member listener of type
+and a call to \c wl_keyboard_add_listener() installs a 6-member listener of type
 <tt>struct wl_keyboard_listener</tt>. These 6 FLTK-defined, callback functions are used as follows.
 
 Function \c wl_keyboard_keymap() runs once and allows initialization of access to this keyboard.
@@ -619,9 +623,9 @@ the <tt>wl_keyboard</tt> object which is at version 3 in all tested Wayland comp
 
 When the connected Wayland compositor supports text input methods, function
 \c registry_handle_global() gets called with its \c interface argument equal to
-\c zwp_text_input_manager_v3_interface.name. The following call to \c wl_registry_bind() returns an
+\c zwp_text_input_manager_v3_interface.name. The following call to \c wl_registry_bind() returns a
-object of type <tt>struct zwp_text_input_manager_v3 *</tt> that is stored as member \c text_input_base
+pointer to type <tt>struct zwp_text_input_manager_v3</tt> that is stored as member
-of the \c Fl_Wayland_Screen_Driver object.
+\c text_input_base of the \c Fl_Wayland_Screen_Driver object.
 
 Later, when function \c seat_capabilities() runs, \c text_input_base is found not NULL, which triggers
 a call to function \c zwp_text_input_manager_v3_get_text_input() returning a value of type
@@ -782,7 +786,8 @@ description of function wl_display_prepare_read_queue()</a>.
 \section wayland-type FLTK-defined, Wayland-specific types
 
 \anchor wld_window
-- <tt>struct wld_window</tt> is defined in \c Fl_Wayland_Window_Driver.H. One such record is created
+<h3>struct wld_window</h3>
+Defined in \c Fl_Wayland_Window_Driver.H. One such record is created
 for each shown()'n Fl_Window by \c Fl_Wayland_Window_Driver::makeWindow().
 Function \c fl_wl_xid(Fl_Window*) returns a pointer to the <tt>struct wld_window</tt> of its argument.
 <pre>
@@ -810,7 +815,8 @@ struct wld_window {
 </pre>
 
 \anchor fl_wld_buffer
-- <tt>struct fl_wld_buffer</tt> is defined in \c Fl_Wayland_Graphics_Driver.H. One such record is
+<h3>struct fl_wld_buffer</h3>
+Defined in \c Fl_Wayland_Graphics_Driver.H. One such record is
 created for each shown()'n or resized Fl_Window by \c Fl_Wayland_Graphics_Driver::create_shm_buffer().
 <pre>
 struct fl_wld_buffer {
@@ -827,7 +833,8 @@ struct fl_wld_buffer {
 </pre>
 
 \anchor output
-- <tt>struct output</tt> is defined inside class \c Fl_Wayland_Screen_Driver. One such record is
+<h3>struct output</h3>
+Defined inside class \c Fl_Wayland_Screen_Driver. One such record is
 created for each display of the system by function \c registry_handle_global() when it receives a
 \c "wl_output" interface. These records are kept in a linked list of them all, and
 an identifier of this linked list is stored in member \c outputs of the unique
@@ -850,12 +857,12 @@ struct output { // one record for each display
 };
 </pre>
 
-
 \anchor seat
-- <tt>struct seat</tt> is defined in file \c Fl_Wayland_Screen_Driver.H. One such record is
+<h3>struct seat</h3>
-created for each seat (e.g., a collection of displays, a keyboard and a mouse) of the system by
+Defined in file \c Fl_Wayland_Screen_Driver.H. One such record is created by
 function \c registry_handle_global() when it receives a \c "wl_seat" or
-\c wl_data_device_manager_interface.name interface.
+\c wl_data_device_manager_interface.name interface. A pointer to this record is stored in member
+\c seat of the client's unique \c Fl_Wayland_Screen_Driver object.
 <pre>
 struct seat {
   struct wl_seat *wl_seat;
@@ -891,10 +898,10 @@ struct seat {
 <table summary="Wayland Documentation" width="100%" border="1">
 <tr>
   <td>
-    <a href=https://wayland-book.com/>The Wayland Protocol</a>
+    <a href=https://wayland-book.com/>The Wayland book</a>
   </td>
-  <td>Extensive introduction to Wayland programming written by the Wayland author,
+  <td>Extensive introduction to Wayland programming written by the author of the <i>sway</i>
-  unfortunately unachieved.
+  compositor, unfortunately unachieved.
   <td>
 </tr>
 
@@ -902,7 +909,7 @@ struct seat {
   <td>
     <a href=https://wayland.app/protocols/>Wayland Explorer</a>
   </td>
-  <td>Documentation of all Wayland protocols, both stable and unstable. A language-independent syntax is used which makes function names usable in the C language not always obvious. Also some useful functions seem undocumented here for an unclear reason.
+  <td>Documentation of all Wayland protocols, both stable and unstable. A language-independent syntax is used which makes function names usable from C or C++ not always obvious. Some useful functions seem undocumented here for an unclear reason.
   <td>
 </tr>