From 9463e2b6880502b1685f1ed458320f15c995a89c Mon Sep 17 00:00:00 2001
From: alexander-akait <4567934+alexander-akait@users.noreply.github.com>
Date: Sun, 1 Nov 2026 00:35:20 +0000
Subject: [PATCH] docs: update

---
 OPTIONS.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/OPTIONS.md b/OPTIONS.md
index bdeed49170e..f89c8cf7dba 100644
--- a/OPTIONS.md
+++ b/OPTIONS.md
@@ -1151,7 +1151,7 @@ Options
   --no-optimization-minimize-css-custom-media                                        Negative 'optimization-minimize-css-custom-media' option.
   --optimization-minimize-css-custom-selectors                                       Resolve the `@custom-selector` at-rule: write the selector list a name stands for as `:is(…)` wherever a selector asks for it, and drop the rule that named it. `@custom-selector :--heading h1, h2` with `:--heading` becomes `:is(h1, h2)`. Off by default, for the reason `customMedia` is: `module.parser.css.customSelectors` already resolves it in every stylesheet webpack parses. Rules are read as `customMedia` reads them, and a name is written out only where the target reads `:is()`.
   --no-optimization-minimize-css-custom-selectors                                    Negative 'optimization-minimize-css-custom-selectors' option.
-  --optimization-minimize-css-drop-overridden-declarations                           Drop a declaration a later one in the same block overrides even where nothing states that the target can read the later value. Off by default. With a `browserslist` target this is already done wherever every browser it names is known to read the later value, so the option only widens the case where no target is selected and there are no engines to name — which is what csso and cssnano do unconditionally. What it gives up is the fallback pair: `color:#c65d06;color:lab(50% 100 -100)` loses the hex, so an engine that cannot read `lab()` is left with nothing. A selection naming a browser the compat tables do not cover is still answered for the whole of it rather than by this option, since naming a browser states a target the option does not override.
+  --optimization-minimize-css-drop-overridden-declarations                           Drop a declaration a later one in the same block overrides even where no target is selected, assuming the engines shipping today: wherever Chromium, Gecko and WebKit each read the later value. Off by default. With a `browserslist` target this is already done wherever every browser it names is known to read the later value, so the option only widens the case where no target is selected and there are no engines to name — which is what csso and cssnano do unconditionally. What it gives up is the fallback pair: `color:#c65d06;color:lab(50% 100 -100)` loses the hex, so an engine that cannot read `lab()` is left with nothing. A selection naming a browser the compat tables do not cover is still answered for the whole of it rather than by this option, since naming a browser states a target the option does not override.
   --no-optimization-minimize-css-drop-overridden-declarations                        Negative 'optimization-minimize-css-drop-overridden-declarations' option.
   --optimization-minimize-css-extract-comments [value]                               Which comments a minimized asset gives up to its `[file].LICENSE.txt`.
   --no-optimization-minimize-css-extract-comments                                    Negative 'optimization-minimize-css-extract-comments' option.
@@ -1220,7 +1220,7 @@ Options
   --no-optimization-minimize-html-normalize-url-attributes                           Negative 'optimization-minimize-html-normalize-url-attributes' option.
   --optimization-minimize-html-remove-empty-attributes                               Drop an attribute whose empty or all-whitespace value leaves it in the state its absence gives: the globals `class`, `id`, `style`, `dir`, `accesskey`, `itemprop`, `itemref`, `itemtype` and `part`, and every attribute reflecting a token list on the elements the spec defines it for — `rel` on `<a>`, `<area>`, `<form>` and `<link>`, `ping` on `<a>` and `<area>`, `headers` on `<td>` and `<th>`, `blocking` on `<link>`, `<script>` and `<style>`, `sizes` on `<link>`, `for` on `<output>` — where an empty list is no tokens. Anywhere else that spelling is an author attribute whose meaning is a script's, so `<x-foo rel="">` and `<label for="">` keep it. Off by default: an attribute selector matches on presence, so `[class]` stops matching. Never dropped: `title` and `lang`, whose empty value means what absence does not; `sandbox`, whose empty list is the most restrictive state an `<iframe>` has; and an event handler, whose empty body still compiles to a function where absence reads null.
   --no-optimization-minimize-html-remove-empty-attributes                            Negative 'optimization-minimize-html-remove-empty-attributes' option.
