docs: Improve word choice/clarity

CONTRIBUTING.md

@@ -9,7 +9,7 @@ SPDX-License-Identifier: CC-BY-4.0
 There are plenty of valid reasons why someone might not be able
 to follow all of the guidelines in this section, and that's OK,
 especially for new contributors or those new to open source entirely.
-Just let us know and we'll figure out a way to help you get involved successfully.
+Let us know and we'll figure out a way to help you get involved successfully.
 
 > Important note: Unlike the guidelines here, the Code of Conduct,
 > available at <https://www.freedesktop.org/wiki/CodeOfConduct/>,
@@ -25,11 +25,11 @@ Just let us know and we'll figure out a way to help you get involved successfull
   to begin a discussion and help smooth the acceptance of your contribution.
 
 - If you are able, please make sure to run clang-format
-  (ideally version 7 or newer) before each commit,
+  (ideally version 11 or newer) before each commit,
   so that you only commit things that are cleanly styled.
   Consistent, machine-performed formatting improves readability and makes it easier for others to contribute.
   It also makes it easier to review changes.
-  If you can't run clang-format, just mention this fact in your request and we'd be happy to help,
+  If you can't run clang-format, mention this fact in your request and we'd be happy to help,
   either in a single "Clean up formatting." commit on top of your work,
   or by "re-writing history" (with your permission and leaving your commit authorship intact),
   revising each commit to apply formatting.
@@ -52,7 +52,7 @@ Just let us know and we'll figure out a way to help you get involved successfull
   please help by making sure your changes build cleanly (and pass all tests).
   When on compilers that take warning flags like gcc and clang do,
   the build system automatically turns on quite a few of them.
-  If a warning stumps you, just mention it in the request so we can figure it out together.
+  If you can't figure out a warning, mention it in the request so we can figure it out together.
 
 ### Issues
 

README.md

@@ -21,8 +21,7 @@ and AR on mobile, PC/desktop, and any other device
 come up with a lot of weird hardware).
 Monado aims to be a complete and conforming implementation
 of the OpenXR API made by Khronos.
-The project currently is being developed for GNU/Linux
-and aims to support other operating systems in the near future.
+The project is primarily developed on GNU/Linux, but also runs on Android and Windows.
 "Monado" has no specific meaning and is just a name.
 
 ## Monado source tree
@@ -248,10 +247,8 @@ scripts/format-project.sh
 You can optionally put something like `CLANG_FORMAT=clang-format-7` before that command
 if your clang-format binary isn't named `clang-format`.
 **Note that you'll typically prefer** to use something like `git clang-format`
-to just re-format your changes, in case version differences in tools result in overall format changes.
-The CI "style" job currently runs on Debian Buster, so it has clang-format-7.
-We will probably update that job to Bullseye or Ubuntu 20.10, which will allow
-using clang-format-11 by default, soon.
+to re-format only your changes, in case version differences in tools result in overall format changes.
+The CI "style" job currently runs on Debian Bullseye, so it has clang-format-11.
 
 [OpenHMD]: http://openhmd.net
 [drm-lease]: https://haagch.frickel.club/#!drmlease%2Emd

doc/CHANGELOG.md

