doc: Clarify theme use

Signed-off-by: Guido Günther <agx@sigxcpu.org>

README.md

@@ -70,11 +70,9 @@ See `examples/` for a simple python example using GObject introspection.
 
 ## How it works
 
-We're using a [event naming spec](./doc/Event-naming-spec-0.0.0.md)
-similar to <http://0pointer.de/public/sound-naming-spec.html> to name
-events. This will allow us to act as a system sound library so
-applications only need to call into this library and things like
-the quiet and silent profile work out of the box.
+Whenever an event is submitted to the daemon by a client via the DBus API *feedbackd*
+looks up the corresponding feedbacks according to the current profile in the currently
+active feedback theme (taking per application profile settings into account).
 
 Any feedback triggered by a client via an event will be stopped latest when the
 client disconnects from DBus. This makes sure all feedbacks get canceled if the
@@ -82,9 +80,9 @@ app that triggered it crashes.
 
 ### Feedback theme
 
-Events are then mapped to a specific type of feedback (sound, led, vibra) via a
-device specific theme - since devices have different capabilities and
-different users different needs.
+As devices have varying capabilities and users different needs, events
+are mapped to a feedbacks (sound, LED, vibra) via a configurable
+theme.
 
 Feedbackd is shipped with a default theme `default.json`.
 You can add your own themes in multiple ways:

doc/feedback-themes.rst

@@ -11,10 +11,18 @@ Theme configuration for feedbackd
 DESCRIPTION
 -----------
 
-In order to reflect device specifics and user overrides the feedback
-(such as sound, haptic or led) that is being triggered by an event can
-be configured and overridden by so called themes. Feedback themes use a JSON
-format that can be validated with ``fbd-theme-validate``.
+The feedback provided to the user for an event is determined by the
+feedback theme. Each theme consists of up to three profiles (`full`,
+`quiet` and `silent`) containing event names and their associated
+feedback.
+
+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
+repetition.
 
 For details on how to create or modify feedback themes see
 ``feedbackd's documentation`` at https://gitlab.freedesktop.org/agx/feedbackd#feedback-theme

doc/feedbackd.rst

@@ -21,14 +21,14 @@ event feedback such as playing a sound, trigger a haptic motor or blink
 a LED.
 
 The feedback triggered by a given event is determined by the feedback theme in
-use. Events are submitted via a DBus API.
+use (see `feedback-themes(5)`). Events are submitted via a DBus API.
 
 Any feedback triggered by a client via an event will be stopped latest when the
 client disconnects from DBus. This makes sure all feedbacks get canceled if the
 app that triggered it crashes.
 
 For details refer to the event and feedback theme specs at
-`<https://gitlab.freedesktop.org/agx/feedbackd/>`__
+`<https://gitlab.freedesktop.org/agx/feedbackd/>`__.
 
 Feedbackd reloads the feedback theme on `SIGHUP` (i.e. `pkill -HUP feedbackd`).
 
@@ -49,7 +49,8 @@ These gsettings are used by ``feedbackd``:
 
 - `org.sigxcpu.feedbackd`
 
-    - `profile`: The current overall feedback profile
+    - `profile`: The current overall feedback profile. Valid  values are
+      `full`, `quiet` and `silent`.
     - `allow-important`: List of apps that can override the feedback level
       (useful for e.g. allowing the alarm clock to also emit sound when
       device is in silent mode).
@@ -61,7 +62,8 @@ These gsettings are used by ``feedbackd``:
 
 - `org.sigxcpu.feedbackd.application`
 
-   - `profile`: Per application profile levels
+   - `profile`: Per application profile levels. Valid  values are
+      `full`, `quiet` and `silent`.
 
 See also
 ========