|
|
@@ -10,14 +10,14 @@
|
|
|
<!-- Module User's Guide -->
|
|
|
|
|
|
<chapter>
|
|
|
-
|
|
|
+
|
|
|
<title>&adminguide;</title>
|
|
|
-
|
|
|
+
|
|
|
<section>
|
|
|
<title>Overview</title>
|
|
|
<para>
|
|
|
This module provides time recurrence matching functions. The format
|
|
|
- of recurrence definitions is based on Internet Calendaring and
|
|
|
+ of recurrence definitions is based on Internet Calendaring and
|
|
|
Scheduling Core Object Specification (Calendar COS - RFC 2445).
|
|
|
It also provides a port of the Perl Time::Period module for generic
|
|
|
time period matching.
|
|
|
@@ -116,7 +116,7 @@ modparam("tmrec", "separator", ";")
|
|
|
<itemizedlist>
|
|
|
<listitem>
|
|
|
<para>
|
|
|
- <emphasis>startdate</emphasis> - date for the start of the first
|
|
|
+ <emphasis>startdate</emphasis> - date for the start of the first
|
|
|
period.
|
|
|
</para>
|
|
|
</listitem>
|
|
|
@@ -124,9 +124,9 @@ modparam("tmrec", "separator", ";")
|
|
|
<para>
|
|
|
<emphasis>duration</emphasis> - the duration of the time period.
|
|
|
For a recurring interval, the <quote>duration</quote> parameter MUST
|
|
|
- be small enough such that subsequent intervals do not overlap.
|
|
|
- For non-recurring intervals, durations of any positive length are
|
|
|
- permitted. Zero-length duration means <quote>forever</quote>.
|
|
|
+ be small enough such that subsequent intervals do not overlap.
|
|
|
+ For non-recurring intervals, durations of any positive length are
|
|
|
+ permitted. Zero-length duration means <quote>forever</quote>.
|
|
|
Negative-length durations are not allowed.
|
|
|
</para>
|
|
|
<para>
|
|
|
@@ -138,12 +138,12 @@ modparam("tmrec", "separator", ";")
|
|
|
</listitem>
|
|
|
<listitem>
|
|
|
<para>
|
|
|
- <emphasis>frequency</emphasis> - can be one of the following values:
|
|
|
+ <emphasis>frequency</emphasis> - can be one of the following values:
|
|
|
<quote>daily</quote> -
|
|
|
specify repeating periods based on an interval of a day or more;
|
|
|
- <quote>weekly</quote> - specify repeating periods based on an
|
|
|
- interval of a week or more; <quote>monthly</quote> - specify
|
|
|
- repeating periods based on an interval of a month or more;
|
|
|
+ <quote>weekly</quote> - specify repeating periods based on an
|
|
|
+ interval of a week or more; <quote>monthly</quote> - specify
|
|
|
+ repeating periods based on an interval of a month or more;
|
|
|
<quote>yearly</quote> - specify repeating periods based
|
|
|
on an interval of a year or more. These values are case-insensitive.
|
|
|
</para>
|
|
|
@@ -152,15 +152,15 @@ modparam("tmrec", "separator", ";")
|
|
|
<para>
|
|
|
<emphasis>until</emphasis> - defines an iCalendar COS DATE or DATE-TIME
|
|
|
value which bounds the recurrence rule in an inclusive manner. If the
|
|
|
- value specified by <quote>until</quote> is synchronized with the
|
|
|
- specified recurrence, this date or date-time becomes the last instance
|
|
|
- of the recurrence. If it is not present, the recurrence is considered
|
|
|
+ value specified by <quote>until</quote> is synchronized with the
|
|
|
+ specified recurrence, this date or date-time becomes the last instance
|
|
|
+ of the recurrence. If it is not present, the recurrence is considered
|
|
|
to repeat forever.
|
|
|
</para>
|
|
|
</listitem>
|
|
|
<listitem>
|
|
|
<para>
|
|
|
- <emphasis>interval</emphasis> - a positive integer
|
|
|
+ <emphasis>interval</emphasis> - a positive integer
|
|
|
representing how often the recurrence rule repeats. The default value
|
|
|
is <quote>1</quote>, meaning every day for a <quote>daily</quote> rule,
|
|
|
every week for a <quote>weekly</quote>
|
|
|
@@ -170,45 +170,45 @@ modparam("tmrec", "separator", ";")
|
|
|
</listitem>
|
|
|
<listitem>
|
|
|
<para>
|
|
|
- <emphasis>byday</emphasis> - a comma-separated list short codes of days
|
|
|
+ <emphasis>byday</emphasis> - a comma-separated list short codes of days
|
|
|
of the week. The days are specified as: <quote>MO</quote> for Monday;
|
|
|
- <quote>TU</quote> for Tuesday; <quote>WE</quote> for Wednesday;
|
|
|
- <quote>TH</quote> for Thursday; <quote>FR</quote> for
|
|
|
- Friday; <quote>SA</quote> for Saturday; <quote>SU</quote>
|
|
|
+ <quote>TU</quote> for Tuesday; <quote>WE</quote> for Wednesday;
|
|
|
+ <quote>TH</quote> for Thursday; <quote>FR</quote> for
|
|
|
+ Friday; <quote>SA</quote> for Saturday; <quote>SU</quote>
|
|
|
for Sunday. These values are case insensitive.
|
|
|
</para>
|
|
|
<para>
|
|
|
- Each <quote>byday</quote> value can also be prefixed by a positive
|
|
|
- (+n) or negative (-n) integer. If present, this indicates the n-th
|
|
|
- occurrence of the specific day within the <quote>monthly</quote> or
|
|
|
- <quote>yearly</quote> recurrence. For example, within a
|
|
|
- <quote>monthly</quote> rule, +1MO (or simply 1MO) represents the first
|
|
|
+ Each <quote>byday</quote> value can also be prefixed by a positive
|
|
|
+ (+n) or negative (-n) integer. If present, this indicates the n-th
|
|
|
+ occurrence of the specific day within the <quote>monthly</quote> or
|
|
|
+ <quote>yearly</quote> recurrence. For example, within a
|
|
|
+ <quote>monthly</quote> rule, +1MO (or simply 1MO) represents the first
|
|
|
Monday within the month, whereas -1MO represents the last Monday of
|
|
|
the month. If an integer modifier is not present, it means all days
|
|
|
- of this type within the specified frequency. For example, within a
|
|
|
+ of this type within the specified frequency. For example, within a
|
|
|
<quote>monthly</quote> rule, MO represents all Mondays within the month.
|
|
|
</para>
|
|
|
</listitem>
|
|
|
<listitem>
|
|
|
<para>
|
|
|
<emphasis>bymonthday</emphasis> - a comma-separated
|
|
|
- list of days of the month. Valid values are 1 to 31 or -31 to -1. For
|
|
|
+ list of days of the month. Valid values are 1 to 31 or -31 to -1. For
|
|
|
example, -10 represents the tenth to the last day of the month.
|
|
|
</para>
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
<para>
|
|
|
- <emphasis>byyearday</emphasis> - a comma-separated list of
|
|
|
+ <emphasis>byyearday</emphasis> - a comma-separated list of
|
|
|
days of the year. Valid values are 1 to 366 or -366 to -1. For example,
|
|
|
- -1 represents the last day of the year (December 31st) and -306
|
|
|
+ -1 represents the last day of the year (December 31st) and -306
|
|
|
represents the 306th day before the last day of the year (March 1st).
|
|
|
</para>
|
|
|
</listitem>
|
|
|
<listitem>
|
|
|
<para>
|
|
|
- <emphasis>byweekno</emphasis> - a comma-separated list of
|
|
|
- ordinals specifying weeks of the year. Valid values are 1 to 53 or
|
|
|
+ <emphasis>byweekno</emphasis> - a comma-separated list of
|
|
|
+ ordinals specifying weeks of the year. Valid values are 1 to 53 or
|
|
|
-53 to -1.
|
|
|
</para>
|
|
|
</listitem>
|
|
|
@@ -219,39 +219,39 @@ modparam("tmrec", "separator", ";")
|
|
|
</para>
|
|
|
</listitem>
|
|
|
</itemizedlist>
|
|
|
-
|
|
|
+
|
|
|
<para>
|
|
|
- A recurrence is specified by including the <quote>frequency</quote>
|
|
|
- parameter, which indicates the type of the recurrence rule. Parameters
|
|
|
+ A recurrence is specified by including the <quote>frequency</quote>
|
|
|
+ parameter, which indicates the type of the recurrence rule. Parameters
|
|
|
other than <quote>startdate</quote>
|
|
|
- and <quote>duration</quote> SHOULD NOT be specified unless
|
|
|
+ and <quote>duration</quote> SHOULD NOT be specified unless
|
|
|
<quote>frequency</quote> is set.
|
|
|
</para>
|
|
|
<para>
|
|
|
- If invalid byxxx parameter values are found (ie, bymonthday=<quote>30</quote> in February),
|
|
|
- they are simply ignored.
|
|
|
+ If invalid byxxx parameter values are found (ie, bymonthday=<quote>30</quote> in February),
|
|
|
+ they are simply ignored.
|
|
|
</para>
|
|
|
<para>
|
|
|
Byxxx parameters modify the recurrence rule matching. The Byxxx rule, as
|
|
|
- an attribute for a period of time which is greater than or equal to the
|
|
|
- frequency, generally reduces or limits the number of occurrences for the
|
|
|
- recurrence definition. For example, frequency=<quote>daily</quote>
|
|
|
+ an attribute for a period of time which is greater than or equal to the
|
|
|
+ frequency, generally reduces or limits the number of occurrences for the
|
|
|
+ recurrence definition. For example, frequency=<quote>daily</quote>
|
|
|
bymonth=<quote>3</quote> reduces the number of
|
|
|
- recurrence instances from all days (if the <quote>bymonth</quote>
|
|
|
- parameter is not present) to all days in March. Byxxx parameters for
|
|
|
- a period of time less than the frequency generally increases or expands
|
|
|
- the number of occurrences of the recurrence. For example,
|
|
|
+ recurrence instances from all days (if the <quote>bymonth</quote>
|
|
|
+ parameter is not present) to all days in March. Byxxx parameters for
|
|
|
+ a period of time less than the frequency generally increases or expands
|
|
|
+ the number of occurrences of the recurrence. For example,
|
|
|
frequency=<quote>yearly</quote> bymonth=<quote>8,9</quote>
|
|
|
- increases the number of days within the yearly recurrence set from 1
|
|
|
+ increases the number of days within the yearly recurrence set from 1
|
|
|
(if <quote>bymonth</quote> parameter is not present) to 2.
|
|
|
</para>
|
|
|
<para>
|
|
|
If multiple Byxxx parameters are specified, then after evaluating the
|
|
|
specified <quote>frequency</quote> and <quote>interval</quote> parameters,
|
|
|
- the Byxxx parameters are
|
|
|
+ the Byxxx parameters are
|
|
|
applied to the current set of evaluated occurrences in the following
|
|
|
- order: <quote>bymonth</quote>, <quote>byweekno</quote>,
|
|
|
- <quote>byyearday</quote>, <quote>bymonthday</quote>,
|
|
|
+ order: <quote>bymonth</quote>, <quote>byweekno</quote>,
|
|
|
+ <quote>byyearday</quote>, <quote>bymonthday</quote>,
|
|
|
<quote>byday</quote>; then <quote>until</quote> is evaluated.
|
|
|
</para>
|
|
|
<para>
|
|
|
@@ -259,15 +259,15 @@ modparam("tmrec", "separator", ";")
|
|
|
</para>
|
|
|
<para>
|
|
|
startdate=<quote>20100101T093000</quote> duration=<quote>PT10H30M</quote>
|
|
|
- frequency=<quote>yearly</quote> interval=<quote>4</quote>
|
|
|
+ frequency=<quote>yearly</quote> interval=<quote>4</quote>
|
|
|
bymonth=<quote>3</quote> byday=<quote>SU</quote>
|
|
|
</para>
|
|
|
<para>
|
|
|
- First, the interval=<quote>4</quote> would be applied to
|
|
|
+ First, the interval=<quote>4</quote> would be applied to
|
|
|
frequency=<quote>yearly</quote> to match on <quote>every 4th year</quote>
|
|
|
- . Then, bymonth=<quote>1</quote> would be applied to match on
|
|
|
+ . Then, bymonth=<quote>1</quote> would be applied to match on
|
|
|
<quote>every March, every 4th year</quote>. Then,
|
|
|
- byday=<quote>SU</quote> would be applied to match on <quote>every
|
|
|
+ byday=<quote>SU</quote> would be applied to match on <quote>every
|
|
|
Sunday in March, every 4th year, from 9:30 to 20:00 </quote>. The start
|
|
|
and end hours:minutes have been retrieved from the
|
|
|
<quote>startdate</quote> and <quote>duration</quote> parameters.
|
Daniel-Constantin Mierla