Merge branch 'theme-doc' into 'main'

doc: Document `$device` in device themes

See merge request agx/feedbackd!206

README.md

@@ -1,12 +1,17 @@
 # Theme based Haptic, Visual and Audio Feedback
 
-feedbackd provides a DBus daemon (feedbackd) to act on events to provide
+feebackd provides a DBus daemon (feebackd) to act on events to provide
-haptic, visual and audio feedback. It offers a library (libfeedback) and
+haptic, visual and audio feedback. It offers a library
-GObject introspection bindings to ease using it from applications.
+([libfeedback][libfeedback-api]) and GObject introspection bindings to
+ease using it from applications.
+
+It provides a reference implementation for the [Feedback theme
+specification][theme-spec] and [Event naming
+specification][event-spec].
 
 ## License
 
-feedbackd is licensed under the GPLv3+ while the libfeedback library is
+feebackd is licensed under the GPLv3+ while the libfeedback library is
 licensed under LGPL 2.1+.
 
 ## Getting the source
@@ -34,7 +39,7 @@ For an explicit list of dependencies check the `Build-Depends` entry in the
 
 ## Building
 
-We use the meson (and thereby Ninja) build system for feedbackd.  The quickest
+We use the meson (and thereby Ninja) build system for feebackd.  The quickest
 way to get going is to do the following:
 
 ```sh
@@ -70,7 +75,7 @@ To run under `gdb` use
 FBD_GDB=1 _build/run _build/src/feedbackd
 ```
 
-You can introspect and get the current profile with
+You can introspect and get the current maximum profile with
 
 ```sh
 gdbus introspect --session --dest org.sigxcpu.Feedback --object-path /org/sigxcpu/Feedback
@@ -80,29 +85,58 @@ To run feedback for an event, use [fbcli](#fbcli)
 
 See `examples/` for a simple python example using GObject introspection.
 
-## How it works
+## Events, Feedbacks and Profiles
 
-Whenever an event is submitted to the daemon by a client via the DBus API *feedbackd*
+Whenever an event is submitted to the daemon by a client via the DBus
-looks up the corresponding feedbacks according to the current profile in the currently
+API *feebackd* looks up the corresponding feedbacks in the profiles
-active feedback theme (taking per application profile settings into account).
+of the currently active feedback theme. Which feedbacks are actually
+triggered depends on the daemon's current *feedback* *level*, per
+application settings and hints provided by the client with the event.
+A feedback can be a sound played, a vibra rumble or a LED blinking
+with a given pattern.
 
-Any feedback triggered by a client via an event will be stopped latest when the
+Any feedback triggered by a client via an event will be stopped latest
-client disconnects from DBus. This makes sure all feedbacks get canceled if the
+when the client disconnects from DBus. This makes sure all feedbacks
-app that triggered them crashes.
+get canceled if the app that triggered them crashes.
 
-### Feedback theme
+### Profiles
+
+Each theme consists of up to three profile sections named `full`,
+`quiet` and `silent` containing event names and their associated
+feedback. feebackd's currently selected profile determines which
+profiles of the current theme are being used for event lookup:
+
+- `full`: Use events from the `full`, `quiet` and `silent` profiles of
+  the current feedback theme.
+- `quiet`: Use events from the `quiet` and `silent` profiles of the
+  current feedback theme. This usually means haptic and LED but no
+  sound feedback.
+- `silent`: Only use the `silent` profile from the current feedback
+  theme. This usually means LED but no sound or vibra feedback.
+
+The daemon's current profile can be changed via a GSetting:
+
+```sh
+gsettings set org.sigxcpu.feedbackd profile full
+```
+
+As the daemon's current profile value sets an upper limit of the used
+profiles of a theme it is called the *feedback* *level*. See the
+[Theme spec][theme-spec] for further details.
+
+### Feedback themes
 
 As devices have varying capabilities and users different needs, events
 are mapped to feedbacks (sound, LED, vibra) via a configurable theme.
 
 There are two types of themes: *custom* themes and *device* themes.
 They both use the same format but have different purpose. Custom
-themes are meant to tweak feedbackd's output to the users needs while
+themes are meant to tweak feebackd's output to the users needs while
 device themes are meant to cater for hardware differences.
 
 #### Custom themes
 
-Feedbackd is shipped with a default theme `default.json`. You can
+feebackd is shipped with a default theme `default.json`. You can
 replace this by your own, custom theme in multiple ways:
 
 1. By exporting an environment variable `FEEDBACK_THEME` with a path to a
@@ -113,7 +147,7 @@ replace this by your own, custom theme in multiple ways:
    default to `$HOME/.config`
 
 1. By creating a theme file under `$XDG_CONFIG_HOME/feedbackd/themes/custom.json` and
-   telling feedbackd to use that theme. In this custom theme you only
+   telling feebackd to use that theme. In this custom theme you only
    specify the events you want to change. Also add a `parent-name` entry
    to chain up to the default theme:
 
@@ -133,7 +167,7 @@ replace this by your own, custom theme in multiple ways:
    [here](./tests/data/user-config/feedbackd/themes/custom.json) for
    an example.
 
-   Once you have the file in place, tell feedbackd to use this theme
+   Once you have the file in place, tell feebackd to use this theme
    instead of the default one:
 
    ```sh
