Reword/Improve API doc

Re #78

Author: JayPanoz

docs/CSS19-api.md

@@ -2,6 +2,8 @@
 
 [Implementers’ doc]
 
+This document is meant to list all the customizable medias and flags (to be found in `ReadiumCSS-config.css`), as well as all the CSS variables for Reading System and User styles available in the `dist` stylesheets.
+
 As a reminder, the priority is, in general: 
 
 ```
@@ -30,6 +32,8 @@ root.style.removeProperty("--USER__var");
 
 ## Customizable medias
 
+You will find those customizable medias in `ReadiumCSS-config.css`. The values defined are used in media queries to control use of the auto pagination model.
+
 * * *
 
 ```
@@ -66,21 +70,33 @@ The maximum device width of the mobile device for which the auto pagination mode
 
 ## Customizable flags
 
-Those custom selectors can be customized before runtime. Check the [“Quickstart” doc](../docs/CSS02-quickstart.md) for further details.
+You will find those customizable flags in `ReadiumCSS-config.css`, and can think of the preset values as boolean inline styles: if they are set on the `:root` element (i.e. `html`) then the flag is enabled. If another value is, or they are removed, then the flag is disabled.
+
+Those custom selectors can only be customized before runtime. You could for example use a class or a custom attribute instead of an inline style. Check the [“User Preferences”](../docs/CSS12-user_prefs.md#flags) and [“Quickstart”](../docs/CSS02-quickstart.md) docs for further details.
 
-The “dummy CSS variable” is a recommended CSS custom property name you can use to set the default value if you don’t customize those selectors and just keep the default.
+**Note:** The preset is not a default implementers should use. Indeed, the initialization of those flags depends on your user settings’ management e.g. apply user settings to all EPUBs, only the ones that have already been customized, etc.
 
 * * * 
 
 ```
-:--scroll-view
+:--paged-view
 ```
 
-Default is `readium-scroll-on`
+Preset: `--USER__view: readium-paged-on`
 
 Scope: `html`
 
-Dummy CSS variable: `--USER__view`
+Override class: Chrome (should be applied by any means necessary)
+
+* * * 
+
+```
+:--scroll-view
+```
+
+Preset: `--USER__view: readium-scroll-on`
+
+Scope: `html`
 
 Override class: Chrome (should be applied by any means necessary)
 
@@ -90,12 +106,10 @@ Override class: Chrome (should be applied by any means necessary)
 :--font-override
 ```
 
-Default is `readium-font-on`
+Preset: `--USER__fontOverride: readium-font-on`
 
 Scope: `html`
 
-Dummy CSS variable: `--USER__fontOverride`
-
 Override class: None. This flag is required to change the `font-family` user setting.
 
 * * * 
@@ -104,12 +118,10 @@ Override class: None. This flag is required to change the `font-family` user set
 :--advanced-settings
 ```
 
-Default is `readium-advanced-on`
+Preset: `--USER__advancedSettings: readium-advanced-on`
 
 Scope: `html`
 
-Dummy CSS variable: `--USER__advancedSettings`
-
 Override class: None. This flag is required to apply the `font-family`, the `font-size` and/or advanced user settings.
 
 * * * 
@@ -118,12 +130,10 @@ Override class: None. This flag is required to apply the `font-family`, the `fon
 :--sepia-mode
 ```
 
-Default is `readium-sepia-on`
+Preset: `--USER__appearance: readium-sepia-on`
 
 Scope: `html`
 
-Dummy CSS variable: `--USER__appearance`
-
 Override class: Chrome (should be applied by any means necessary)
 
 This flag applies the sepia reading mode.
@@ -134,12 +144,10 @@ This flag applies the sepia reading mode.
 :--night-mode
 ```
 
-Default is `readium-night-on`
+Preset: `--USER__appearance: readium-night-on`
 
 Scope: `html`
 
-Dummy CSS variable: `--USER__appearance`
-
 Override class: Chrome (should be applied by any means necessary)
 
 This flag applies the night reading mode.
@@ -150,12 +158,10 @@ This flag applies the night reading mode.
 :--darken-filter
 ```
 
-Default is `readium-darken-on`
+Preset: `--USER__darkenImages: readium-darken-on`
 
 Scope: `html`
 
-Dummy CSS variable: `--USER__darkenImages`
-
 Override class: Chrome advanced (optional but should be applied by any means necessary if provided to users)
 
 This will only apply in night mode to darken images and impact `img`.
@@ -166,12 +172,10 @@ This will only apply in night mode to darken images and impact `img`.
 :--invert-filter
 ```
 
-Default is `readium-invert-on`
+Preset: `--USER__invertImages: readium-invert-on`
 
 Scope: `html`
 
-Dummy CSS variable: `--USER__invertImages`
-
 Override class: Chrome advanced (optional but should be applied by any means necessary if provided to users)
 
 This will only apply in night mode to invert images and impact `img`.
@@ -182,12 +186,10 @@ This will only apply in night mode to invert images and impact `img`.
 :--a11y-normalize
 ```
 
-Default is `readium-a11y-on`
+Preset: `--USER__a11yNormalize: readium-a11y-on`
 
 Scope: `html`
 
-Dummy CSS variable: `--USER__a11yNormalize`
-
 Required flag: `:--fontOverride`
 
 Override class: User settings advanced (optional but should be applied by any means necessary if provided to users)

docs/ReadiumCSS_docs.epub

@@ -15,6 +15,8 @@
 
     <p>[Implementers’ doc]</p>
 
+    <p>This document is meant to list all the customizable medias and flags (to be found in <code>ReadiumCSS-config.css</code>), as well as all the CSS variables for Reading System and User styles available in the <code>dist</code> stylesheets.</p>
+
     <p>As a reminder, the priority is, in general:</p>
 
     <pre><code>USER &gt; AUTHOR &gt; RS</code></pre>
@@ -40,6 +42,8 @@
     <section id="customizable-medias" class="level2">
       <h2 id="sigil_toc_id_183">Customizable medias</h2>
 
+      <p>You will find those customizable medias in <code>ReadiumCSS-config.css</code>. The values defined are used in media queries to control use of the auto pagination model.</p>
+
       <hr/>
 
       <pre><code>--responsive-columns</code></pre>
@@ -72,56 +76,60 @@
     <section id="customizable-flags" class="level2">
       <h2 id="sigil_toc_id_184">Customizable flags</h2>
 
-      <p>Those custom selectors can be customized before runtime. Check the <a href="../Text/Section-002.xhtml">“Quickstart” doc</a> for further details.</p>
+      <p>You will find those customizable flags in <code>ReadiumCSS-config.css</code>, and can think of the preset values as boolean inline styles: if they are set on the <code>:root</code> element (i.e. <code>html</code>) then the flag is enabled. If another value is, or they are removed, then the flag is disabled.</p>
+
+      <p>Those custom selectors can only be customized before runtime. You could for example use a class or a custom attribute instead of an inline style. Check the <a href="../Text/Section-012.xhtml#sigil_toc_id_177">“User Settings”</a> and <a href="../Text/Section-002.xhtml">“Quickstart”</a> docs for further details.</p>
 
-      <p>The “dummy CSS variable” is a recommended CSS custom property name you can use to set the default value if you don’t customize those selectors and just keep the default.</p>
+      <p><strong>Note:</strong> The preset is not a default implementers should use. Indeed, the initialization of those flags depends on your user settings’ management e.g. apply user settings to all EPUBs, only the ones that have already been customized, etc.</p>
 
       <hr/>
 
-      <pre><code>:--scroll-view</code></pre>
+      <pre><code>:--paged-view</code></pre>
 
-      <p>Default is <code>readium-scroll-on</code></p>
+      <p>Preset: <code>--USER__view: readium-paged-on</code></p>
 
       <p>Scope: <code>html</code></p>
 
-      <p>Dummy CSS variable: <code>--USER__view</code></p>
+      <p>Override class: Chrome (should be applied by any means necessary)</p>
+
+      <hr/>
+
+      <pre><code>:--scroll-view</code></pre>
+
+      <p>Preset: <code>--USER__view: readium-scroll-on</code></p>
+
+      <p>Scope: <code>html</code></p>
 
       <p>Override class: Chrome (should be applied by any means necessary)</p>
 
       <hr/>
 
       <pre><code>:--font-override</code></pre>
 
-      <p>Default is <code>readium-font-on</code></p>
+      <p>Preset: <code>--USER__fontOverride: readium-font-on</code></p>
 
       <p>Scope: <code>html</code></p>
 
-      <p>Dummy CSS variable: <code>--USER__fontOverride</code></p>
-
       <p>Override class: None. This flag is required to change the <code>font-family</code> user setting.</p>
 
       <hr/>
 
       <pre><code>:--advanced-settings</code></pre>
 
-      <p>Default is <code>readium-advanced-on</code></p>
+      <p>Preset: <code>--USER__advancedSettings: readium-advanced-on</code></p>
 
       <p>Scope: <code>html</code></p>
 
-      <p>Dummy CSS variable: <code>--USER__advancedSettings</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>
 
       <hr/>
 
       <pre><code>:--sepia-mode</code></pre>
 
-      <p>Default is <code>readium-sepia-on</code></p>
+      <p>Preset: <code>--USER__appearance: readium-sepia-on</code></p>
 
       <p>Scope: <code>html</code></p>
 
-      <p>Dummy CSS variable: <code>--USER__appearance</code></p>
-
       <p>Override class: Chrome (should be applied by any means necessary)</p>
 
       <p>This flag applies the sepia reading mode.</p>
@@ -130,12 +138,10 @@
 
       <pre><code>:--night-mode</code></pre>
 
-      <p>Default is <code>readium-night-on</code></p>
+      <p>Preset: <code>--USER__appearance: readium-night-on</code></p>
 
       <p>Scope: <code>html</code></p>
 
-      <p>Dummy CSS variable: <code>--USER__appearance</code></p>
-
       <p>Override class: Chrome (should be applied by any means necessary)</p>
 
       <p>This flag applies the night reading mode.</p>
@@ -144,12 +150,10 @@
 
       <pre><code>:--darken-filter</code></pre>
 
-      <p>Default is <code>readium-darken-on</code></p>
+      <p>Preset: <code>--USER__darkenImages: readium-darken-on</code></p>
 
       <p>Scope: <code>html</code></p>
 
-      <p>Dummy CSS variable: <code>--USER__darkenImages</code></p>
-
       <p>Override class: Chrome advanced (optional but should be applied by any means necessary if provided to users)</p>
 
       <p>This will only apply in night mode to darken images and impact <code>img</code>.</p>
@@ -158,12 +162,10 @@
 
       <pre><code>:--invert-filter</code></pre>
 
-      <p>Default is <code>readium-invert-on</code></p>
+      <p>Preset: <code>--USER__invertImages: readium-invert-on</code></p>
 
       <p>Scope: <code>html</code></p>
 
-      <p>Dummy CSS variable: <code>--USER__invertImages</code></p>
-
       <p>Override class: Chrome advanced (optional but should be applied by any means necessary if provided to users)</p>
 
       <p>This will only apply in night mode to invert images and impact <code>img</code>.</p>
@@ -172,12 +174,10 @@
 
       <pre><code>:--a11y-normalize</code></pre>
 
-      <p>Default is <code>readium-a11y-on</code></p>
+      <p>Preset: <code>--USER__a11yNormalize: readium-a11y-on</code></p>
 
       <p>Scope: <code>html</code></p>
 
-      <p>Dummy CSS variable: <code>--USER__a11yNormalize</code></p>
-
       <p>Required flag: <code>:--fontOverride</code></p>
 
       <p>Override class: User settings advanced (optional but should be applied by any means necessary if provided to users)</p>

docs/ReadiumCSS_docs/OEBPS/Text/Section-019.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">2019-11-28T14:00:00Z</meta>
+    <meta property="dcterms:modified">2020-03-09T16:47:28Z</meta>
     <meta content="0.9.5" name="Sigil version"/>
     <meta property="schema:accessibilityFeature">displayTransformability</meta>
     <meta property="schema:accessibilityFeature">readingOrder</meta>