Clarify API doc + switch to empty string for removing User Settings flags

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/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)