From 785db37bd2866d369757e072000ffc19973121d2 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Tue, 3 Dec 2024 20:01:27 -0800
Subject: [PATCH 1/7] Document how to specify a static resource bundle to load
 as the last one in Classic UI

---
 docs/classic-ui/static-resources.md | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/docs/classic-ui/static-resources.md b/docs/classic-ui/static-resources.md
index 84a8aec56..002c307eb 100644
--- a/docs/classic-ui/static-resources.md
+++ b/docs/classic-ui/static-resources.md
@@ -52,7 +52,7 @@ You can register a CSS resource in the same way.
   </registry>
 ```
 
-Registering a JavaScript file and a CSS file in the same bundle is also possible.
+You can also register a JavaScript file and a CSS file in the same bundle.
 
 ```xml 
 <registry>
@@ -100,4 +100,20 @@ The following attributes are available for registering a static resource:
 
 ## Loading order of resources
 
-`depends` is used to define the loading order of resources by specifying the name of the depending bundle.
+You can use the `depends` attribute to define the order in which resources load.
+
+You can specify a list of either the names of the bundles on which this bundle depends or a single list item of `["all"]`.
+In the latter case of `["all"]` for a bundle, all other JavaScript and CSS resources in their resource groups will render before this bundle, making it the final bundle to render in its resource group.
+This includes the theme, such as Barceloneta's theme CSS.
+
+This feature lets you override a theme with custom CSS from a bundle.
+Previously you had to add the CSS customizations to the registry via the `custom_css` settings, then update the registry after every change.
+
+```{versionadded} Plone 6.0.14
+The `depends` attribute may be assigned the value of `["all"]`, making this bundle render last, after all other bundles.
+```
+
+```{note}
+Setting `depends=["all"]` does not affect custom CSS that you define in the {guilabel}`Theming` control panel, which _always_ renders as the last style resource.
+It only affects bundles, not control panel settings.
+```

From 77770c35eff72b5ad405ac5bfb3c73d8b597491c Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Wed, 4 Dec 2024 05:44:07 -0800
Subject: [PATCH 2/7] Merge content from #1803

---
 docs/classic-ui/static-resources.md | 65 ++++++++++++++++++-----------
 1 file changed, 40 insertions(+), 25 deletions(-)

diff --git a/docs/classic-ui/static-resources.md b/docs/classic-ui/static-resources.md
index 002c307eb..ccfa9f24f 100644
--- a/docs/classic-ui/static-resources.md
+++ b/docs/classic-ui/static-resources.md
@@ -12,7 +12,11 @@ myst:
 # Static resources
 
 We often want to ship a website with a static resource, such as an image, icon, CSS, or JavaScript file.
-For this, we need to register static resources.
+For CSS and JavaScript files, we can use the resource registry to register, then deliver, them to the client browser.
+
+The resource registry provides a programmatic way, either in code or through the web, to extend and configure the dependencies between static resources.
+It also automatically manages caching of static resources.
+If you were to hard-code these resources in templates with `<link>` or `<script>` tags, you would not have these advantages.
 
 ```{seealso}
 For some additional implementation information, see {ref}`classic-ui-theming-from-scratch-theme-label`.
@@ -33,7 +37,7 @@ The JavaScript files have to be in the `browser/static` folder of your Plone 6 p
   <records interface="plone.base.interfaces.resources.IBundleRegistry" prefix="plone.bundles/jscript">
     <value key="enabled">True</value>
     <value key="jscompilation">++plone++myproject.site/javascript.min.js</value>
-    <value key="load_async">False</value> 
+    <value key="load_async">False</value>
     <value key="load_defer">False</value>
     <value key="depends">plone</value>
   </records>
@@ -41,7 +45,7 @@ The JavaScript files have to be in the `browser/static` folder of your Plone 6 p
 ```
 
 You can register a CSS resource in the same way.
