Merge branch 'proto-doc' into 'main'

doc: explain wl_registry on the protocol page

See merge request wayland/wayland!545

doc/book/src/Protocol.md

@@ -170,9 +170,9 @@ mechanism to request a different version.
 
 ## Connect Time
 
-There is no fixed connection setup information, the server emits multiple events
+When a client connects, the server sends no data but silently provides access to
-at connect time, to indicate the presence and properties of global objects:
+the singleton `wl_display` under object ID 1. Global objects are managed through
-outputs, compositor, input devices.
+an instance of [wl_registry](#registry).
 
 ## Security and Authentication
 
@@ -187,16 +187,47 @@ outputs, compositor, input devices.
 
 Each object has a unique ID. The IDs are allocated by the entity creating the
 object (either client or server). IDs allocated by the client are in the range
-[1, 0xfeffffff] while IDs allocated by the server are in the range [0xff000000,
+[2, 0xfeffffff] while IDs allocated by the server are in the range [0xff000000,
-0xffffffff]. The 0 ID is reserved to represent a null or non-existent object.
+0xffffffff]. The 0 ID is reserved to represent a null or non-existent object and
-For efficiency purposes, the IDs are densely packed in the sense that the ID N
+ID 1 is automatically assigned to the singleton `wl_display` instance when a
-will not be used until N-1 has been used. This ordering is not merely a
+client connects. For efficiency purposes, the IDs are densely packed in the
-guideline, but a strict requirement, and there are implementations of the
+sense that the ID N will not be used until N-1 has been used. This ordering is
-protocol that rigorously enforce this rule, including the ubiquitous libwayland.
+not merely a guideline, but a strict requirement, and there are implementations
+of the protocol that rigorously enforce this rule, including the ubiquitous
+libwayland.
+
+## Display
+
+The display is a singleton global object and always has the ID 1. Clients often
+call its `get_registry` method after connecting to the server to obtain the
+object registry.
+
+See [wl_display](https://wayland.app/protocols/wayland#wl_display) for the
+protocol description.
+
+## Registry
+
+The registry is a global object, instantiated using
+[`wl_display.get_registry`](https://wayland.app/protocols/wayland#wl_display:request:get_registry),
+that acts as the interface to Wayland's object system between client and server:
+it initially informs the client of all objects available on the server,
+announces to the client whenever objects are added to or removed from the
+server, and allows the client to bind to the objects to interact with them.
+
+After instantiating a new registry, the server advertises all available objects
+to the client using
+[`wl_registry.global`](https://wayland.app/protocols/wayland#wl_registry:event:global).
+Thereafter, whenever a new object is added, the server advertises it to its
+clients using `wl_registry.global`, and whenever an object is removed, this fact
+is advertised using
+[`wl_registry.global_remove`](https://wayland.app/protocols/wayland#wl_registry:event:global_remove).
+
+See [wl_registry](https://wayland.app/protocols/wayland#wl_registry) for the
+protocol description.
 
 ## Compositor
 
-The compositor is a global object, advertised at connect time.
+The compositor is a global object, advertised through the registry.
 
 See [wl_compositor](https://wayland.app/protocols/wayland#wl_compositor) for the
 protocol description.
@@ -275,8 +306,8 @@ client is likely just broken.
 
 ## Output
 
-An output is a global object, advertised at connect time or as it comes and
+An output is a global object, advertised through the registry. Outputs may be
-goes.
+added or removed during the lifetime of the server.
 
 See [wl_output](https://wayland.app/protocols/wayland#wl_output) for the
 protocol description.