updates readme

README.md

@@ -1,21 +1,36 @@
 # Multibow
 
-GitHub: [github.com/thediveo/multibow](https://github.com/thediveo/multibow)
-
-Multibow turns a [Pimoroni Keybow](https://shop.pimoroni.com/products/keybow)
-into a macro keyboard with multiple layouts, switchable at any time. (Keybow is
-a solderless DIY 4x3 mechanical USB keyboard, powered by a Raspberry Pi. And
-yes, these days even keyboards run Linux...)
+Find it on GitHub:
+[thediveo/multibow](https://github.com/thediveo/multibow).
 
 ![Multibow on Keybow](multibow.jpg)
 
+Multibow adds ease-of use support for **multiple layouts** to [Pimoroni
+Keybow](https://shop.pimoroni.com/products/keybow) macro keyboards. Simply
+switch between the installed layouts by pressing a special key combination
+(defaults to press-hold key #11, then tap key #5). And you can even control the key LEDs brightness (press-hold key #11, then tap key #8 to change brightness).
+
+> "_Keybows_" are solderless DIY 4x3 mechanical USB keyboards, powered by a
+> Raspberry Pi. And yes, these days even _keyboards_ now run Linux and script
+> interpreters...
+
+And yes, this is probably a New Year's project slightly gone overboard ...
+what sane reason is there to end up with a Lua-scripted multi-layout keyboard
+"operating" system and a bunch of automated unit test cases?
+
 ## Layouts
 
+The default setup activates the following macro keyboard layouts shown below.
+
+> You can switch (cycle) between them by pressing and holding key #11
+> (top-left key in landscape), then tapping key #5 (immediately right to #11),
+> and finally releasing both keys.
+
 ### Debug Go in VisualStudio Code
 
 Debug Go programs and packages in VisualStudio Code with its Go extension.
 
-```
+```text
 ┌╌╌╌╌┐  ┌╌╌╌╌┐  ┌╌╌╌╌┐  ┌╌╌╌╌┐
 ┊ 11 ┊  ┊  8 ┊  ┊  5 ┊  ┊  2 ┊
 └╌╌╌╌┘  └╌╌╌╌┘  └╌╌╌╌┘  └╌╌╌╌┘
@@ -23,14 +38,19 @@ Debug Go programs and packages in VisualStudio Code with its Go extension.
 ╔════╗  ╔════╗  ┌╌╌╌╌┐  ╔════╗
 ║ 10 ║  ║  7 ║  ┊  4 ┊  ║  1 ║
 ╚════╝  ╚════╝  └╌╌╌╌┘  ╚════╝
-⏹STOP   ↺RELOAD         TSTPKG
+⏹STOP   ↺RELOAD         ☑TSTPKG
 ╔════╗  ╔════╗  ╔════╗  ╔════╗
 ║  9 ║  ║  6 ║  ║  3 ║  ║  0 ║
 ╚════╝  ╚════╝  ╚════╝  ╚════╝
   ▮▶    ⭢STEP   ⮧INTO   ⮥OUT
 ```
 
-* TSTPKG activates the command "go: test package".
+* ▮▶ starts, continues, or pauses the program to be debugged.
+* ⮧INTO steps _into_ a function call.
+* ⭢STEP steps _over_ a line/function call.
+* ⏹STOP stops debugging
+* ↺RELOAD reloads the program being debugged.
+* ☑TSTPKG activates the command "go: test package".
 
 ### Kdenlive Video Editor
 
@@ -44,11 +64,11 @@ A SHIFT key, with Keybow LED brightness and keyboard layout cycle control.
 > is always active, regardless of keyboard layout. The other keys in this layout
 > only become active _while_ holding SHIFT.
 
-```
+```text
 ╔════╗  ╔╌╌╌╌╗  ╔╌╌╌╌╗  ┌╌╌╌╌┐
 ║ 11 ║  ┊  8 ┊  ┊  5 ┊  ┊  2 ┊
 ╚════╝  ╚╌╌╌╌╝  ╚╌╌╌╌╝  └╌╌╌╌┘
-SHIFT   →LAYOUT  🔆BRIGHT
+⇑SHIFT  →LAYOUT 🔆BRIGHT
 ┌╌╌╌╌┐  ┌╌╌╌╌┐  ┌╌╌╌╌┐  ┌╌╌╌╌┐
 ┊ 10 ┊  ┊  7 ┊  ┊  4 ┊  ┊  1 ┊
 └╌╌╌╌┘  └╌╌╌╌┘  └╌╌╌╌┘  └╌╌╌╌┘
@@ -58,12 +78,20 @@ SHIFT   →LAYOUT  🔆BRIGHT
 └╌╌╌╌┘  └╌╌╌╌┘  └╌╌╌╌┘  └╌╌╌╌┘
 ```
 
+* press ⇑SHIFT, release ⇑SHIFT: if a keyboard layout has a SHIFT layer, then
+  this activates and deactivates this ⇑SHIFT layer.
+* press ⇑SHIFT, tap →LAYOUT, release ⇑SHIFT: switches to next keyboard layout.
+* press ⇑SHIFT, tap 🔆BRIGHT, release 🔆BRIGHT: changes the keyboard LED
+  brightness in three different brightness steps (70% → 100% → 40% → 70% →
+  ...).
+
 ### Empty
 
-Just as its name says: an empty keyboard layout -- useful if you want to have
-also "no" layout active when working with multiple keyboard layouts.
+Just as its name says: an empty keyboard layout – useful if you want to have
+also a "no" layout with no functionality whatsoever to switch to. (_This
+layout by courtesy of Margaret Thatcher._)
 
-```
+```text
 ┌╌╌╌╌┐  ┌╌╌╌╌┐  ┌╌╌╌╌┐  ┌╌╌╌╌┐
 ┊ 11 ┊  ┊  8 ┊  ┊  7 ┊  ┊  6 ┊
 └╌╌╌╌┘  └╌╌╌╌┘  └╌╌╌╌┘  └╌╌╌╌┘
@@ -88,14 +116,14 @@ keybow-firmware GitHub repository.
 ## Installation
 
 1. Download the [Pibow
-firmware](https://github.com/pimoroni/keybow-firmware/releases) and copy all
-files inside its `sdcard/` subdirectory onto an empty, FAT32 formatted microSD
-card. Copy only the files **inside** `sdcard/`, but do **not** place them into a
-~~`sdcard`~~ directory on your microSD card.
+   firmware](https://github.com/pimoroni/keybow-firmware/releases) and copy
+   all files inside its `sdcard/` subdirectory onto an empty, FAT32 formatted
+   microSD card. Copy only the files **inside** `sdcard/`, but do **not**
+   place them into a ~~`sdcard`~~ directory on your microSD card.
 
 2. Download all files from the `sdcard/` subdirectory of this repository and
-then copy them onto the microSD card. This will overwrite but one file
-`key.lua`, all other files are new.
+   then copy them onto the microSD card. This will overwrite but one file
+   `key.lua`, all other files are new.
 
 ## Multiple Keyboard Layouts
 
@@ -105,16 +133,24 @@ accordingly to require them. The default configuration is as follows:
 ```lua
 require "layouts/shift" -- for cycling between layouts.
 require "layouts/vsc-golang" -- debugging Go programs in VisualStudio Code.
+require "layouts/kdenlive" -- editing video using Kdenlive.
 require "layouts/empty" -- empty, do-nothing layout.
 ```
 
-
 ## Developing
 
-For some basic testing, run `lua test.lua` from the base directory of this
-repository. It pulls in `keybow`, then mocks some functionality of it, and
-finally starts `sdcard/keys.lua` as usual.
-
-This helps in detecting syntax and logic erros early, avoiding the
+Whether you want to dry-run your own keyboard layout or to hack Multibow: use
+the unit tests which you can find in the `spec/` subdirectory. These tests
+help you in detecting syntax and logic errors early, avoiding the
 rinse-and-repeat cycle with copying to microSD card, starting the Keybow
-hardware, and then wondering what went wrong, without any real clue.
+hardware, and then wondering what went wrong, without any real clue as to what
+is the cause of failure.
+
+Before your first testing, you'll need to run `./setup-tests.sh` once in order
+to install (on Ubuntu-based distributions) the required system distribution and
+LuaRocks packages.
+
+Afterwards, simply run `busted` while in the `multibow` repository root
+directory to run all tests. For instance, run `busted
+spec/layout/kdenlive_spec.lua` to unit test a specific keyboard layout (or set
+of layouts).