13 files changed, 54 insertions(+), 53 deletions(-)

M src/introduction/goals.md
M src/introduction/high-level-design.md
M src/libwayland/interfaces.md
M src/libwayland/proxies.md
M src/libwayland/util.md
M src/protocol-design/high-level.md
M src/protocol-design/interfaces-reqs-events.md
M src/protocol-design/wire-protocol.md
M src/registry.md
M src/registry/binding.md
M src/wayland-display.md
M src/wayland-display/creation.md
M src/wayland-display/event-loop.md

@@ 14,7 14,7 @@ here about leveraging libdrm in your Wayland compositor, or using libinput to
 process evdev events. Thus, this book is not a comprehensive guide for building 
 Wayland compositors. We're also not going to talk about drawing technologies 
 which are useful for Wayland clients, such as Cairo, Pango, GTK+, and so on, and 
-thus neither is this a robust guide for the practical Wayland client 
+thus nor is this a robust guide for the practical Wayland client 
 implementation. Instead, we focus only on the particulars of Wayland.
 
 This book only covers the protocol and libwayland. If you are writing a client

@@ 59,12 59,12 @@ tells it so. For this reason, only one component is allowed to talk to it...
 
 This responsibility falls onto the kernel. The kernel is a complex beast, so
 we'll focus on only the parts which are relevant to Wayland. Linux's job is to
-provide an abstraction over your hardware, so that they can be safely accessed
+provide an abstraction over your hardware, so that it can be safely accessed
 by *userspace* — where our Wayland compositors run. For graphics, this is
-called **DRM**, or *direct rendering manager*, for efficiently tasking the GPU
-with work from userspace. An important subsystem of DRM is **KMS**, or *kernel
-mode setting*, for enumerating your displays and setting properties such as 
-their selected resolution (also known as their "mode"). Input devices are 
+called the **DRM**, or *direct rendering manager*, which efficiently tasks the
+GPU with work from userspace. An important subsystem of DRM is **KMS**, or
+*kernel mode setting*, for enumerating your displays and setting properties such
+as their selected resolution (also known as their "mode"). Input devices are
 abstracted through an interface called **evdev**.
 
 Most kernel interfaces are made available to userspace by way of special files

@@ 68,7 68,7 @@ static const struct wl_surface_listener surface_listener = {
     .leave = wl_surface_leave,
 };
 
-// ...cotd...
+// ...
 
 struct wl_surface *surf;
 wl_surface_add_listener(surf, &surface_listener, NULL);

@@ 1,6 1,6 @@
 # Proxies & resources
 
-An *object* is an entity which known to both the client and server that has some
+An *object* is an entity known to both the client and server that has some
 state, changes to which are negotiated over the wire. On the client side,
 libwayland refers to these objects through the `wl_proxy` interface. These are a
 concrete C-friendly "proxy" for the abstract object, and provides functions


@@ 20,4 20,5 @@ out-of-context, or send a protocol error when the client attempts an invalid
 operation.
 
 Another level up is another set of higher-level interfaces, which most Wayland
-client & server code interacts with to accomplish a majority of their tasks.
+clients & servers interact with to accomplish a majority of their tasks. We will
+look at them in the next section.

@@ 13,6 13,6 @@ handful of primitives for use in Wayland applications. Among these are:
   numbers) and C types
 - Debug logging facilities to bubble up information from libwayland internals
 
-The header contains many comments which document itself. The documentation is
-quite good — you should read through the header yourself. We'll go into 
-detail on how to apply these primitives in the next several pages.
+The header itself contains many comments with quite good documentation —
+you should read through them yourself. We'll go into detail on how to apply
+these primitives in the next several pages.

@@ 31,11 31,11 @@ yourself — included is additional documentation explaining the purpose and
 precise semantics of each request and event.
 
 When processing this XML file, we assign each request and event an opcode in the
-order that they appear (both numbered from zero and incrementing independently).
+order that they appear, numbered from zero and incrementing independently.
 Combined with the list of arguments, you can decode the request or event when it
 comes in over the wire, and based on the documentation shipped in the XML file
 you can decide how to program your software to behave accordingly.  This usually
