Git commit 1f3e71eef808ced629531cdb38ac1eaf9ae10b87 by David Jarvie. Committed on 02/09/2023 at 01:50. Pushed by djarvie into branch 'master'.
Add documentation on Linux kernel timer wake from suspend function M +55 -9 doc/index.docbook https://invent.kde.org/pim/kalarm/-/commit/1f3e71eef808ced629531cdb38ac1eaf9ae10b87 diff --git a/doc/index.docbook b/doc/index.docbook index dc9e4f1fb..09f874267 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -39,8 +39,8 @@ <!-- Don't change format of date and version of the documentation --> -<date>2023-7-13</date> -<releaseinfo>3.6.0 (KDE Gear 23.08)</releaseinfo> +<date>2023-9-2</date> +<releaseinfo>3.7.0 (KDE Gear 23.12)</releaseinfo> <abstract> <para>&kalarm; is a personal alarm message, command and email scheduler by &kde;.</para> @@ -1939,6 +1939,13 @@ cancelled.</para></note> <sect2> <title>Other Controls</title> +<para>If the system configuration allows multiple alarms to wake the +system from suspension, you can select +<guilabel>Wake from suspend</guilabel> to wake the system if it is +currently suspended when the alarm becomes due. See +<link linkend="wake-suspend">Wake From Suspend</link> for more +information.</para> + <para>For display alarms, the <guilabel>Confirm acknowledgment</guilabel> check box lets you specify whether you will be prompted for confirmation when you close the alarm @@ -2490,14 +2497,41 @@ from the context menu.</para> <sect1 id="wake-suspend"> <title>Wake From Suspend</title> -<para>It is possible to configure a selected alarm to wake your -computer from hibernation or suspension when the alarm triggers, so -that the alarm action can occur even when the system was shut down. -This function is controlled by a dialog which is accessed by selecting +<para>Alarms can be configured to wake your computer from hibernation +or suspension when the alarm triggers, so that the alarm action can +occur even when the system is shut down. The mechanism used by +&kalarm; to wake the system, and the user interface to control it, +depend on the type of system and user permissions. There are two +possibilities:</para> + +<sect2> +<title>Linux Kernel Timer Wake From Suspend</title> + +<para>On Linux systems, if the user has kernel alarm timer +(<literal>cap_wake_alarm</literal>) capability, any number of alarms +can be set to wake from suspend. In this case, wake from suspend is +configured for each individual alarm in the +<link linkend="alarm-edit-dlg">Alarm Edit dialog</link> using its +<guilabel>Wake from suspend</guilabel> option.</para> + +<para>You can configure how long before the alarm to wake from suspend, +to ensure that the system has time to fully restore itself before the +alarm triggers, in the +<link linkend="preferences-time">Configuration dialog</link>.</para> + +</sect2> + +<sect2> +<title>RTC Wake From Suspend</title> + +<para>On non-Linux systems, or on Linux systems where the user does not +have <literal>cap_wake_alarm</literal> capability, the real time clock +(<acronym>RTC</acronym>) alarm is used. This can only be set for one +alarm at a time. In this case, a special Wake From Suspend dialog is +used to configure it. The dialog allows the Wake From Suspend alarm to +be set, cancelled or displayed. To access the dialog, select <menuchoice><guimenu>Actions</guimenu> -<guimenuitem>Wake From Suspend</guimenuitem></menuchoice>. The dialog -allows the Wake From Suspend alarm to be set, cancelled or -displayed.</para> +<guimenuitem>Wake From Suspend</guimenuitem></menuchoice>.</para> <para>Use of the Wake From Suspend function requires administrative privileges. You will be prompted for the root password @@ -2553,6 +2587,7 @@ that the alarm can trigger at the correct time.</para> </listitem> </itemizedlist> +</sect2> </sect1> <sect1 id="quitting"> @@ -2708,6 +2743,17 @@ country's or region's holidays to use. This affects recurring alarms for which the option to exclude holidays is selected.</para> </listitem> +<listitem><para><guilabel>Wake from suspend before alarm</guilabel>: +Enter the number of minutes before the alarm trigger time to wake the +system, for alarms set to wake from suspend. This allows you to ensure +that the system has time to fully restore itself before the alarm +triggers, so that the alarm can trigger at the correct time. This +option is only shown if the system configuration allows multiple alarms +to wake the system from suspension. See +<link linkend="wake-suspend">Wake From Suspend</link> for more +information.</para> +</listitem> + <listitem><para><guilabel>Start of day for date-only alarms</guilabel>: Set the start-of-day time for the purposes of triggering date-only alarms, &ie; ones for which the <guilabel>Any