This commit was manufactured by cvs2svn to create tag 'BALSA_2_2_2'.BALSA_2_2_2

svn path=/tags/BALSA_2_2_2/; revision=23687

1 files changed, 0 insertions, 155 deletions

diff --git a/doc/devel/calendar/alarm-generation.sgml b/doc/devel/calendar/alarm-generation.sgml
deleted file mode 100644
index 46f7e4bff1..0000000000
--- a/doc/devel/calendar/alarm-generation.sgml
+++ /dev/null
@@ -1,155 +0,0 @@
-  <chapter id="calendar-alarm-generation">
-    <title>How the Wombat generates alarm instances</title>
-
-    <para>
-      This chapter describes the algorithm that the &Wombat; uses
-      internally to generate instances of a calendar component's
-      alarms.  You do not need to read this chapter if you are simply
-      using the client-side functions.
-    </para>
-
-    <sect1 id="what-makes-up-an-alarm-trigger">
-      <title>What makes up an alarm trigger</title>
-
-      <para>
-	VTODO and VEVENT calendar components can have any number of
-	alarms defined for them.  Each alarm has a trigger
-	specification, an alarm type (display, audio, email, or
-	procedure), and data corresponding to the alarm type.  The
-	Wombat side of things is interested only in the trigger
-	specification, since this is all that the Wombat needs to
-	produce alarm instances.
-      </para>
-
-      <para>
-	An alarm trigger can be relative or absolute.  Relative
-	triggers occur a certain time before or after the start or end
-	of a calendar component's occurrence.  For example, you could
-	configure a trigger to notify you 15 minutes before an
-	appointment starts, so that you can get to its location on
-	time; or another one to notify you 5 minutes after another
-	person's meeting has ended, so that you can call that person
-	on the phone after the meeting and not disturb him while
-	there.  Absolute triggers occur at a specific point in time;
-	you can configure an alarm to trigger exactly at a particular
-	date and time that has no relation to the component's
-	occurrences at all.
-      </para>
-    </sect1>
-
-    <sect1 id="generating-trigger-instances">
-      <title>Generating trigger instances</title>
-
-      <para>
-	Generating absolute triggers is trivial; you just use the date
-	and time they specify.  However, relative triggers are
-	associated to recurrence instances, so in order to generate
-	trigger instances we must generate the corresponding
-	recurrence instances and compute the trigger times based on
-	those.
-      </para>
-
-      <para>
-	Since relative triggers are specified as occurring a certain
-	amount of time before or after each of a calendar component's
-	recurrence instances, we can compute a trigger time by adding
-	or subtracting that amount of time to the corresponding
-	recurrence instance's time.
-      </para>
-
-      <para>
-	Recurrence instances are generated by specifying a range of
-	time and asking the Wombat to generate the instances that
-	occur within that range.  We shall see that the range of time
-	in which instances occur is not necessarily the same range of
-	time in which those instances' alarm triggers occur.
-      </para>
-
-      <para>
-	Consider an alarm that is set to trigger 10 minutes before the
-	start time of an event's occurrence, that is, the trigger has
-	an offset of -10 minutes.  Say this event recurs every hour at
-	5 minutes past the hour:  it would occur at 1:05, 2:05, 3:05,
-	etc.; the corresponding triggers would occur at 12:55, 1:55,
-	2:55, etc.  If we wish to compute the alarm triggers that
-	occur between 4:00 and 6:00 (which would be at 4:55 and 5:55),
-	then we cannot just generate recurrence instances between 4:00
-	and 6:00 because we will miss the 6:05 occurrence which
-	corresponds to the 5:55 trigger.
-      </para>
-
-      <para>
-	The solution is to expand the range of time on both sides to
-	fit the relative triggers that have the largest time periods.
-	If a trigger's offset is negative, like the -10 minutes in the
-	example above, then we must expand the
-	<emphasis>end</emphasis> of the time range: in the case above,
-	the range's ending time of 6:00 must be grown by 10 minutes to
-	6:10 so that the last recurrence instance will be that of
-	6:05; computing the trigger's offset we will get the 5:55
-	trigger, which is what we wanted.  For triggers with positive
-	offsets, like if an alarm were to trigger 20 minutes after an
-	event's occurrence, we must expand the
-	<emphasis>start</emphasis> of the time range in an analogous
-	way, by subtracting the time offset from it.
-      </para>
-
-      <para>
-	Again, absolute triggers need no special computation.  We can
-	just see if the trigger time is within the requested range of
-	time, and if so, we take that trigger occurrence into account
-	for the final result.
-      </para>
-
-      <para>
-	In addition, alarms may specify a number of repetitions and a
-	duration time.  For example, an alarm may be configured to
-	repeat 3 extra times after the original occurrence with 5
-	minutes between each repetition.  Again, for absolute triggers
-	this does not present a problem, as we can just generate the
-	repetitions starting from the absolute trigger time.  For
-	relative triggers, we expand the range as described above and
-	also add the total offset for the repetitions to the start of
-	the range, i.e. 15 extra minutes for the case of 3 repetitions
-	with 5 minutes between each.  We do not need to modify the end
-	of the range because alarm repetitions always have positive
-	offsets, so they are equivalent to relative alarm triggers
-	with positive offsets.
-      </para>
-    </sect1>
-
-    <sect1 id="alarm-trigger-generation-code">
-      <title>Alarm trigger generation code</title>
-
-      <para>
-	The main function to generate alarm trigger instances is
-	<function>generate_alarms_for_comp()</function> in
-	<filename>evolution/calendar/pcs/cal-backend-file.c</filename>.
-	This function calls <function>compute_alarm_range()</function>
-	to expand the specified range of time in the way described in
-	the previous section.  It then generates the instances for
-	relative alarm triggers inside the
-	<function>add_alarm_occurrences_cb()</function> callback,
-	which is used by
-	<function>cal_recur_generate_instances()</function> with the
-	expanded range of time.  The callback goes through all of the
-	calendar component's relative alarm triggers and adds the
-	trigger offsets to the occurrence's time; the results are
-	added as <structname>CalAlarmInstance</structname> structures
-	to the final list of trigger instances.  Finally,
-	<function>generate_alarms_for_comp()</function> calls
-	<function>generate_absolute_triggers()</function>, which
-	simply adds the instances for absolute alarm triggers; these
-	are the absolute times that are within the time range that was
-	requested originally.  In the very end, the list of instances
-	is sorted to produce nicer results.
-      </para>
-    </sect1>
-  </chapter>
-
-<!--
-Local variables:
-mode: sgml
-sgml-parent-document: ("../evolution-devel-guide.sgml" "book" "part" "")
-End:
--->