@@ -159,7 +193,7 @@ be used to avoid having to restart the daemon in case of configuration changes.
 
 ### Device themes
 
-Feedbackd has support to pick up device specific themes
+feebackd has support to pick up device specific themes
 automatically. This allows us to handle device differences like
 varying strength of haptic motors or different LED colors in an
 automatic way.
@@ -178,7 +212,16 @@ the current list of device-specific themes we ship by default.
 Device specific themes have the same format as custom themes. They
 also use the `parent-name` property to chain up to the default theme
 and only override the events that need adjustment. However the rules
-for finding the device theme in the file system differ.
+for finding the device theme in the file system differ and device
+themes always have the `name` property set to `$device`. The simplest
+device theme, doing nothing looks like:
+
+```json
+{
+  "name" : "$device",
+  "parent-name": "default"
+}
+```
 
 If multiple device theme files exist, the selection logic follows
 these steps:
@@ -201,7 +244,7 @@ $ echo $XDG_DATA_DIRS
 /usr/local/share/:/usr/share/
 ```
 
-The selection logic would follow these steps:
+The above selection logic would look at these concrete locations:
 
 - `/usr/local/share/feedbackd/themes/pine64,pinephone-1.2.json` takes
   precedence over `/usr/local/share/feedbackd/themes/pine64-pinephone.json`
@@ -209,7 +252,7 @@ The selection logic would follow these steps:
   over `/usr/share/feedbackd/themes/pine64-pinephone-1.2.json`
 - etc...
 
-if you create or adjust a device theme and consider the changes
+If you create or adjust a device theme and consider the changes
 generally useful, please submit them as merge request in the
 [feedbackd-device-themes][1] repository.
 
@@ -218,26 +261,10 @@ generally useful, please submit them as merge request in the
 Note that the feedback theme API, including the theme file format, is
 not stable but considered internal to the daemon.
 
-### Profiles
-
-The profile determines which parts of the theme are in use:
-
-- `full`: Use configured events from the `full`, `quiet` and `silent` parts of
-  the feedback them.
-- `quiet`: Use `quiet` and `silent` part from of the feedback theme. This usually
-  means no audio feedback.
-- `silent`: Only use the `silent` part from the feedback theme. This usually means
-  to not use audio or vibra.
-
-It can be set via a GSetting
-
-```sh
-  gsettings set org.sigxcpu.feedbackd profile full
-```
-
 ## fbcli
 
-`fbcli` can be used to trigger feedback for different events. Here are some examples:
+`fbcli` is a command line tool that can be used to trigger feedback
+for different events. Here are some examples:
 
 ### Phone call
 
@@ -319,20 +346,20 @@ a haptic device is found.
 ## Getting in Touch
 
 - Issue tracker: <https://gitlab.freedesktop.org/agx/feedbackd/-/issues>
-- Matrix: <https://matrix.to/#/#phosh:phosh.mobi>
+- Chat via Matrix: <https://matrix.to/#/#phosh:phosh.mobi>
 
 ## Code of Conduct
 
-Note that as a project hosted on freedesktop.org, feedbackd follows its
+Note that since feedbackd is hosted on freedesktop.org, feebackd follows its
 [Code of Conduct], based on the Contributor Covenant. Please conduct yourself
 in a respectful and civilized manner when communicating with community members
 on IRC and bug tracker.
 
 ## Documentation
 
-- [Libfeedback API](https://feedbackd-b29738.pages.freedesktop.org/)
+- [Libfeedback API][libfeedback-api]
-- [Event naming spec draft](./doc/Event-naming-spec-0.0.0.md)
+- [Event naming spec draft][event-spec]
-- [Feedback-theme-spec draft](./doc/Feedback-theme-spec-0.0.0.md)
+- [Feedback-theme-spec draft][theme-spec]
 - [W3's vibration API draft](https://www.w3.org/TR/vibration/)
 
 [debian/control]: ./debian/control#L5
@@ -340,3 +367,6 @@ on IRC and bug tracker.
 [feedback-themes]: ./doc/feedback-themes.rst
 [Code of Conduct]: https://www.freedesktop.org/wiki/CodeOfConduct/
 [feedbackd-themes manpage]: ./doc/feedbackd-themes.rst
+[event-spec]: ./doc/Event-naming-spec-0.0.0.md
+[theme-spec]: ./doc/Feedback-theme-spec-0.0.0.md
+[libfeedback-api]: https://feedbackd-b29738.pages.freedesktop.org/

doc/feedback-themes.rst

@@ -12,17 +12,19 @@ DESCRIPTION
 -----------
 
 The feedback provided to the user for an event is determined by the
-feedback theme. Each theme consists of up to three profiles (`full`,
+currently active feedback theme.
-`quiet` and `silent`) containing event names and their associated
-feedback.
 
-Events in the theme are named according to the
+Each theme consists of up to three profile sections named `full`,
+`quiet` and `silent` containing event names and their associated
+feedback. They can reference another theme via the `parent-name`
+element to avoid repetition.
+
+The events in the theme are named according to the
 `Event Naming Specifiaction
 <https://gitlab.freedesktop.org/agx/feedbackd/-/blob/main/doc/Event-naming-spec-0.0.0.md>`_
 
 Feedback themes use a JSON format that can be validated with
