Docs: polish the README to match new additions

README.md

@@ -1,10 +1,11 @@
 # Calamares Branding and Module Examples
 
 > A *branding component* in Calamares is a description of the
-> produce (i.e. distribution) being installed along with a "slideshow"
+> product (i.e. distribution) being installed along with a "slideshow"
 > that is displayed during the installation phase of Calamares.
+> This shapes the **look** of your installation.
 >
-> A *module* adds functionality to Calamares; modules may be written
+> A *module* adds **functionality** to Calamares; modules may be written
 > in C++ or Python, using Qt Widgets or QML for the UI (with C++)
 > if there is one. Both C++ and Python allow a full control over the
 > target system during the installation.
@@ -13,11 +14,7 @@ This repository contains complete examples of branding and some
 modules for Calamares.
 
 - [Branding](#branding) documentation
-  - [default](branding/default/branding.desc) branding example
-  - [fancy](branding/fancy/branding.desc) branding example
-  - [KaOS](branding/kaos_branding/branding.desc) branding example
-  - [SameGame](branding/samegame/branding.desc) branding example
-- [Module](#module) documentation
+- [Module](#modules) documentation
 
 ## Branding
 
@@ -28,11 +25,20 @@ can be used for testing. The examples here show what can be done
 with QML in the context of Calamares branding, and provide examples
 and documentation for the framework that Calamares ships with.
 
- - `default/` is a copy of the default branding included with Calamares.
- - `fancy/` has navigation buttons and a slide counter.
- - `kaos_branding/` is a copy of the KaOS branding component, which
+ - [`default/`](branding/default/branding.desc)
+   is a copy of the default branding included with Calamares.
+ - [`fancy/`](branding/fancy/branding.desc)
+   has navigation buttons and a slide counter.
+ - [`image-slideshow/`](branding/image-slideshow/branding.desc)
+   is a variant of the *default* branding that implements its
+   own slide element for QML that supports a single image.
+   This is useful for straightforward images-only slideshows
+   (probably moreso than the default slideshow).
+ - [`kaos_branding/`](branding/kaos_branding/branding.desc)
+   is a copy of the KaOS branding component, which
    has translations and a bunch of fancy graphics.
- - `samegame/` is a copy of the Qt Company "Same Game" QML demo. It
+ - [`samegame/` ](branding/default/branding.desc)
+   is a copy of the Qt Company "Same Game" QML demo. It
    shows that **any** QML can be used for branding purposes.
 
 ### Writing your own Branding
@@ -108,8 +114,11 @@ one of two "API styles".
 
 - Version 1 is loaded when the slideshow starts. If the slideshow is
   large, or contains remote content, then this may be slow.
+  The loading time may be visible as a "white flash" as the
+  QML component is displayed with no background until the
+  slideshow is loaded.
 - Version 2 is loaded asynchronously from the moment Calamares is
-  started. This may delay startup a little, but may appear more
+  started. This may delay startup a little, but appears more
   responsive overall.
 
 If the slideshow QML defines functions
@@ -122,7 +131,18 @@ In addition, if the slideshow QML defines a property
 `activatedInCalamares` then it is set to `true`
 when the slideshow becomes visible, and to `false` when
 the installation is finished. This can also be used to
-start timers, etc.
+start timers, etc. The standard `Presentation.qml` included with
+Calamares has such a property.
+
+A slideshow (`show.qml`) can be entirely independent, with bespoke code,
+or it can make use of files shipped as part of Calamares: a *Presentation* and
+a *Slide* element (and some others). There are also Calamares internals which
+can be used from QML:
+- `import calamares.slideshow 1.0` for the standard QML slideshow (e.g. *Presentation* element;
+  use *Slide* with this or write an API-equivalent element such as the one in `image-slideshow/`).
+- `import io.calamares.ui 1.0` for a *Branding* object which has an API to
+  get colors and strings that are used elsewhere in Calamares (e.g. to make the
+  slide background the same as the background defined in `branding.desc`).
 
 
 ## Modules