From 3ddba7553f5d17f33f4698feeef1ee53af7277a9 Mon Sep 17 00:00:00 2001 From: Okhuomon Ajayi Date: Fri, 8 Mar 2024 11:51:33 +0100 Subject: [PATCH 01/11] fixed a typo in the Android setup command --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e82954f54cc8..22d0fef0877f 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,7 @@ See also [Windows Troubleshooting Tips][windows-tips]. - Install the latest version of the [Android command-line tools](https://developer.android.com/studio#command-tools) to `$ANDROID_SDK_ROOT/cmdline-tools/latest`. -- Run the following command to install the necessary components and the path t +- Run the following command to install the necessary components and the path : ```shell sudo $ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager --install "build-tools;33.0.2" \ From 3f1b3e3b47a58e98caf43c3d921d5f2bca72110b Mon Sep 17 00:00:00 2001 From: Okhuomon Ajayi Date: Fri, 8 Mar 2024 11:57:26 +0100 Subject: [PATCH 02/11] Fix typo in documentation for command-line arguments --- docs/COMMAND_LINE_ARGS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/COMMAND_LINE_ARGS.md b/docs/COMMAND_LINE_ARGS.md index 70ef19bebd04..2de7975ae909 100644 --- a/docs/COMMAND_LINE_ARGS.md +++ b/docs/COMMAND_LINE_ARGS.md @@ -11,7 +11,7 @@ Only arguments that need more explanation will be documented here. # Run ## Enable Experimental Features -Use `--pref` to enable experimental features like experimental DOM API, JavaScript API and CSS properties. +Use `--pref` to enable experimental features like the experimental DOM API, JavaScript API and CSS properties. e.g. To enable Web VR and Bluetooth features: ``` From 13c93dd8b6717fac66941ef7eb784a3b8cf86f30 Mon Sep 17 00:00:00 2001 From: Okhuomon Ajayi Date: Fri, 8 Mar 2024 12:25:52 +0100 Subject: [PATCH 03/11] Fix style and formatting issues in the Shell Scripts section of the documentation --- docs/STYLE_GUIDE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/STYLE_GUIDE.md b/docs/STYLE_GUIDE.md index 49f69e65855e..04aa0b5900f2 100644 --- a/docs/STYLE_GUIDE.md +++ b/docs/STYLE_GUIDE.md @@ -5,10 +5,10 @@ automated linters. This document has guidelines that are less easy to lint for. ## Shell scripts -Shell scripts are OK for small tasks or wrappers, but prefer to use Python for +Shell scripts are suitable for small tasks or wrappers, but it's preferable to use Python for anything with a hint of complexity or in general. -Shell scripts should be written against bash, starting with this shebang: +Shell scripts should be written using bash, starting with this shebang: ``` #!/usr/bin/env bash ``` @@ -23,7 +23,7 @@ set -o nounset set -o pipefail ``` -Quote all variables, using the full form: `"${SOME_VARIABLE}"`. +Rememeber to quote all variables, using the full form: `"${SOME_VARIABLE}"`. Use `"$(some-command)"` instead of backticks for command substitution. Note that these should be quoted as well. From eed6e163cf5821a686bda95623f689c9c8ddb342 Mon Sep 17 00:00:00 2001 From: Okhuomon Ajayi Date: Fri, 8 Mar 2024 12:37:09 +0100 Subject: [PATCH 04/11] Update style.md --- docs/components/style.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/components/style.md b/docs/components/style.md index d8d54124faba..2ac49c844535 100644 --- a/docs/components/style.md +++ b/docs/components/style.md @@ -1,15 +1,13 @@ # Servo's style system overview -This needs to be filled more extensively. Meanwhile, you can also take a look at -the [style doc comments][style-doc], or the [Styling -Overview][wiki-styling-overview] in the wiki, a conversation between +This document provides an overview of Servo's style system. For more extensive details, refer to the [style doc comments][style-doc], or the [Styling +Overview][wiki-styling-overview] in the wiki, which includes a conversation between Boris Zbarsky and Patrick Walton about how style sharing works. ## Selector Implementation -In order to be sharable and compatible with Stylo (a project that aims -to integrate Servo's style system into Gecko), the style must be consistent. +To ensure compatibility with Stylo (a project integrating Servo's style system into Gecko), selectors must be consistent. The consistency is implemented in [selectors' SelectorImpl][selector-impl], containing the logic related to parsing pseudo-elements and other pseudo-classes From 67e57bdef47cc1fcc7832d79d2bb0d6b0266e2bd Mon Sep 17 00:00:00 2001 From: Okhuomon Ajayi Date: Fri, 8 Mar 2024 12:40:08 +0100 Subject: [PATCH 05/11] Fixed various inconsistencies --- docs/components/webxr.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/components/webxr.md b/docs/components/webxr.md index 9b614ba9d169..f58105b213ca 100644 --- a/docs/components/webxr.md +++ b/docs/components/webxr.md @@ -2,22 +2,22 @@ ## Terminology -There are three main components involved in Servo's WebXR implementation: -1. the script thread (runs all JS for a page) -2. the WebGL thread (maintains WebGL canvas data and invokes GL operations corresponding to [WebGL APIs](https://registry.khronos.org/webgl/specs/latest/1.0/)) -3. the compositor (AKA the main thread) +Servo's WebXR implementation involves three main components: +1. The script thread (runs all JS for a page) +2. The WebGL thread (maintains WebGL canvas data and invokes GL operations corresponding to [WebGL APIs](https://registry.khronos.org/webgl/specs/latest/1.0/)) +3. The compositor (AKA the main thread) Additionally, there are a number of WebXR-specific concepts: -* the [discovery object](https://doc.servo.org/webxr_api/trait.DiscoveryAPI.html) (ie. how Servo discovers if a device can provide a WebXR session) -* the [WebXR registry](https://doc.servo.org/webxr_api/struct.MainThreadRegistry.html) (the compositor's interface to WebXR) -* the [layer manager](https://doc.servo.org/webxr_api/layer/trait.LayerManagerAPI.html) (manages WebXR layers for a given session and frame operations on those layers) -* ths [layer grand manager](https://doc.servo.org/webxr_api/layer/trait.LayerGrandManagerAPI.html) (manages all layer managers for WebXR sessions) +* The [discovery object](https://doc.servo.org/webxr_api/trait.DiscoveryAPI.html) (ie. how Servo discovers if a device can provide a WebXR session) +* The [WebXR registry](https://doc.servo.org/webxr_api/struct.MainThreadRegistry.html) (the compositor's interface to WebXR) +* The [layer manager](https://doc.servo.org/webxr_api/layer/trait.LayerManagerAPI.html) (manages WebXR layers for a given session and frame operations on those layers) +* The [layer grand manager](https://doc.servo.org/webxr_api/layer/trait.LayerGrandManagerAPI.html) (manages all layer managers for WebXR sessions) Finally, there are graphics-specific concepts that are important for the low-level details of rendering with WebXR: -* [surfman](https://github.com/servo/webxr/blob/main/webxr/glwindow/mod.rs#L448-L452) is a crate that abstracts away platform-specific details of OpenGL hardware-accelerated rendering -* a [surface](https://doc.servo.org/surfman/platform/unix/default/surface/type.Surface.html) is a hardware buffer that are tied to a specific OpenGL context -* a [surface texture](https://doc.servo.org/surfman/platform/unix/default/surface/type.SurfaceTexture.html) is an OpenGL texture that wraps a surface. Surface textures can be shared between OpenGL contexts. -* a [surfman context](https://doc.servo.org/surfman/platform/unix/default/context/type.Context.html) represents a particular OpenGL context, and is backed by platform-specific implementations (such as EGL on Unix-based platforms) +* [Surfman](https://github.com/servo/webxr/blob/main/webxr/glwindow/mod.rs#L448-L452) is a crate that abstracts away platform-specific details of OpenGL hardware-accelerated rendering +* a [Surface](https://doc.servo.org/surfman/platform/unix/default/surface/type.Surface.html) is a hardware buffer that are tied to a specific OpenGL context +* a [Surface texture](https://doc.servo.org/surfman/platform/unix/default/surface/type.SurfaceTexture.html) is an OpenGL texture that wraps a surface. Surface textures can be shared between OpenGL contexts. +* a [Surfman context](https://doc.servo.org/surfman/platform/unix/default/context/type.Context.html) represents a particular OpenGL context, and is backed by platform-specific implementations (such as EGL on Unix-based platforms) * [ANGLE](https://github.com/servo/mozangle/) is an OpenGL implementation on top of Direct3D which is used in Servo to provide a consistent OpenGL backend on Windows-based platforms ## How Servo's compositor starts From b23ed6792ea85755aad2149e700073f0807a80e1 Mon Sep 17 00:00:00 2001 From: Okhuomon Ajayi Date: Fri, 8 Mar 2024 12:42:55 +0100 Subject: [PATCH 06/11] Fixed various inconsistencies --- docs/components/webxr.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/components/webxr.md b/docs/components/webxr.md index f58105b213ca..87bd92d8cffa 100644 --- a/docs/components/webxr.md +++ b/docs/components/webxr.md @@ -13,11 +13,11 @@ Additionally, there are a number of WebXR-specific concepts: * The [layer manager](https://doc.servo.org/webxr_api/layer/trait.LayerManagerAPI.html) (manages WebXR layers for a given session and frame operations on those layers) * The [layer grand manager](https://doc.servo.org/webxr_api/layer/trait.LayerGrandManagerAPI.html) (manages all layer managers for WebXR sessions) -Finally, there are graphics-specific concepts that are important for the low-level details of rendering with WebXR: +Furthermore, there are graphics-specific concepts that are important for the low-level details of rendering with WebXR: * [Surfman](https://github.com/servo/webxr/blob/main/webxr/glwindow/mod.rs#L448-L452) is a crate that abstracts away platform-specific details of OpenGL hardware-accelerated rendering -* a [Surface](https://doc.servo.org/surfman/platform/unix/default/surface/type.Surface.html) is a hardware buffer that are tied to a specific OpenGL context -* a [Surface texture](https://doc.servo.org/surfman/platform/unix/default/surface/type.SurfaceTexture.html) is an OpenGL texture that wraps a surface. Surface textures can be shared between OpenGL contexts. -* a [Surfman context](https://doc.servo.org/surfman/platform/unix/default/context/type.Context.html) represents a particular OpenGL context, and is backed by platform-specific implementations (such as EGL on Unix-based platforms) +* [Surface](https://doc.servo.org/surfman/platform/unix/default/surface/type.Surface.html) is a hardware buffer that are tied to a specific OpenGL context +* [Surface texture](https://doc.servo.org/surfman/platform/unix/default/surface/type.SurfaceTexture.html) is an OpenGL texture that wraps a surface. Surface textures can be shared between OpenGL contexts. +* a[Surfman context](https://doc.servo.org/surfman/platform/unix/default/context/type.Context.html) represents a particular OpenGL context, and is backed by platform-specific implementations (such as EGL on Unix-based platforms) * [ANGLE](https://github.com/servo/mozangle/) is an OpenGL implementation on top of Direct3D which is used in Servo to provide a consistent OpenGL backend on Windows-based platforms ## How Servo's compositor starts From 99d516a081f5b894f96ac2d73c9c9be9d3487628 Mon Sep 17 00:00:00 2001 From: Okhuomon Ajayi Date: Fri, 8 Mar 2024 13:15:14 +0100 Subject: [PATCH 07/11] Update webxr.md --- docs/components/webxr.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/components/webxr.md b/docs/components/webxr.md index 87bd92d8cffa..f366b0698862 100644 --- a/docs/components/webxr.md +++ b/docs/components/webxr.md @@ -13,11 +13,11 @@ Additionally, there are a number of WebXR-specific concepts: * The [layer manager](https://doc.servo.org/webxr_api/layer/trait.LayerManagerAPI.html) (manages WebXR layers for a given session and frame operations on those layers) * The [layer grand manager](https://doc.servo.org/webxr_api/layer/trait.LayerGrandManagerAPI.html) (manages all layer managers for WebXR sessions) -Furthermore, there are graphics-specific concepts that are important for the low-level details of rendering with WebXR: -* [Surfman](https://github.com/servo/webxr/blob/main/webxr/glwindow/mod.rs#L448-L452) is a crate that abstracts away platform-specific details of OpenGL hardware-accelerated rendering -* [Surface](https://doc.servo.org/surfman/platform/unix/default/surface/type.Surface.html) is a hardware buffer that are tied to a specific OpenGL context -* [Surface texture](https://doc.servo.org/surfman/platform/unix/default/surface/type.SurfaceTexture.html) is an OpenGL texture that wraps a surface. Surface textures can be shared between OpenGL contexts. -* a[Surfman context](https://doc.servo.org/surfman/platform/unix/default/context/type.Context.html) represents a particular OpenGL context, and is backed by platform-specific implementations (such as EGL on Unix-based platforms) +Finally, there are graphics-specific concepts that are important for the low-level details of rendering with WebXR: +* [surfman](https://github.com/servo/webxr/blob/main/webxr/glwindow/mod.rs#L448-L452) is a crate that abstracts away platform-specific details of OpenGL hardware-accelerated rendering +* [surface](https://doc.servo.org/surfman/platform/unix/default/surface/type.Surface.html) is a hardware buffer that are tied to a specific OpenGL context +* [surface texture](https://doc.servo.org/surfman/platform/unix/default/surface/type.SurfaceTexture.html) is an OpenGL texture that wraps a surface. Surface textures can be shared between OpenGL contexts. +* [surfman context](https://doc.servo.org/surfman/platform/unix/default/context/type.Context.html) represents a particular OpenGL context, and is backed by platform-specific implementations (such as EGL on Unix-based platforms) * [ANGLE](https://github.com/servo/mozangle/) is an OpenGL implementation on top of Direct3D which is used in Servo to provide a consistent OpenGL backend on Windows-based platforms ## How Servo's compositor starts From 6aff1c4afade5eda829386dfa083220262f27d1c Mon Sep 17 00:00:00 2001 From: Okhuomon Ajayi Date: Fri, 8 Mar 2024 13:17:23 +0100 Subject: [PATCH 08/11] Update style.md --- docs/components/style.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/components/style.md b/docs/components/style.md index 2ac49c844535..12da45f86729 100644 --- a/docs/components/style.md +++ b/docs/components/style.md @@ -1,13 +1,15 @@ # Servo's style system overview -This document provides an overview of Servo's style system. For more extensive details, refer to the [style doc comments][style-doc], or the [Styling +This document provides an overview of Servo's style system. For more extensive details, +refer to the [style doc comments][style-doc], or the [Styling Overview][wiki-styling-overview] in the wiki, which includes a conversation between Boris Zbarsky and Patrick Walton about how style sharing works. ## Selector Implementation -To ensure compatibility with Stylo (a project integrating Servo's style system into Gecko), selectors must be consistent. +To ensure compatibility with Stylo (a project integrating Servo's style system into Gecko), +selectors must be consistent. The consistency is implemented in [selectors' SelectorImpl][selector-impl], containing the logic related to parsing pseudo-elements and other pseudo-classes From ea07fc78adf49c67f7339ac7d1b478c7a9ae683c Mon Sep 17 00:00:00 2001 From: Okhuomon Ajayi Date: Fri, 8 Mar 2024 13:18:29 +0100 Subject: [PATCH 09/11] Update COMMAND_LINE_ARGS.md --- docs/COMMAND_LINE_ARGS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/COMMAND_LINE_ARGS.md b/docs/COMMAND_LINE_ARGS.md index 2de7975ae909..d47b9db0bf1a 100644 --- a/docs/COMMAND_LINE_ARGS.md +++ b/docs/COMMAND_LINE_ARGS.md @@ -11,7 +11,7 @@ Only arguments that need more explanation will be documented here. # Run ## Enable Experimental Features -Use `--pref` to enable experimental features like the experimental DOM API, JavaScript API and CSS properties. +Use `--pref` to enable experimental features like the experimental DOM APIs, JavaScript APIs and CSS properties. e.g. To enable Web VR and Bluetooth features: ``` From 5cf7a0ab9a8507067cc0678ca6b2611ff433269b Mon Sep 17 00:00:00 2001 From: Okhuomon Ajayi Date: Fri, 8 Mar 2024 13:19:45 +0100 Subject: [PATCH 10/11] Update README.md Co-authored-by: Martin Robinson --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 22d0fef0877f..42f931b3ff12 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,7 @@ See also [Windows Troubleshooting Tips][windows-tips]. - Install the latest version of the [Android command-line tools](https://developer.android.com/studio#command-tools) to `$ANDROID_SDK_ROOT/cmdline-tools/latest`. -- Run the following command to install the necessary components and the path : +- Run the following command to install the necessary components: ```shell sudo $ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager --install "build-tools;33.0.2" \ From 7281b2324feeca7da76dd6ad2e071c07b822b99c Mon Sep 17 00:00:00 2001 From: Martin Robinson Date: Fri, 8 Mar 2024 13:26:05 +0100 Subject: [PATCH 11/11] Update docs/COMMAND_LINE_ARGS.md --- docs/COMMAND_LINE_ARGS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/COMMAND_LINE_ARGS.md b/docs/COMMAND_LINE_ARGS.md index d47b9db0bf1a..aee3d81fc8b8 100644 --- a/docs/COMMAND_LINE_ARGS.md +++ b/docs/COMMAND_LINE_ARGS.md @@ -11,7 +11,7 @@ Only arguments that need more explanation will be documented here. # Run ## Enable Experimental Features -Use `--pref` to enable experimental features like the experimental DOM APIs, JavaScript APIs and CSS properties. +Use `--pref` to enable experimental features like experimental DOM APIs, JavaScript APIs and CSS properties. e.g. To enable Web VR and Bluetooth features: ```