-  
+
 ```xml
     <registry>
     <records interface="plone.base.interfaces.resources.IBundleRegistry" prefix="plone.bundles/css">
@@ -54,13 +58,13 @@ You can register a CSS resource in the same way.
 
 You can also register a JavaScript file and a CSS file in the same bundle.
 
-```xml 
+```xml
 <registry>
   <records interface="plone.base.interfaces.resources.IBundleRegistry" prefix="plone.bundles/css">
     <value key="enabled">True</value>
     <value key="csscompilation">++plone++myproject.site/style.min.css</value>
     <value key="jscompilation">++plone++myproject.site/javascript.min.js</value>
-    <value key="load_async">False</value> 
+    <value key="load_async">False</value>
     <value key="load_defer">False</value>
     <value key="depends">plone</value>
   </records>
@@ -72,34 +76,53 @@ You can also register a JavaScript file and a CSS file in the same bundle.
 
 ## Available attributes
 
-The following attributes are available for registering a static resource:
+The following attributes are available for registering a static resource.
 
 `enabled`
-:   Whether the bundle is enabled or not.
+:   Boolean.
+    Whether the bundle is enabled or not.
     If it is disabled, the bundle will not be loaded.
 
 `jscompilation`
-:   The path to the compiled JavaScript file.
+:   String.
+    The path to the compiled JavaScript file.
 
 `csscompilation`
-:   The path to the compiled CSS file.
+:   String.
+    The path to the compiled CSS file.
 
 `depends`
-:   A list of bundles that this bundle depends on.
+:   String.
+    A comma-separated list of bundles that this bundle depends on.
+    For a single dependency, do not insert commas.
+
+    When a bundle depends on another one, its `<script>` or `<link>` tag is rendered after the bundle it depends on.
+
+    If the bundle's dependencies do not exist, then the bundle will not render.
+
+    The `depends` attribute may be assigned the value of `all`, making this bundle render last, after all other bundles.
+    The `all` value lets you load CSS files after the automatically added theme resources and override CSS declarations from your own custom CSS files.
+
+    ```{note}
+    Setting `depends` to `all` does not affect custom CSS that you define in the {guilabel}`Theming` control panel, which _always_ renders as the last style resource.
+    It only affects bundles, not control panel settings.
+    ```
+
+    ```{versionadded} Plone 6.0.14
+    `depends` value of `all`.
+    ```
 
 `load_async`
-:   Whether the bundle should be loaded asynchronously or not.
+:   Boolean.
+    Whether the bundle should be loaded asynchronously or not.
     *Only JavaScript*
 
 `load_defer`
-:   Whether the bundle should be loaded deferred or not.
+:   Boolean.
+    Whether the bundle should be loaded deferred or not.
+    If you use `load_async`, this attribute has no effect.
     *Only JavaScript*
 
-
-(classic-ui-static-resources-loading-order-label)=
-
-## Loading order of resources
-
 You can use the `depends` attribute to define the order in which resources load.
 
 You can specify a list of either the names of the bundles on which this bundle depends or a single list item of `["all"]`.
@@ -109,11 +132,3 @@ This includes the theme, such as Barceloneta's theme CSS.
 This feature lets you override a theme with custom CSS from a bundle.
 Previously you had to add the CSS customizations to the registry via the `custom_css` settings, then update the registry after every change.
 
-```{versionadded} Plone 6.0.14
-The `depends` attribute may be assigned the value of `["all"]`, making this bundle render last, after all other bundles.
-```
-
-```{note}
-Setting `depends=["all"]` does not affect custom CSS that you define in the {guilabel}`Theming` control panel, which _always_ renders as the last style resource.
-It only affects bundles, not control panel settings.
-```

From f80c6103029f37c3e9bfb9c5fc70292f36442881 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Wed, 4 Dec 2024 05:46:45 -0800
Subject: [PATCH 3/7] Add clause for multiple `all`s

---
 docs/classic-ui/static-resources.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/classic-ui/static-resources.md b/docs/classic-ui/static-resources.md
index ccfa9f24f..892aa005e 100644
--- a/docs/classic-ui/static-resources.md
+++ b/docs/classic-ui/static-resources.md
@@ -103,6 +103,8 @@ The following attributes are available for registering a static resource.
     The `depends` attribute may be assigned the value of `all`, making this bundle render last, after all other bundles.
     The `all` value lets you load CSS files after the automatically added theme resources and override CSS declarations from your own custom CSS files.
 
+    If you set multiple bundles to `all`, then these bundles will render in the order in which you define them.
+
     ```{note}
     Setting `depends` to `all` does not affect custom CSS that you define in the {guilabel}`Theming` control panel, which _always_ renders as the last style resource.
     It only affects bundles, not control panel settings.

From 4c6bce22de2d91eaedf19096bc41be94ebb1f528 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Wed, 4 Dec 2024 05:57:01 -0800
Subject: [PATCH 4/7] More merge and removal of redundant content

---
 docs/classic-ui/static-resources.md | 11 +----------
 1 file changed, 1 insertion(+), 10 deletions(-)