-``fbd-theme-validate(1)``. They can include other themes to avoid
+``fbd-theme-validate(1)``.
-repetition.
 
 For details on how to create or modify feedback themes see
 ``feedbackd's documentation`` at https://gitlab.freedesktop.org/agx/feedbackd#feedback-theme
@@ -47,6 +49,8 @@ are described in the ``Sound theme spec`` at https://freedesktop.org/wiki/Specif
 - `event-name`: The sound event name to use.
 - `media-role`: The media role to set played audio stream. Defaults to `event`.
 
+`Sound` feedback is usually used in the `full` profile section of the the theme only.
+
 VibraRumble feedback
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -57,6 +61,8 @@ The `VibraRumble` feedback uses a single property
 - `duration`: The duration of the rumble in ms.
 - `mangitude`: The relative magnitude of the rumble (``[0, 1]``).
 
+`VibraRumble` feedback is usually used in the `quiet` profile section of the the theme only.
+
 VibraPattern feedback
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -65,9 +71,10 @@ The `VibraPattern` feedback has these properties
 - `magnitudes`: The relative magnitude of each rumble ``[0, 1]`` as array of doubles.
 - `durations`: The durations of each rumble in ms as array of unsigned integers.
 
-Both arrays must have the same length.
+Both arrays must have the same length. `VibraPattern` feedback is
+usually used in the `quiet` profile section of the the theme only.
 
-LED feedback
+Led feedback
 ~~~~~~~~~~~~
 
 The `Led` feedback type uses two properties to specify the way a LED blinks.
@@ -78,6 +85,8 @@ The `Led` feedback type uses two properties to specify the way a LED blinks.
   each component. E.g. `#00FFFF` corresponds to cyan color.
 - `frequency`: The LEDs blinkinig frequency in mHz.
 
+`Led` feedback is usually used in the `silent` profile section of the the theme only.
+
 See also
 ========