-  --optimization-minimize-html-remove-empty-elements                                 Drop an element that has no children and no attributes. Kept anyway when its bare form is still doing a job (`canvas`, `slot`, `template`, `textarea`, `progress`, `meter`, `output`, `dialog`, and the table structure), when it is a void element, or when it is foreign content. Off by default: CSS can give an empty element a size or a `::before`, and the minifier cannot see the stylesheet. Emptiness is read off the output rather than the source, so a run of nested empties goes together and an element left empty only by a dropped comment or by whitespace `collapseWhitespace` deletes goes with them.
+  --optimization-minimize-html-remove-empty-elements                                 Drop an element that has no children and no attributes, where its bare form renders nothing and nothing reads it: a generic container such as `div`, `span` or `section`, an inline phrase element, an empty `title`, `script` or `style`, or an attribute-less `meta`, `link` or `base`. Every other element is kept, including widgets, list items, elements with margins and custom elements. Off by default: CSS can give an empty element a size or a `::before`, and the minifier cannot see the stylesheet. Emptiness is read off the output rather than the source, so a run of nested empties goes together and an element left empty only by a dropped comment or by whitespace `collapseWhitespace` deletes goes with them.
   --no-optimization-minimize-html-remove-empty-elements                              Negative 'optimization-minimize-html-remove-empty-elements' option.
   --optimization-minimize-html-remove-implied-tags [value]                           How much of the `<html>` / `<head>` / `<body>` shell §13.1.2.4 lets the parser imply may be left out. Every other optional tag goes unconditionally — nothing can observe that — but these six are what a consumer reading the page with a regexp rather than a parser looks for. `"smart"`, the default, leaves out the one such a reader never matches: the `<html>` start tag, which is omittable only when it carries no attribute at all, so the `<html lang=en>` anyone greps for keeps its tag anyway. `</html>` stays with it, since a truncation check reads a page as complete by finding one. `true` (or `"all"`) leaves out all six, which is where a crawler matching on `<body>` stops finding one; `false` leaves out none. A tag also stays wherever the spec keeps it: an attribute to carry, a comment minifying does not drop, whitespace opening the element, or a `meta` / `noscript` / `link` / `script` / `style` / `template` element opening the body.
   --no-optimization-minimize-html-remove-implied-tags                                Negative 'optimization-minimize-html-remove-implied-tags' option.
@@ -1253,7 +1253,7 @@ Options
   --no-optimization-minimize-options-css-custom-media                                Negative 'optimization-minimize-options-css-custom-media' option.
   --optimization-minimize-options-css-custom-selectors                               Resolve the `@custom-selector` at-rule: write the selector list a name stands for as `:is(…)` wherever a selector asks for it, and drop the rule that named it. `@custom-selector :--heading h1, h2` with `:--heading` becomes `:is(h1, h2)`. Off by default, for the reason `customMedia` is: `module.parser.css.customSelectors` already resolves it in every stylesheet webpack parses. Rules are read as `customMedia` reads them, and a name is written out only where the target reads `:is()`.
   --no-optimization-minimize-options-css-custom-selectors                            Negative 'optimization-minimize-options-css-custom-selectors' option.
-  --optimization-minimize-options-css-drop-overridden-declarations                   Drop a declaration a later one in the same block overrides even where nothing states that the target can read the later value. Off by default. With a `browserslist` target this is already done wherever every browser it names is known to read the later value, so the option only widens the case where no target is selected and there are no engines to name — which is what csso and cssnano do unconditionally. What it gives up is the fallback pair: `color:#c65d06;color:lab(50% 100 -100)` loses the hex, so an engine that cannot read `lab()` is left with nothing. A selection naming a browser the compat tables do not cover is still answered for the whole of it rather than by this option, since naming a browser states a target the option does not override.
+  --optimization-minimize-options-css-drop-overridden-declarations                   Drop a declaration a later one in the same block overrides even where no target is selected, assuming the engines shipping today: wherever Chromium, Gecko and WebKit each read the later value. Off by default. With a `browserslist` target this is already done wherever every browser it names is known to read the later value, so the option only widens the case where no target is selected and there are no engines to name — which is what csso and cssnano do unconditionally. What it gives up is the fallback pair: `color:#c65d06;color:lab(50% 100 -100)` loses the hex, so an engine that cannot read `lab()` is left with nothing. A selection naming a browser the compat tables do not cover is still answered for the whole of it rather than by this option, since naming a browser states a target the option does not override.
   --no-optimization-minimize-options-css-drop-overridden-declarations                Negative 'optimization-minimize-options-css-drop-overridden-declarations' option.
   --optimization-minimize-options-css-extract-comments [value]                       Which comments a minimized asset gives up to its `[file].LICENSE.txt`.
   --no-optimization-minimize-options-css-extract-comments                            Negative 'optimization-minimize-options-css-extract-comments' option.