-comes in the form of code generation — we'll talk about how libwayland 
+comes in the form of code generation — we'll talk about how libwayland
 does this in chapter 3.
 
 Starting from chapter 4, most of the remainder of this book is devoted to

@@ 9,9 9,10 @@ are possible, and the *signature* of each. Let's consider an example interface:
 
 A surface is a box of pixels that can be displayed on-screen. It's one of the
 primitives we build things like application windows out of. One of its
-*requests* is "damage", which the client uses to indicate that some part of the
-surface has changed and needs to be redrawn. Here's an annotated example of a
-"damage" message on the wire (in hexadecimal):
+*requests*, sent from the client to the server, is "damage", which the client
+uses to indicate that some part of the surface has changed and needs to be
+redrawn. Here's an annotated example of a "damage" message on the wire (in
+hexadecimal):
 
     0000000A    Object ID (10)
     00180002    Message length (24) and request opcode (2)


@@ 29,11 30,11 @@ for processing internally.
 
 ## Events
 
-Requests are sent from the client to the server. The server can also send
-messages back — events. One event that the server can send regarding a
-`wl_surface` is "enter", which it sends when that surface is being displayed on
-a specific output (the client might respond to this, for example, by adjusting
-its scale factor for a HiDPI display). Here's an example of such a message:
+The server can also send messages back to the client — events. One event
+that the server can send regarding a `wl_surface` is "enter", which it sends
+when that surface is being displayed on a specific output (the client might
+respond to this, for example, by adjusting its scale factor for a HiDPI
+display). Here's an example of such a message:
 
     0000000A    Object ID (10)
     000C0000    Message length (12) and event opcode (0)


@@ 43,12 44,12 @@ This message references another object, by its ID: the `wl_output` object which
 the surface is being shown on. The client receives this and dances to a similar
 tune as the server did. It looks up object 10, associates it with the
 `wl_surface` interface, and looks up the signature of the event corresponding to
-opcode 0. It decodes the rest of the message accordingly (looking up the
-`wl_output` with ID 5 as well), then dispatches it for processing internally.
+opcode 0. It decodes the rest of the message accordingly, looking up the
+`wl_output` with ID 5 as well, then dispatches it for processing internally.
 
 ## Interfaces
 
 The interfaces which define the list of requests and events, the opcodes
-associated with each, and the signatures with which you can decode the messages 
-— are agreed upon in advance. I'm sure you're dying to know how — 
+associated with each, and the signatures with which you can decode the messages,
+are agreed upon in advance. I'm sure you're dying to know how — 
 simply turn the page to end the suspense.

@@ 57,9 57,9 @@ assuming you've already negotiated an object ID. Speaking of which...
 
 ## Object IDs
 
-When a message comes in with a `new_id` argument, the sender allocates an
-object ID for it (the interface used for this object is established through
-additional arguments, or agreed upon in advance for that request/event). This
+When a message comes in with a `new_id` argument, the sender allocates an object
+ID for it — the interface used for this object is established through
+additional arguments, or agreed upon in advance for that request/event. This
 object ID can be used in future messages, either as the first word of the
 header, or as an `object_id` argument. The client allocates IDs in the range of
 `[1, 0xFEFFFFFF]`, and the server allocates IDs in the range of `[0xFF000000,

@@ 4,7 4,7 @@ If you'll recall from chapter 2.1, each request and event is associated with an
 object ID, but thus far we haven't discussed how objects are created. When we
 receive a Wayland message, we must know what interface the object ID represents
 to decode it. We must also somehow negotiate available objects, the creation of
-new ones, and the assigning of IDs to them, in some manner. On Wayland we solve
+new ones, and the assigning of IDs to them, in some manner. In Wayland we solve
 both of these problems at once — when we *bind* an object ID, we agree on 
 the interface used for it in all future messages, and stash a mapping of object 
 IDs to interfaces in our local state.


@@ 12,14 12,14 @@ IDs to interfaces in our local state.
 In order to bootstrap these, the server offers a list of *global* objects. These
 globals often provide information and functionality on their own merits, but
 most often they're used to broker additional objects to fulfill various
-purposes — such as the creation of application windows. These globals 
-themselves also have their own object IDs and interfaces, which we have to 
-assign and agree upon somehow.
+purposes, such as the creation of application windows. These globals themselves
+also have their own object IDs and interfaces, which we have to somehow assign
+and agree upon.
 
-With questions of hens and eggs no doubt coming to mind by now, I'll reveal the
-secret trick: object ID 1 is already implicitly assigned to the `wl_display`
-interface when you make the connection. As you'll recall the interface, take
-note of the `wl_display::get_registry` request:
+With questions of chickens and eggs no doubt coming to mind by now, I'll reveal
+the secret trick: object ID 1 is already implicitly assigned to the `wl_display`
+interface when you make the connection. As you recall the interface, take note
+of the `wl_display::get_registry` request:
 
 ```xml
 <interface name="wl_display" version="1">


