Update docs

Author: JayPanoz

docs/CSS12-user_prefs.md

@@ -169,6 +169,30 @@ Supported value: `readium-noRuby-on`
 
 To disable the hiding and show ruby annotations, you can either set an empty string as a value of remove the property.
 
+### Experimental Features Flags
+
+Experimental flags are used to opt-in to and test improvements to existing features. That way they can also be disabled without having to wait on a quickfix in case they are creating new issues.
+
+```
+--RS__experimentalHeaderFiltering
+```
+
+Supported value: `readium-experimentalHeaderFiltering-on`
+
+This attempts to filter out paragraphs that are implicitly headings or part of headers.
+
+To disable the experimental header filtering, you can either set an empty string as a value or remove the property.
+
+```
+--RS__experimentalZoom
+```
+
+Supported value: `readium-experimentalZoom-on`
+
+This attempts to filter out elements that are sized using viewport units and should not be scaled directly.
+
+To disable the experimental zoom, you can either set an empty string as a value or remove the property.
+
 ## List of variables 
 
 ### Layout 

docs/CSS28-migration_guide.md

@@ -257,4 +257,13 @@ As of version `2.0.0-beta.22`, ReadiumCSS provides an experimental stylesheet fo
 
 As well as the patching of zoom for iOS and iPadOS. **Note there is no fallback in case the `zoom` CSS property is not supported.**
 
-Typically, you would use zoom for all web publications, and the rest of the styles if the web publication’s accessibility metadata contains feature `displayTransformability`.
+Typically, you would use zoom for all web publications, and the rest of the styles if the web publication’s accessibility metadata contains feature `displayTransformability`.
+
+## Experimental Features Flags
+
+As of version `2.0.0-beta.23`, ReadiumCSS provides flags as a way to opt-in to and test improvements to existing features. That way they can also be disabled without having to wait on a quickfix in case they are creating new issues.
+
+- `--RS__experimentalHeaderFiltering: readium-experimentalHeaderFiltering-on`: attempts to filter out paragraphs that are implicitly headings or part of headers
+- `--RS__experimentalZoom: readium-experimentalZoom-on`: attemps to filter out elements that are sized using viewport units and should not be scaled directly
+
+These flags are expected to be found on `:root`.

docs/ReadiumCSS_docs.epub

@@ -172,8 +172,6 @@ root.style.setProperty("name of var", "");</code></pre>
 
         <p>Supported value: <code>readium-a11y-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>
 
@@ -185,11 +183,31 @@ root.style.setProperty("name of var", "");</code></pre>
         <pre><code>--USER__no-ruby</code></pre>
 
         <p>Supported value: <code>readium-noRuby-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 hiding and show ruby annotations, you can either set an empty string as a value of remove the property.</p>
+      </section>
+
+      <section id="experimental-features-flags" class="level3">
+        <h3 class="sigil_not_in_toc">Experimental Features Flags</h3>
 
+        <p>Experimental flags are used to opt-in to and test improvements to existing features. That way they can also be disabled without having to wait on a quickfix in case they are creating new issues</p>
+    
+        <pre><code>--RS__experimentalHeaderFiltering</code></pre>
+    
+        <p>Supported value: <code>readium-experimentalHeaderFiltering-on</code></p>
+
+        <p>This attempts to filter out paragraphs that are implicitly headings or part of headers.</p>
+
         <p>To disable the hiding and show ruby annotations, you can either set an empty string as a value of remove the property.</p>
-        </section>
+
+        <pre><code>--RS__experimentalZoom</code></pre>
+
+        <p>Supported value: <code>readium-experimentalZoom-on</code></p>
+
+        <p>This attempts to filter out elements that are sized using viewport units and should not be scaled directly.</p>
+
+        <p>To disable the experimental zoom, you can either set an empty string as a value of remove the property.</p>
+      </section>
     </section>
 
     <section id="list-of-variables" class="level2">

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

@@ -309,6 +309,17 @@ const backgroundColor = defaultColors.RS__backgroundColor;</code></pre>
 
       <p>Typically, you would use zoom for all web publications, and the rest of the styles if the web publication’s accessibility metadata contains feature <code>displayTransformability</code>.</p>
     </section>
+
+    <section id="experimental-flags" class="level2">
+      <h2 id="sigil_toc_id_219">Experimental Flags</h2>
+
+      <p>As of version <code>2.0.0-beta.23</code>, ReadiumCSS provides flags as a way to opt-in to and test improvements to existing features. That way they can also be disabled without having to wait on a quickfix in case they are creating new issues.</p>
+
+      <ul>
+        <li><code>--RS__experimentalHeaderFiltering: readium-experimentalHeaderFiltering-on</code>: attempts to filter out paragraphs that are implicitly headings or part of headers</li>
+        <li><code>--RS__experimentalZoom: readium-experimentalZoom-on</code>: attemps to filter out elements that are sized using viewport units and should not be scaled directly</li>
+      </ul>
+    </section>
   </section>
 </body>
 </html>

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

@@ -759,6 +759,9 @@
         <li>
           <a href="../Text/Section-028.xhtml#sigil_toc_id_218">Experimental Web Publications stylesheet</a>
         </li>
+        <li>
+          <a href="../Text/Section-028.xhtml#sigil_toc_id_219">Experimental Features Flags</a>
+        </li>
       </ol>
       </li>
     </ol>

docs/ReadiumCSS_docs/OEBPS/Text/nav.xhtml

@@ -1389,6 +1389,12 @@
         </navLabel>
         <content src="Text/Section-028.xhtml#sigil_toc_id_218"/>
       </navPoint>
+      <navPoint id="navPoint231">
+        <navLabel>
+          <text>Experimental Features Flags</text>
+        </navLabel>
+        <content src="Text/Section-028.xhtml#sigil_toc_id_219"/>
+      </navPoint>
     </navPoint>
   </navMap>
 </ncx>