From fd28bfd78e4c19d406e3f2e98d090eaf9449b2f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guido=20G=C3=BCnther?= Date: Tue, 29 Aug 2023 12:06:42 +0200 Subject: [PATCH 1/4] event: Fix doc link --- libfeedback/lfb-event.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/libfeedback/lfb-event.c b/libfeedback/lfb-event.c index 8ce3f8f..cf566dc 100644 --- a/libfeedback/lfb-event.c +++ b/libfeedback/lfb-event.c @@ -789,8 +789,8 @@ lfb_event_set_app_id (LfbEvent *self, const gchar *app_id) * @self: The event * * Returns the app-id for this event. If no app-id has been explicitly - * set, %NULL is returned. The event uses the app-id returns by - * [func@lfb_get_app_id] in this case. + * set, %NULL is returned. The event uses the app-id returned by + * [func@Lfb.get_app_id] in this case. * * Returns:(transfer none): The set app-id for this event or %NULL. */ From 65fa915184f6e62dd7096af8c89bf73b66ce2fdf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guido=20G=C3=BCnther?= Date: Tue, 29 Aug 2023 12:13:19 +0200 Subject: [PATCH 2/4] treewide: Drop superfluous '()' after functions in doc strings Otherwise we have that doubled in the docs --- libfeedback/lfb-event.c | 24 ++++++++++++------------ libfeedback/libfeedback.c | 2 +- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/libfeedback/lfb-event.c b/libfeedback/lfb-event.c index cf566dc..3fdf78a 100644 --- a/libfeedback/lfb-event.c +++ b/libfeedback/lfb-event.c @@ -23,9 +23,9 @@ * One event can trigger multiple feedbacks at once (e.g. audio and * haptic feedback). This is determined by the feedback theme in * use (which is not under the appliction's control) and the active - * feedback profile (see [func@Lfb.set_feedback_profile](). + * feedback profile (see [func@Lfb.set_feedback_profile]. * - * After initializing the library via [func@Lfb.init]() feedback can be + * After initializing the library via [func@Lfb.init] feedback can be * triggered like: * * ```c @@ -38,7 +38,7 @@ * * When all feedback for this event has ended the [signal@LfbEvent::feedback-ended] * signal is emitted. If you want to end the feedback ahead of time use - * [method@LfbEvent.end_feedback](): + * [method@LfbEvent.end_feedback]: * * ```c * if (!lfb_event_end_feedback (event, &err)) @@ -46,7 +46,7 @@ * ``` * * Since these methods involve DBus calls there are asynchronous variants - * available, e.g. [method@LfbEvent.trigger_feedback_async](): + * available, e.g. [method@LfbEvent.trigger_feedback_async]: * * ```c * static void @@ -303,7 +303,7 @@ lfb_event_class_init (LfbEventClass *klass) * * How long feedback should be provided in seconds. The special value * %-1 uses the natural length of each feedback while %0 plays each feedback - * in a loop until ended explicitly via e.g. [method@LfbEvent.end_feedback](). + * in a loop until ended explicitly via e.g. [method@LfbEvent.end_feedback]. */ props[PROP_TIMEOUT] = g_param_spec_int ( @@ -335,7 +335,7 @@ lfb_event_class_init (LfbEventClass *klass) * LfbEvent:feedback-profile: * * The name of the feedback profile to use for this event. See - * [method@LfbEvent.set_feedback_profile]() for details. + * [method@LfbEvent.set_feedback_profile] for details. */ props[PROP_FEEDBACK_PROFILE] = g_param_spec_string ( @@ -349,7 +349,7 @@ lfb_event_class_init (LfbEventClass *klass) * LfbEvent:app-id: * * The application id to use for the event. - * [method@LfbEvent.set_feedback_profile]() for details. + * [method@LfbEvent.set_feedback_profile] for details. */ props[PROP_APP_ID] = g_param_spec_string ( @@ -477,7 +477,7 @@ lfb_event_trigger_feedback (LfbEvent *self, GError **error) * * Tells the feedback server to provide proper feedback for the give * event to the user. This is the sync version of - * [method@LfbEvent.trigger_feedback](). + * [method@LfbEvent.trigger_feedback]. */ void lfb_event_trigger_feedback_async (LfbEvent *self, @@ -525,7 +525,7 @@ lfb_event_trigger_feedback_async (LfbEvent *self, * @res: Result object passed to the callback of [method@LfbEvent.trigger_feedback_async] * @error: Return location for error * - * Finish an async operation started by [method@LfbEvent.trigger_feedback_async](). You + * Finish an async operation started by [method@LfbEvent.trigger_feedback_async]. You * must call this function in the callback to free memory and receive any * errors which occurred. * @@ -571,7 +571,7 @@ lfb_event_end_feedback (LfbEvent *self, GError **error) /** * lfb_event_end_feedback_finish: * @self: the event - * @res: Result object passed to the callback of [method@LfbEvent.end_feedback_async]() + * @res: Result object passed to the callback of [method@LfbEvent.end_feedback_async] * @error: Return location for error * * Finish an async operation started by lfb_event_end_feedback_async. You @@ -637,10 +637,10 @@ lfb_event_end_feedback_async (LfbEvent *self, * Tells the feedback server to end feedack after #timeout seconds. * The value -1 indicates to not set a timeout and let feedbacks stop * on their own while 0 indicates to loop all feedbacks endlessly. - * They must be stopped via [method@LfbEvent.end_feedback]() in this case. + * They must be stopped via [method@LfbEvent.end_feedback] in this case. * * It is an error to change the timeout after the feedback has been triggered - * via [method@LfbEvent.trigger_feedback](). + * via [method@LfbEvent.trigger_feedback]. */ void lfb_event_set_timeout (LfbEvent *self, gint timeout) diff --git a/libfeedback/libfeedback.c b/libfeedback/libfeedback.c index e3b3012..b984846 100644 --- a/libfeedback/libfeedback.c +++ b/libfeedback/libfeedback.c @@ -131,7 +131,7 @@ lfb_set_app_id (const char *app_id) /** * lfb_get_app_id: * - * Get the application id set via [func@Lfb.set_app_id](). + * Get the application id set via [func@Lfb.set_app_id]. * * Returns: the application id. */ From 2ca7a329b7eb368073c2dddc875eb7d7824575be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guido=20G=C3=BCnther?= Date: Tue, 29 Aug 2023 11:33:36 +0200 Subject: [PATCH 3/4] doc: Better cross reference manpages --- doc/fbcli.rst | 2 +- doc/feedbackd.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/fbcli.rst b/doc/fbcli.rst index 4955579..1c3baaa 100644 --- a/doc/fbcli.rst +++ b/doc/fbcli.rst @@ -46,4 +46,4 @@ OPTIONS See also ======== -``feedbackd(8)`` +``feedbackd(8)`` ``fbd-theme-validate(1)`` diff --git a/doc/feedbackd.rst b/doc/feedbackd.rst index 51fffa4..cd4f4b6 100644 --- a/doc/feedbackd.rst +++ b/doc/feedbackd.rst @@ -39,4 +39,4 @@ Options See also ======== -``fbcli(1)`` +``fbcli(1)`` ``fbd-theme-validate(1)`` From 154701fee64295fb1921e74bfc8f8e5b5cb1e872 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guido=20G=C3=BCnther?= Date: Tue, 29 Aug 2023 11:53:06 +0200 Subject: [PATCH 4/4] doc: Add manpage for feedback themes This should direct users to the documentation. Prompted by https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1050762 --- doc/fbcli.rst | 2 +- doc/feedback-themes.rst | 32 ++++++++++++++++++++++++++++++++ doc/feedbackd.rst | 2 +- doc/meson.build | 1 + 4 files changed, 35 insertions(+), 2 deletions(-) create mode 100644 doc/feedback-themes.rst diff --git a/doc/fbcli.rst b/doc/fbcli.rst index 1c3baaa..314a34e 100644 --- a/doc/fbcli.rst +++ b/doc/fbcli.rst @@ -46,4 +46,4 @@ OPTIONS See also ======== -``feedbackd(8)`` ``fbd-theme-validate(1)`` +``feedbackd(8)`` ``fbd-theme-validate(1)`` ``feedback-themes(5)`` diff --git a/doc/feedback-themes.rst b/doc/feedback-themes.rst new file mode 100644 index 0000000..ef5528e --- /dev/null +++ b/doc/feedback-themes.rst @@ -0,0 +1,32 @@ +.. _feedback-themes(5): + +=============== +feedback themes +=============== + +--------------------------------- +Theme configuration for feedbackd +--------------------------------- + +DESCRIPTION +=========== + +In order to reflect device specifics and user overrides the feedback +(such as sound, haptic or led) that are being triggered by events can +be configured. This allows for device as well as user specific +configuration. Themes use a json format and can be validated by +``fbd-theme-validate``. + +For details on how to create or modify feedback themes see [feedbackd's documentation]( +https://source.puri.sm/Librem5/feedbackd#feedback-theme) + +Sound events +============ + +Sound feedbacks specify an event name from a XDG sound theme. Sound themes +are described in the [Sound theme spec](https://freedesktop.org/wiki/Specifications/sound-theme-spec/). + +See also +======== + +``feedbackd(8)`` ``fbcli(1)`` ``fbd-theme-validate(1)`` diff --git a/doc/feedbackd.rst b/doc/feedbackd.rst index cd4f4b6..ed03a27 100644 --- a/doc/feedbackd.rst +++ b/doc/feedbackd.rst @@ -39,4 +39,4 @@ Options See also ======== -``fbcli(1)`` ``fbd-theme-validate(1)`` +``fbcli(1)`` ``fbd-theme-validate(1)`` ``feedback-themes(5)`` ``feedback-themes(5)`` diff --git a/doc/meson.build b/doc/meson.build index dd16d8b..fe87fda 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -53,6 +53,7 @@ if get_option('man') ['fbcli', 1], ['fbd-theme-validate', 1], ['feedbackd', 8], + ['feedback-themes', 5], ] rst2man = find_program('rst2man', 'rst2man.py', required: false)