@@ 31,7 31,7 @@ note of the `wl_display::get_registry` request:
     <arg name="registry" type="new_id" interface="wl_registry" />
   </request>
 
-  <!-- cotd -->
+  <!-- ... -->
 </interface>
 ```
 

@@ 4,14 4,13 @@ Upon creating a registry object, the server will emit the `global` event for
 each global available on the server. You can then bind to the globals you
 require.
 
-This process of taking a known object and assigning it an ID is called
-*binding* the object. Once the client binds to the registry like this, the
-server emits the `global` event several times to advertise which interfaces it
-supports. Each of these globals is assigned a unique `name`, as an unsigned
-integer. The `interface` string maps to the name of the interface found in the
-protocol: `wl_display` from the XML above is an example of such a name. The
-version number is also defined here — for more information about interface
-versioning, see appendix C.
+*Binding* is the process of taking a known object and assigning it an ID. Once
+the client binds to the registry like this, the server emits the `global` event
+several times to advertise which interfaces it supports. Each of these globals
+is assigned a unique `name`, as an unsigned integer. The `interface` string maps
+to the name of the interface found in the protocol: `wl_display` from the XML
+above is an example of such a name. The version number is also defined here
+— for more information about interface versioning, see appendix C.
 
 To bind to any of these interfaces, we use the bind request, which works
 similarly to the magical process by which we bound to the `wl_registry`. For

@@ 44,7 44,7 @@ for housekeeping on the connection, and are generally not important unless
 you're writing your own libwayland replacement.
 
 Instead, this chapter will focus on a number of functions that libwayland
-associated with the `wl_display` object, for establishing and maintaining your
+associates with the `wl_display` object, for establishing and maintaining your
 Wayland connection. These are used to manipulate libwayland's internal state,
 rather than being directly related to wire protocol requests and events.
 

@@ 50,11 50,11 @@ libwayland will:
 
 1. If `$WAYLAND_DISPLAY` is set, attempt to connect to
    `$XDG_RUNTIME_DIR/$WAYLAND_DISPLAY`
-2. Attempt to connect to `$XDG_RUNTIME_DIR/wayland-0`
-3. Fail :(
+2. Otherwise, attempt to connect to `$XDG_RUNTIME_DIR/wayland-0`
+3. Otherwise, fail :(
 
 This allows users to specify the Wayland display they want to run their clients
-on by setting the `$WAYLAND_DISPLAY` to the desired display. If you have more
+on by setting `$WAYLAND_DISPLAY` to the desired display. If you have more
 complex requirements, you can also establish the connection yourself and create
 a Wayland display from a file descriptor:
 


@@ 115,7 115,7 @@ Connection established!
 
 Using `wl_display_add_socket_auto` will allow libwayland to decide the name for
 the display automatically, which defaults to `wayland-0`, or `wayland-$n`,
-depending on if any other Wayland compositors have sockets in
+depending on whether any other Wayland compositors have sockets in
 `$XDG_RUNTIME_DIR`. However, as with the client, you have some other options for
 configuring the display:
 

@@ 2,8 2,8 @@
 
 libwayland provides its own event loop implementation for Wayland servers to
 take advantage of, but the maintainers have acknowledged this as a design
-overstep. For clients, there is no such equivalent. However, the Wayland server
-event loop is useful enough, even if it's out-of-scope.
+overstep. For clients, there is no such equivalent. Regardless, the Wayland
+server event loop is useful enough, even if it's out-of-scope.
 
 ## Wayland server event loop