@@ -1322,7 +1322,7 @@ Options
   --no-optimization-minimize-options-html-normalize-url-attributes                   Negative 'optimization-minimize-options-html-normalize-url-attributes' option.
   --optimization-minimize-options-html-remove-empty-attributes                       Drop an attribute whose empty or all-whitespace value leaves it in the state its absence gives: the globals `class`, `id`, `style`, `dir`, `accesskey`, `itemprop`, `itemref`, `itemtype` and `part`, and every attribute reflecting a token list on the elements the spec defines it for — `rel` on `<a>`, `<area>`, `<form>` and `<link>`, `ping` on `<a>` and `<area>`, `headers` on `<td>` and `<th>`, `blocking` on `<link>`, `<script>` and `<style>`, `sizes` on `<link>`, `for` on `<output>` — where an empty list is no tokens. Anywhere else that spelling is an author attribute whose meaning is a script's, so `<x-foo rel="">` and `<label for="">` keep it. Off by default: an attribute selector matches on presence, so `[class]` stops matching. Never dropped: `title` and `lang`, whose empty value means what absence does not; `sandbox`, whose empty list is the most restrictive state an `<iframe>` has; and an event handler, whose empty body still compiles to a function where absence reads null.
   --no-optimization-minimize-options-html-remove-empty-attributes                    Negative 'optimization-minimize-options-html-remove-empty-attributes' option.
-  --optimization-minimize-options-html-remove-empty-elements                         Drop an element that has no children and no attributes. Kept anyway when its bare form is still doing a job (`canvas`, `slot`, `template`, `textarea`, `progress`, `meter`, `output`, `dialog`, and the table structure), when it is a void element, or when it is foreign content. Off by default: CSS can give an empty element a size or a `::before`, and the minifier cannot see the stylesheet. Emptiness is read off the output rather than the source, so a run of nested empties goes together and an element left empty only by a dropped comment or by whitespace `collapseWhitespace` deletes goes with them.
+  --optimization-minimize-options-html-remove-empty-elements                         Drop an element that has no children and no attributes, where its bare form renders nothing and nothing reads it: a generic container such as `div`, `span` or `section`, an inline phrase element, an empty `title`, `script` or `style`, or an attribute-less `meta`, `link` or `base`. Every other element is kept, including widgets, list items, elements with margins and custom elements. Off by default: CSS can give an empty element a size or a `::before`, and the minifier cannot see the stylesheet. Emptiness is read off the output rather than the source, so a run of nested empties goes together and an element left empty only by a dropped comment or by whitespace `collapseWhitespace` deletes goes with them.
   --no-optimization-minimize-options-html-remove-empty-elements                      Negative 'optimization-minimize-options-html-remove-empty-elements' option.
   --optimization-minimize-options-html-remove-implied-tags [value]                   How much of the `<html>` / `<head>` / `<body>` shell §13.1.2.4 lets the parser imply may be left out. Every other optional tag goes unconditionally — nothing can observe that — but these six are what a consumer reading the page with a regexp rather than a parser looks for. `"smart"`, the default, leaves out the one such a reader never matches: the `<html>` start tag, which is omittable only when it carries no attribute at all, so the `<html lang=en>` anyone greps for keeps its tag anyway. `</html>` stays with it, since a truncation check reads a page as complete by finding one. `true` (or `"all"`) leaves out all six, which is where a crawler matching on `<body>` stops finding one; `false` leaves out none. A tag also stays wherever the spec keeps it: an attribute to carry, a comment minifying does not drop, whitespace opening the element, or a `meta` / `noscript` / `link` / `script` / `style` / `template` element opening the body.
   --no-optimization-minimize-options-html-remove-implied-tags                        Negative 'optimization-minimize-options-html-remove-implied-tags' option.