diff --git a/docs/classic-ui/static-resources.md b/docs/classic-ui/static-resources.md
index 892aa005e..d0a8f558c 100644
--- a/docs/classic-ui/static-resources.md
+++ b/docs/classic-ui/static-resources.md
@@ -106,6 +106,7 @@ The following attributes are available for registering a static resource.
     If you set multiple bundles to `all`, then these bundles will render in the order in which you define them.
 
     ```{note}
+    You can also add custom CSS through-the-web via the {guilabel}`Theming` control panel, under {menuselection}`Site Setup --> Theming --> Advanced settings --> Custom Styles`.
     Setting `depends` to `all` does not affect custom CSS that you define in the {guilabel}`Theming` control panel, which _always_ renders as the last style resource.
     It only affects bundles, not control panel settings.
     ```
@@ -124,13 +125,3 @@ The following attributes are available for registering a static resource.
     Whether the bundle should be loaded deferred or not.
     If you use `load_async`, this attribute has no effect.
     *Only JavaScript*
-
-You can use the `depends` attribute to define the order in which resources load.
-
-You can specify a list of either the names of the bundles on which this bundle depends or a single list item of `["all"]`.
-In the latter case of `["all"]` for a bundle, all other JavaScript and CSS resources in their resource groups will render before this bundle, making it the final bundle to render in its resource group.
-This includes the theme, such as Barceloneta's theme CSS.
-
-This feature lets you override a theme with custom CSS from a bundle.
-Previously you had to add the CSS customizations to the registry via the `custom_css` settings, then update the registry after every change.
-

From d3748d886f43fedbc27e78b56fd645f38941adbd Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Fri, 6 Dec 2024 00:33:41 -0800
Subject: [PATCH 5/7] Update docs/classic-ui/static-resources.md

Co-authored-by: Peter Mathis <petschki@users.noreply.github.com>
---
 docs/classic-ui/static-resources.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/classic-ui/static-resources.md b/docs/classic-ui/static-resources.md
index d0a8f558c..8977c250c 100644
--- a/docs/classic-ui/static-resources.md
+++ b/docs/classic-ui/static-resources.md
@@ -103,7 +103,7 @@ The following attributes are available for registering a static resource.
     The `depends` attribute may be assigned the value of `all`, making this bundle render last, after all other bundles.
     The `all` value lets you load CSS files after the automatically added theme resources and override CSS declarations from your own custom CSS files.
 
-    If you set multiple bundles to `all`, then these bundles will render in the order in which you define them.
+    If you set multiple bundles to `all`, then these bundles will render in alphabetical order by its name.
 
     ```{note}
     You can also add custom CSS through-the-web via the {guilabel}`Theming` control panel, under {menuselection}`Site Setup --> Theming --> Advanced settings --> Custom Styles`.

From 0ef1bb7c4192f47d2b76be0b96d128684f7ec0a8 Mon Sep 17 00:00:00 2001
From: Johannes Raggam <thetetet@gmail.com>
Date: Fri, 6 Dec 2024 10:14:39 +0100
Subject: [PATCH 6/7] Update docs/classic-ui/static-resources.md

Co-authored-by: Yuri <yurj@alfa.it>
---
 docs/classic-ui/static-resources.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/classic-ui/static-resources.md b/docs/classic-ui/static-resources.md
index 8977c250c..9bfec1577 100644
--- a/docs/classic-ui/static-resources.md
+++ b/docs/classic-ui/static-resources.md
@@ -56,7 +56,7 @@ You can register a CSS resource in the same way.
   </registry>
 ```
 
-You can also register a JavaScript file and a CSS file in the same bundle.
+It is also possible to include both a JavaScript file and a CSS file in the same bundle.
 
 ```xml
 <registry>

From 0d5b158f038b2cc95f8c311a0075330ab6c9e07d Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Fri, 6 Dec 2024 01:32:58 -0800
Subject: [PATCH 7/7] Retain friendly "you", but use "both"

---
 docs/classic-ui/static-resources.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/classic-ui/static-resources.md b/docs/classic-ui/static-resources.md
index 9bfec1577..5234813e9 100644
--- a/docs/classic-ui/static-resources.md
+++ b/docs/classic-ui/static-resources.md
@@ -56,7 +56,7 @@ You can register a CSS resource in the same way.
   </registry>
 ```
 
-It is also possible to include both a JavaScript file and a CSS file in the same bundle.
+You can also register both a JavaScript file and a CSS file in the same bundle.
 
 ```xml
 <registry>