@@ -566,12 +566,12 @@ SPDX-FileCopyrightText: 2020 Collabora, Ltd. and the Monado contributors
   - comp: Set a compositor window title.
     ([!418](https://gitlab.freedesktop.org/monado/monado/merge_requests/418))
 - IPC
-  - server: Almost completely overhaul the handling of swapchain life cycle
+  - server: Almost completely overhaul the handling of swapchain lifecycle
     including: correctly track which swapchains are alive; reuse ids; enforce the
     maximum number of swapchains; and destroy underlying swapchains when they are
     destroyed by the client.
     ([!359](https://gitlab.freedesktop.org/monado/monado/merge_requests/359))
-  - util: Make sure to not access NULL control messages, say in the case of the
+  - util: Make sure to not dereference NULL control messages, say in the case of the
     server failing to create a swapchain. Also add a whole bunch of paranoia when
     it comes to the alignment of the control message buffers.
     ([!359](https://gitlab.freedesktop.org/monado/monado/merge_requests/359))

doc/changes/README.md

@@ -55,14 +55,12 @@ Each change should add a changelog fragment file, whose contents are
 Markdown-formatted text describing the change briefly. Reference metadata will
 be used to automatically add links to associated issues/merge requests/pull
 requests, so no need to add these in your fragment text. The simplest changelog
-fragment just contains one line of Markdown text describing the change:
+fragment contains one line of Markdown text describing the change:
 
 ```md
 Here the author of a change has written some text about it.
 ```
 
-(If you change the template in your Proclamation config file, your project can use a different markup format than Markdown.)
-
 ### References
 
 The changelog fragment system revolves around "references" - these are issue
@@ -95,7 +93,7 @@ extension added. (You can also use `.rst` or `.txt` as your extension in your
 project.)
 
 To specify additional references in a file, prefix the contents of the changelog
-fragment with a block delimited above and below by `---`, with one reference on
+fragment with a block delimited before and after by `---`, with one reference on
 each line. (This can be seen as a very minimal subset of "YAML Front Matter", if
 you're familiar with that concept.) For example:
 
@@ -109,7 +107,7 @@ Here the author of a change has written some text about it.
 
 There are provisions for providing your own reference parser if this format is
 entirely unusable, but they're underdeveloped. (Most use cases found by the
-original author can actually be accommodated just by changing the template and
+original author can actually be accommodated by changing the template and
 specifying `.`-delimited fields in references.) If this functionality is
 interesting to you, get involved in the development of Proclamation and help
 finish it!
@@ -166,7 +164,7 @@ elaborate use-cases than this.)
   - `insert_point_pattern` - Useful mainly if you're not using the default
     template. The first match of this regex will be considered the first line of
     a release entry, and your new release will be put in your changelog file
-    above it. Default works with the default template (looks for a second-level
+    before it. Default works with the default template (looks for a second-level
     Markdown heading).
   - `extra_data` - Any extra data you'd like to pass along to your custom
     template.

doc/changes/auxiliary/mr.839.1.md

@@ -1,4 +1,4 @@
 util: added `u_device_2d_extents` and `u_setup_2d_extents_split_side_by_side` -
 this is hopefully to eliminate confusion: the FOV you had to give to
-`u_device_split_side_by_side` was just a dummy value, but some people thought
+`u_device_split_side_by_side` was a placeholder value, but some people thought
 it was the actual headset's FOV.

doc/changes/misc_features/mr.695.md

@@ -1 +1 @@
-Implement tracking overrides via wrapper devices and add a tracking override configuration gui.
+Implement tracking overrides using wrapper devices and add a tracking override configuration gui.

doc/changes/misc_features/mr.715.md

@@ -1,3 +1,3 @@
-a/gst: Add a small and fairly dumb framework for integrating gstreamer pipelines
+a/gst: Add a small and fairly naive framework for integrating gstreamer pipelines
 into Monado pipelines. Enough to be able to push frames into it and use various
 encoder elements.

doc/changes/xrt/mr.1258.md

@@ -1,3 +1,3 @@
 xrt: Add xrt_swapchain_create_properties to allow client compositors and IPC
-code to query the main compositor how many images to create on a swapchain
-(and in the future or properties as needed).
+code to query the main compositor how many images to create on a swapchain,
+and provide an extension point for more properties as needed.

doc/changes/xrt/mr.721.4.md

@@ -1,4 +1,4 @@
 Add `xrt_multi_compositor_control` that allows the `xrt_system_compositor` to
 expose a interface that the IPC layer can use to manage multiple clients
 without having to do the rendering. This allows us to move a lot of the code
-out the IPC layer and make it more about just passing calls.
+out the IPC layer and make it more about passing calls.

doc/conventions.md

@@ -1,7 +1,7 @@
 # Code Style and Conventions {#conventions}
 
 <!--
-Copyright 2021, Collabora, Ltd. and the Monado contributors
+Copyright 2021-2022, Collabora, Ltd. and the Monado contributors
 SPDX-License-Identifier: BSL-1.0
 -->
 
@@ -19,7 +19,7 @@ Here are some general code style guidelines we follow.
 ## APIs
 
 Internal APIs, when it makes sense, should be C APIs. Headers that define
-general communication interfaces between modules (not just use of utilities)
+general communication interfaces between modules (not only use of utilities)
 belong in the `xrt/include/xrt` directory, and should not depend on any other module outside
 that directory. (As a historical note: this directory gets its name from a
 compressed version of the phrase "XR RunTime", a generic term for Monado and an
@@ -161,8 +161,8 @@ are gradually migrating those that don't fit this pattern. If you call a
 destroy function that does not take a pointer-to-a-pointer, make sure to do
 null checks before calling and set it to null after it returns.
 
-Also note: when an interface includes a "destroy" function pointer, it just
-takes the normal pointer to an object: The free function wrapper is the one that
-takes a pointer-to-a-pointer and handles the null checks. See for example @ref
+Also note: when an interface includes a "destroy" function pointer, it takes the
+normal pointer to an object: The free function wrapper is the one that takes a
+pointer-to-a-pointer and handles the null checks. See for example @ref
 xrt_instance_destroy takes the pointer-to-a-pointer, while the interface method
-@ref xrt_instance::destroy takes just the single pointer.
+@ref xrt_instance::destroy takes the single pointer.

doc/frame-pacing.md

@@ -7,7 +7,7 @@ SPDX-License-Identifier: BSL-1.0
 
 A "brief" overview of the various time-points that a frame goes through, from
 when the application gets go ahead to render the frame to when pixels are turned
-into photons. This is only a single frame, where all of the timings are hit and
+into photons. This is only a single frame, where all of the timings are achieved and
 the application is single threaded. The HMD also only turns on the display
 during the vblank period, meaning the pixel to photon transformation is delayed
 from scanout starting to the vblank period (like for the Index).
@@ -43,6 +43,6 @@ information.
 * @ref xrt_comp_layer_stereo_projection - This and other layer functions are
   called to list the layers the compositor should render.
 * @ref xrt_comp_layer_commit - The compositor starts to render the frame,
-  trying to hit the **present** time.
+  trying to finish at the **present** time.
 
 [`VK_GOOGLE_display_timing`]: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_GOOGLE_display_timing.html

doc/howto-release.md

@@ -47,4 +47,4 @@ git tag v21.0.0 -m"v21.0.0"
 
 ## Do gitlab release
 
-The Gitlab UI has a friendly interface, just follow the guide there.
+The Gitlab UI has a friendly interface, follow the guide there.

doc/howto-remote-driver.md

@@ -5,11 +5,11 @@ Copyright 2022, Collabora, Ltd. and the Monado contributors
 SPDX-License-Identifier: BSL-1.0
 -->
 
-## Prerequisites 
+## Prerequisites
 
 Before proceeding you will need to have monado installed (or built) and capable
 of running applications. If you do not have any hardware this should still work
-with the dummy driver. For those building Monado themselves you have to make
+with the simulated driver. For those building Monado themselves you have to make
 sure the GUI is built. In short the commands `monado-gui` and `monado-service`
 are needed.
 

doc/implementing-extensions.md

@@ -23,7 +23,7 @@ The general steps to implement an OpenXR extension in Monado are as follows.
 * Implement the `oxr_` Monado internal functions in an appropriate source file
   `src/state_trackers/oxr/oxr_api_*.c`. Trivial functions can be implemented
   right there along with the usual parameter checks. More complex functions that
-  access more internal monado state should call functions implemented in the
+  use more internal Monado state should call functions implemented in the
   relevant `oxr_*.c` file (without `_api_`). The definitions for those functions
   go into `src/xrt/state_trackers/oxr/oxr_objects.h`.
 * Monado internal implementations of "objects" (think XrSession or

doc/ipc.md

@@ -17,10 +17,10 @@ There are three main communication needs:
   any, to start communication. (Auto-starting, where available, is handled by
   platform-specific mechanisms: the client currently has no code to explicitly
   start up the service.)
-- The client and service must share a dedicated channel for IPC calls (aka
-  **RPC** - remote procedure call), typically a socket.
-- The service must share access to device data updating at various rates, shared
-  by all clients. This is typically done with a form of **shared memory**.
+- The client and service must share a dedicated channel for IPC calls (also
+  known as **RPC** - remote procedure call), typically a socket.
+- The service must share device data updating at various rates, shared by all
+  clients. This is typically done with a form of **shared memory**.
 
 Each platform's implementation has a way of meeting each of these needs. The
 specific way each need is met is highlighted below.
@@ -47,7 +47,7 @@ descriptor to the client, so it has (read) access to this data.
 
 ## Android Platform Details
 
-On Android, in order to pass platform objects, allow for service activation, and
+On Android, to pass platform objects, allow for service activation, and
 fit better within the idioms of the platform, Monado provides a Binder/AIDL
 service instead of a named socket. (The named sockets we typically use are not
 permitted by the platform, and "abstract" named sockets are currently available,
@@ -90,11 +90,11 @@ From there, the native-code mainloop starts when this service received a valid
 `Surface`. By default, the JVM code will signal the mainloop to shut down a short
 time after the last client disconnects, to work best within the platform.
 
-At startup, just as on Linux, the shared memory segment is created. The
-[ashmem][] API is used to create/destroy an anonymous **shared memory** segment
-on Android, instead of standard POSIX shared memory, but is otherwise treated
-and used exactly the same as on standard Linux: file descriptors are duplicated
-and passed through IPC calls, etc.
+At startup, as on Linux, the shared memory segment is created. The [ashmem][]
+API is used to create/destroy an anonymous **shared memory** segment on Android,
+instead of standard POSIX shared memory, but is otherwise treated and used
+exactly the same as on standard Linux: file descriptors are duplicated and
+passed through IPC calls, etc.
 
 When the client side starts up, it creates an __anonymous socket pair__ to use
 for IPC calls (the **RPC** function) later. It then passes one of the two file
@@ -123,8 +123,8 @@ multiple clients and client transition without shutdown.
 ### Synchronization
 
 Synchronization of new client connections is a special challenge on the Android
-platform, since new clients arrive via calls into JVM code while the mainloop is
-native code. Unlike Linux, we cannot simply use epoll to check if there are new
+platform, since new clients arrive using calls into JVM code while the mainloop is
+C/C++ code. Unlike Linux, we cannot simply use epoll to check if there are new
 connections to our locating socket.
 
 We have the following design goals/constraints:

doc/targets.md

@@ -37,14 +37,13 @@ executable, or the well-known symbol name if it's a shared library. In some
 cases, the entry point might be provided by one of the modules being combined to
 form the target. For instance, an OpenXR runtime must expose
 `xrNegotiateLoaderRuntimeInterface`: this function is provided by the OpenXR
-state tracker `st_oxr`, so the OpenXR runtime target just has to link the state
-tracker in and ensure that symbol is present and visible in the final build
-product.
+state tracker `st_oxr`, so the OpenXR runtime target links the state tracker in
+and ensures that symbol is present and visible in the final build product.
 
-Then, the target must provide access to the collection of devices desired.
-Target device access is provided by implementing the `xrt_instance` interface in
-your target and providing a definition of `xrt_instance_create` that
-instantiates your implementation.
+Then, the target must provide an interface to the collection of devices desired.
+This is done by implementing the `xrt_instance` interface in your target and
+providing a definition of `xrt_instance_create` that instantiates your
+implementation.
 
 All methods of `xrt_instance` are required, though the `get_prober` method may
 output a null pointer if the instance is not using a prober, and targets that do
@@ -85,6 +84,6 @@ Note that in this case, there are two processes involved, which have different
 - The runtime has a "stub" or "client proxy" implementation that delegates to
   the service over the IPC.
 - The service has a normal or complete instance implementation that actually
-  provides access to devices, etc.
+  provides hardware device interaction, etc.
 
 ![Out-of-process OpenXR runtime diagram](images/out-of-proc.drawio.svg)

doc/tracing.md

@@ -54,7 +54,7 @@ Then run the following commands before launching Monado.
 
 # Start the daemon ftrace probes daemon.
 # Only needs to be run once and keeps running.
-# Not needed with the above config.
+# Not needed with the preceding config.
 ./perfetto/out/linux_clang_release/traced_probes &
 
 # When you want to run a capture do and then run Monado.

doc/vulkan-extensions.md

@@ -48,7 +48,7 @@ minimize frustration.
 
 ## Notes
 
-Kept out of the table above to limit its width.
+Kept out of the preceding table to limit its width.
 
 * Server type:
   * a: Windowed

doc/writing-a-new-driver.md

@@ -88,10 +88,10 @@ Monado are in `src/xrt/targets/common/target_lists.c`. These are shared by the
 various targets (OpenXR runtime shared library, service executable, utility
 executables) also found in `src/xrt/targets`. If you're using Monado as a
 toolkit or component rather than as a standalone runtime and service, you can
-replicate whatever portions of the target lists in your own target, or just
-directly implement the @ref xrt_instance interface more directly, linking in
-only those drivers and components you need. **Note**, however, that Monado is
-intended to not expose any external API other than the OpenXR API: the @ref
-xrt_iface are subject to change as required so those writing drivers or other
-software on those interfaces are encouraged to upstream as much as possible to
-minimize maintenance burden.
+replicate whatever portions of the target lists in your own target, or directly
+implement the @ref xrt_instance interface more directly, linking in only those
+drivers and components you need. **Note**, however, that Monado is intended to
+not expose any external API other than the OpenXR API: the @ref xrt_iface are
+subject to change as required so those writing drivers or other software on
+those interfaces are encouraged to upstream as much as possible to minimize
+maintenance burden.