From 2fa6361d63f644c6161e30f9d8d80be4d133a128 Mon Sep 17 00:00:00 2001
From: Adriaan de Groot <groot@kde.org>
Date: Mon, 19 Feb 2018 05:10:17 -0500
Subject: [PATCH] [branding] Expand documentation

 - Make CMakeLists a little more resilient
 - Format docs source
 - Add documentation for the examples
---
 src/branding/CMakeLists.txt |  3 ++-
 src/branding/README.md      | 33 +++++++++++++++++++++++++++++----
 2 files changed, 31 insertions(+), 5 deletions(-)

diff --git a/src/branding/CMakeLists.txt b/src/branding/CMakeLists.txt
index ed25828bb..b03127e39 100644
--- a/src/branding/CMakeLists.txt
+++ b/src/branding/CMakeLists.txt
@@ -1,6 +1,7 @@
 file( GLOB SUBDIRECTORIES RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} "*" )
 foreach( SUBDIRECTORY ${SUBDIRECTORIES} )
-    if( IS_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/${SUBDIRECTORY}" )
+    set( _sd "${CMAKE_CURRENT_SOURCE_DIR}/${SUBDIRECTORY}" )
+    if( IS_DIRECTORY "${_sd}" AND EXISTS "${_sd}/branding.desc" )
         calamares_add_branding_subdirectory( ${SUBDIRECTORY} )
     endif()
 endforeach()
diff --git a/src/branding/README.md b/src/branding/README.md
index 7f37b9230..bfdcdebba 100644
--- a/src/branding/README.md
+++ b/src/branding/README.md
@@ -1,9 +1,34 @@
 # Branding directory
 
-Branding components can go here, or they can be managed and installed separately.
+Branding components can go here, or they can be installed separately.
 
-A branding component is a subdirectory with a branding.desc descriptor file, containing brand-specific strings in a key-value structure, plus brand-specific images or QML. Such a subdirectory, when placed here, is automatically picked up by CMake and made available to Calamares.
+A branding component is a subdirectory with a `branding.desc` descriptor
+file, containing brand-specific strings in a key-value structure, plus
+brand-specific images or QML. Such a subdirectory, when placed here, is
+automatically picked up by CMake and made available to Calamares.
 
-QML files in a branding component can be translated. Translations should be placed in a subdirectory `lang` of the branding component directory. Qt translation files are supported (`.ts` sources which get compiled into `.qm`). Inside the `lang` subdirectory all translation files must be named according to the scheme `calamares-<component name>_<language>.qm`.
+QML files in a branding component can be translated. Translations should
+be placed in a subdirectory `lang/` of the branding component directory.
+Qt translation files are supported (`.ts` sources which get compiled into
+`.qm`). Inside the `lang` subdirectory all translation files must be named
+according to the scheme `calamares-<component name>_<language>.qm`.
 
-Text in your show.qml should be enclosed in this form for translations `text: qsTr("This is an example text.")`
+Text in your `show.qml` (or whatever *slideshow* is set to in the descriptor
+file) should be enclosed in this form for translations
+
+```
+    text: qsTr("This is an example text.")
+```
+
+## Examples
+
+There are two examples of branding content:
+
+ - `default/` is a sample brand for the Generic Linux distribution. It uses
+   the default Calamares icons and a as start-page splash it provides a
+   tag-cloud view of languages. The slideshow is a basic one with a few
+   slides of text and a single image. No translations are provided.
+ - `samegame/` is a similarly simple branding setup for Generic Linux,
+   but instead of a slideshow, it lets the user play Same Game (clicking
+   colored balls) during the installation. The game is taken from the
+   QML examples provided by the Qt Company.