Remove unused flag values and make empty string an option to remove them

Author: JayPanoz

docs/CSS12-user_prefs.md

@@ -37,16 +37,30 @@ You don’t need to remove the variable before setting another value, the new va
 
 #### Removing
 
+You can either remove the style explicitly with `removeProperty()`:
+
 ```
 var root = document.documentElement; 
 
 root.style.removeProperty("name of var");
 ```
 
+Or implicitly by using an empty string as a value with `setProperty()`:
+
+```
+var root = document.documentElement; 
+
+root.style.setProperty("name of var", "");
+```
+
+Setting a property with an empty string as the value will indeed invoke `removeProperty()`, as defined in the [CSS Object Model Spec](https://drafts.csswg.org/cssom/#dom-cssstyledeclaration-setproperty).
+
 ## Flags
 
 Some variables behave like flags. You could also use custom `data-*` attributes or CSS classes to manage the following ones. See the [“Quickstart” doc](../docs/CSS02-quickstart.md) for customization.
 
+By default, those flags are not set. Then their initialization depends on your user settings’ management e.g. apply user settings to all EPUBs, only the ones that have already been customized, etc.
+
 ### User view
 
 Allows to switch between paged and scroll view.
@@ -55,10 +69,12 @@ Allows to switch between paged and scroll view.
 --USER__view
 ```
 
-Possible values: `readium-paged-on` | `readium-scroll-on`
+Supported values: `readium-paged-on` | `readium-scroll-on`
 
 Override class: Chrome (should be applied by any means necessary)
 
+If the flag is not set, ReadiumCSS will fall back to the paged view.
+
 ### Font Family override
 
 Acts as an explicit switch to override the publisher’s `font-family`.
@@ -67,11 +83,11 @@ Acts as an explicit switch to override the publisher’s `font-family`.
 --USER__fontOverride
 ```
 
-Possible values: `readium-font-on` | `readium-font-off`
+Supported value: `readium-font-on`
 
 Override class: None. This flag is required to change the `font-family` user setting.
 
-To switch back to the publisher’s font, you can either change the value to `readium-font-off` or remove the flag.
+To switch back to the publisher’s font, you can either set an empty string as a value or remove the property.
 
 ### Advanced Settings
 
@@ -83,11 +99,11 @@ If you provide users with a “Publisher’s styles” toggle, it must be enable
 --USER__advancedSettings
 ``` 
 
-Possible values: `readium-advanced-on` | `readium-advanced-off`
+Supported value: `readium-advanced-on`
 
 Override class: None. This flag is required to apply the `font-family`, the `font-size` and/or advanced user settings.
 
-To switch back to the publisher’s styles, you can either change the value to `readium-advanced-off` or remove it. This will disable all advanced settings requiring the flag.
+To switch back to the publisher’s styles, you can either set an empty string as a value or remove the property. This will disable all advanced settings requiring the flag.
 
 ### Reading Modes
 
@@ -97,10 +113,12 @@ We currently have two reading modes for night and sepia.
 --USER__appearance
 ```
 
-Possible values: `readium-day-on` | `readium-sepia-on` | `readium-night-on`
+Supported values: `readium-day-on` | `readium-sepia-on` | `readium-night-on`
 
 Override class: Chrome (should be applied by any means necessary)
 
+If the flag is not set, ReadiumCSS will fall back to the day mode.
+
 ### Filters
 
 Please note night mode provides two extra specific variables: 
@@ -109,18 +127,22 @@ Please note night mode provides two extra specific variables:
 --USER__darkenFilter
 ```
 
-Possible values: `readium-darken-on` | `readium-darken-off`
+Supported value: `readium-darken-on`
 
 Override class: Chrome advanced (optional but should be applied by any means necessary if provided to users)
 
+To disable the filter, you can either set an empty string as a value or remove the property.
+
 ```
 --USER__invertFilter
 ```
 
-Possible values: `readium-invert-on` | `readium-invert-off`
+Supported value: `readium-invert-on`
 
 Override class: Chrome advanced (optional but should be applied by any means necessary if provided to users)
 
+To disable the filter, you can either set an empty string as a value or remove the property.
+
 ### Accessibility Normalization
 
 Users may want to normalize text (no bold, no italics, etc.) for accessibility reasons, using a non a11y-specific typeface.
@@ -129,12 +151,14 @@ Users may want to normalize text (no bold, no italics, etc.) for accessibility r
 --USER__a11yNormalize
 ```
 
-Possible values: `readium-a11y-on` | `readium-a11y-off`
+Supported value: `readium-a11y-on`
 
 Required flag: `--USER__fontOverride: readium-font-on`
 
 Override class: User settings advanced (optional but should be applied by any means necessary if provided to users)
 
+To disable the normalization, you can either set an empty string as a value or remove the property.
+
 ## List of variables 
 
 ### Layout 

docs/ReadiumCSS_docs.epub

@@ -50,15 +50,26 @@
         <section id="setting" class="level4">
           <h4 class="sigil_not_in_toc">Setting</h4>
 
-          <pre><code>var root = document.documentElement; root.style.setProperty("name of var", "value");</code></pre>
+          <pre><code>var root = document.documentElement; 
+root.style.setProperty("name of var", "value");</code></pre>
 
           <p>You don’t need to remove the variable before setting another value, the new value will simply override the existing one.</p>
         </section>
 
         <section id="removing" class="level4">
           <h4 class="sigil_not_in_toc">Removing</h4>
 
-          <pre><code>var root = document.documentElement; root.style.removeProperty("name of var");</code></pre>
+		  <p>You can either remove the style explicitly with <code>removeProperty()</code>:</p>
+
+          <pre><code>var root = document.documentElement; 
+root.style.removeProperty("name of var");</code></pre>
+
+		  <p>Or implicitly by using an empty string as a value with <code>setProperty()</code>:</p>
+
+          <pre><code>var root = document.documentElement; 
+root.style.setProperty("name of var", "");</code></pre>
+
+		  <p>Setting a property with an empty string as the value will indeed invoke <code>removeProperty()</code>, as defined in the <a href="https://drafts.csswg.org/cssom/#dom-cssstyledeclaration-setproperty">CSS Object Model Spec</a>.</p>
         </section>
       </section>
     </section>
@@ -68,16 +79,20 @@
 
       <p>Some variables behave like flags. You could also use custom <code>data-*</code> attributes or CSS classes to manage the following ones. See the <a href="../Text/Section-002.xhtml">“Quickstart” doc</a> for customization.</p>
 
+	  <p>By default, those flags are not set. Then their initialization depends on your user settings’ management e.g. apply user settings to all EPUBs, only the ones that have already been customized, etc.</p>
+
       <section id="user-view" class="level3">
         <h3 class="sigil_not_in_toc">User view</h3>
 
         <p>Allows to switch between paged and scroll view.</p>
 
         <pre><code>--USER__view</code></pre>
 
-        <p>Possible values: <code>readium-paged-on</code> | <code>readium-scroll-on</code></p>
+        <p>Supported values: <code>readium-paged-on</code> | <code>readium-scroll-on</code></p>
 
         <p>Override class: Chrome (should be applied by any means necessary)</p>
+
+		<p>If the flag is not set, ReadiumCSS will fall back to the paged view.</p>
       </section>
 
       <section id="font-family-override" class="level3">
@@ -87,11 +102,11 @@
 
         <pre><code>--USER__fontOverride</code></pre>
 
-        <p>Possible values: <code>readium-font-on</code> | <code>readium-font-off</code></p>
+        <p>Supported value: <code>readium-font-on</code></p>
 
         <p>Override class: None. This flag is required to change the <code>font-family</code> user setting.</p>
 
-        <p>To switch back to the publisher’s font, you can either change the value to <code>readium-font-off</code> or remove the flag.</p>
+        <p>To switch back to the publisher’s font, you can either set an empty string as a value or remove the property.</p>
       </section>
 
       <section id="advanced-settings" class="level3">
@@ -103,11 +118,11 @@
 
         <pre><code>--USER__advancedSettings</code></pre>
 
-        <p>Possible values: <code>readium-advanced-on</code> | <code>readium-advanced-off</code></p>
+        <p>Supported value: <code>readium-advanced-on</code></p>
 
         <p>Override class: None. This flag is required to apply the <code>font-family</code>, the <code>font-size</code> and/or advanced user settings.</p>
 
-        <p>To switch back to the publisher’s styles, you can either change the value to <code>readium-advanced-off</code> or remove it. This will disable all advanced settings requiring the flag.</p>
+        <p>To switch back to the publisher’s styles, you can either set an empty string as a value or remove the property. This will disable all advanced settings requiring the flag.</p>
       </section>
 
       <section id="reading-modes" class="level3">
@@ -117,9 +132,11 @@
 
         <pre><code>--USER__appearance</code></pre>
 
-        <p>Possible values: <code>readium-day-on</code> | <code>readium-sepia-on</code> | <code>readium-night-on</code></p>
+        <p>Supported values: <code>readium-day-on</code> | <code>readium-sepia-on</code> | <code>readium-night-on</code></p>
 
         <p>Override class: Chrome (should be applied by any means necessary)</p>
+
+		<p>If the flag is not set, ReadiumCSS will fall back to the day mode.</p>
       </section>
 
       <section id="filters" class="level3">
@@ -129,15 +146,19 @@
 
         <pre><code>--USER__darkenFilter</code></pre>
 
-        <p>Possible values: <code>readium-darken-on</code> | <code>readium-darken-off</code></p>
+        <p>Supported value: <code>readium-darken-on</code></p>
 
         <p>Override class: Chrome advanced (optional but should be applied by any means necessary if provided to users)</p>
 
+		<p>To disable the filter, you can either set an empty string as a value or remove the property.</p>
+
         <pre><code>--USER__invertFilter</code></pre>
 
-        <p>Possible values: <code>readium-invert-on</code> | <code>readium-invert-off</code></p>
+        <p>Supported value: <code>readium-invert-on</code></p>
 
         <p>Override class: Chrome advanced (optional but should be applied by any means necessary if provided to users)</p>
+
+		<p>To disable the filter, you can either set an empty string as a value or remove the property.</p>
       </section>
 
       <section id="accessibility-normalization" class="level3">
@@ -147,11 +168,13 @@
 
         <pre><code>--USER__a11yNormalize</code></pre>
 
-        <p>Possible values: <code>readium-a11y-on</code> | <code>readium-a11y-off</code></p>
+        <p>Supported value: <code>readium-a11y-on</code></p>
 
         <p>Required flag: <code>--USER__fontOverride: readium-font-on</code></p>
 
         <p>Override class: User settings advanced (optional but should be applied by any means necessary if provided to users)</p>
+
+		<p>To disable the normalization, you can either set an empty string as a value or remove the property.</p>
       </section>
     </section>
 

docs/ReadiumCSS_docs/OEBPS/Text/Section-012.xhtml

@@ -8,7 +8,7 @@
     <dc:language>en</dc:language>
     <dc:identifier id="epub-id-1">urn:uuid:91cab77e-946f-4814-9e61-8494a5d5cb0f</dc:identifier>
     <meta name="cover" content="cover_jpg"/>
-    <meta property="dcterms:modified">2020-03-09T16:47:28Z</meta>
+    <meta property="dcterms:modified">2020-03-10T20:56:35Z</meta>
     <meta content="0.9.5" name="Sigil version"/>
     <meta property="schema:accessibilityFeature">displayTransformability</meta>
     <meta property="schema:accessibilityFeature">readingOrder</meta>