Branding: shuffle around a bit, expand documentation

src/branding/default/branding.desc

@@ -7,6 +7,12 @@
 ---
 componentName:  default
 
+
+### WELCOME / OVERALL WORDING
+#
+# These settings affect some overall phrasing and looks,
+# which are most visible in the welcome page.
+
 # This selects between different welcome texts. When false, uses
 # the traditional "Welcome to the %1 installer.", and when true,
 # uses "Welcome to the Calamares installer for %1." This allows
@@ -20,6 +26,12 @@ welcomeStyleCalamares:   false
 # may have surprising effects on HiDPI monitors).
 welcomeExpandingLogo:   true
 
+### WINDOW CONFIGURATION
+#
+# The settings here affect the placement of the Calamares
+# window through hints to the window manager and initial
+# sizing of the Calamares window.
+
 # Size and expansion policy for Calamares.
 #  - "normal" or unset, expand as needed, use *windowSize*
 #  - "fullscreen", start as large as possible, ignore *windowSize*
@@ -41,6 +53,14 @@ windowSize: 800px,520px
 # *windowExpanding* set to "fullscreen").
 windowPlacement: center
 
+### PANELS CONFIGURATION
+#
+# Calamares has a main content area, and two panels (navigation
+# and progress / sidebar). The panels can be controlled individually,
+# or switched off. If both panels are switched off, the layout of
+# the main content area loses its margins, on the assumption that
+# you're doing something special.
+
 # Kind of sidebar (panel on the left, showing progress).
 #  - "widget" or unset, use traditional sidebar (logo, items)
 #  - "none", hide it entirely
@@ -66,6 +86,12 @@ sidebar: widget
 # except the default is *bottom*.
 navigation: widget
 
+
+### STRINGS, IMAGES AND COLORS
+#
+# This section contains the "branding proper" of names
+# and images, rather than global-look settings.
+
 # These are strings shown to the user in the user interface.
 # There is no provision for translating them -- since they
 # are names, the string is included as-is.
@@ -139,9 +165,28 @@ images:
     # productWallpaper:    "wallpaper.png"
     productWelcome:      "languages.png"
 
+# Colors for text and background components.
+#
+#  - sidebarBackground is the background of the sidebar
+#  - sidebarText is the (foreground) text color
+#  - sidebarTextHighlight sets the background of the selected (current) step.
+#    Optional, and defaults to the application palette.
+#  - sidebarSelect is the text color of the selected step.
+#
+# These colors can **also** be set through the stylesheet, if the
+# branding component also ships a stylesheet.qss. Then they are
+# the corresponding CSS attributes of #sidebarApp.
+style:
+   sidebarBackground:    "#292F34"
+   sidebarText:          "#FFFFFF"
+   sidebarTextSelect:    "#292F34"
+   sidebarTextHighlight: "#D35400"
+
+### SLIDESHOW
+#
 # The slideshow is displayed during execution steps (e.g. when the
 # installer is actually writing to disk and doing other slow things).
-#
+
 # The slideshow can be a QML file (recommended) which can display
 # arbitrary things -- text, images, animations, or even play a game --
 # during the execution step. The QML **is** abruptly stopped when the
@@ -171,19 +216,3 @@ slideshow:               "show.qml"
 slideshowAPI: 2
 
 
-# Colors for text and background components.
-#
-#  - sidebarBackground is the background of the sidebar
-#  - sidebarText is the (foreground) text color
-#  - sidebarTextHighlight sets the background of the selected (current) step.
-#    Optional, and defaults to the application palette.
-#  - sidebarSelect is the text color of the selected step.
-#
-# These colors can **also** be set through the stylesheet, if the
-# branding component also ships a stylesheet.qss. Then they are
-# the corresponding CSS attributes of #sidebarApp.
-style:
-   sidebarBackground:    "#292F34"
-   sidebarText:          "#FFFFFF"
-   sidebarTextSelect:    "#292F34"
-   sidebarTextHighlight: "#D35400"