1.1 --- a/pages/HelpOnEventAggregator Tue Mar 30 20:12:51 2010 +0200
1.2 +++ b/pages/HelpOnEventAggregator Sat Apr 10 22:15:18 2010 +0200
1.3 @@ -35,6 +35,40 @@
1.4
1.5 Obviously, duplicating the date information introduces a risk of this information becoming inconsistent, so beware!
1.6
1.7 +=== Adding Time Information ===
1.8 +
1.9 +In addition to date information, !EventAggregator understands time information; this is specified using the `HH:MM:SS` format (`HH` for hour digits in a 24-hour clock scheme, `MM` for minutes, and `SS` for seconds). The hour and minute details are mandatory; the seconds are optional. For example:
1.10 +
1.11 +{{{
1.12 + Start:: 2009-06-30 10:30
1.13 + End:: 2009-06-30 11:00
1.14 +}}}
1.15 +
1.16 +With no additional information, this indicates a time period from 10:30 (10:30am) until 11:00 (11am) without specifying a time zone. Consequently, such a period could be interpreted as applying ''in any location'' or ''in an agreed but unspecified location''. Where such things could lead to confusion, such as in the planning of an Internet meeting where people may join the meeting from many different places, time zone information can be specified. For example:
1.17 +
1.18 +{{{
1.19 + Start:: 2009-06-30 10:30 UTC+0100
1.20 + End:: 2009-06-30 11:00 UTC+0100
1.21 +}}}
1.22 +
1.23 +This indicates that the time is defined in a zone one hour ahead of UTC, thus defining a UTC period of 09:30 (9:30am) until 10:00 (10am). It is also possible to drop `UTC` and the last two minute digits where appropriate:
1.24 +
1.25 +{{{
1.26 + Start:: 2009-06-30 10:30 +01
1.27 + End:: 2009-06-30 11:00 +01
1.28 +}}}
1.29 +
1.30 +For an event occurring in British Summer Time (BST, GMT/UTC+01) this is a satisfactory means of describing the associated period. However, it can be more convenient to define an event in terms of the wall-clock time at a particular location. Sometimes, a regular meeting may occur at a particular time regardless of the introduction of daylight saving (or summer) time, and people can find it awkward to remember and choose the appropriate time zone, and thus the correct UTC offset. So instead, a time "regime" can be given. For example:
1.31 +
1.32 +{{{
1.33 + Start:: 2009-06-30 10:30 Europe/London
1.34 + End:: 2009-06-30 11:00 Europe/London
1.35 +}}}
1.36 +
1.37 +This indicates that in Britain (a "regime" defined for London, Europe) on the specified day, at 10:30am wall-clock time - that is, in the time zone reflected by properly adjusted local clocks - the event will begin, concluding at 11am according to the same clocks.
1.38 +
1.39 +For most events, specifying a "regime" should be sufficiently accurate and unambiguous. However, some potential issues with specifying time information in such a way are [[#TimeProblems|described below]].
1.40 +
1.41 === Supported Event Properties ===
1.42
1.43 As well as the start and end dates of an event, the following properties are also recognised as being part of an event description:
1.44 @@ -74,6 +108,29 @@
1.45
1.46 To start a distinct event, just define a property that has already been recorded for the previous event on the page, if any. Usually, the start and end dates will be the most suitable properties for this purpose.
1.47
1.48 +<<Anchor(TimeProblems)>>
1.49 +=== Occasional Problems with Times ===
1.50 +
1.51 +In most circumstances, specifying a time "regime" should result in an appropriate time zone being deduced and thus defined for an event. In some circumstances, however, such wall-clock times can be ambiguous or ill-defined. For example:
1.52 +
1.53 +{{{
1.54 + Start:: 2010-03-28 02:30 Europe/London
1.55 + End:: 2010-03-28 02:45 Europe/London
1.56 +}}}
1.57 +
1.58 +In this example, the given times (2:30am and 2:45am) do not exist as wall-clock times: since British clocks observe GMT/UTC until 2am and then switch to BST (GMT/UTC+01), times between 2am and 3am do not really appear on clocks on that particular day. !EventAggregator will indicate a problem with events specified in such a way, but will still produce [[HelpOnEventAggregatorSummary|event summaries]] assuming that the intention was to schedule such a period as starting 30 minutes after 2am in GMT/UTC and ending 45 minutes after 2am in GMT/UTC, pretending that the time zone preceding the zone change has remained in force for the sake of the event.
1.59 +
1.60 +Where the wall-clock time is effectively repeated, !EventAggregator will also indicate a problem with events defined using such ambiguous times. For example:
1.61 +
1.62 +{{{
1.63 + Start:: 2010-10-31 02:30 Europe/London
1.64 + End:: 2010-10-31 02:45 Europe/London
1.65 +}}}
1.66 +
1.67 +In this example, the given times (2:30am and 2:45am) ''do'' exist as wall-clock times, but such times appear ''twice'' on clocks: since British clocks observe BST (GMT/UTC+01) until 3am and then switch to GMT/UTC, times between 2am and 3am are visited twice by clocks on that particular day. For [[HelpOnEventAggregatorSummary|event summaries]], the assumption will be made that the intention was to schedule such a period as starting 30 minutes after 2am in BST and ending 45 minutes after 2am in BST, pretending (as above) that the time zone preceding the zone change is the correct zone.
1.68 +
1.69 +Naturally, without explicitly specifying a time zone (as an offset from UTC), it is not possible to schedule the above event for the period from 2:30am until 2:45am in the GMT/UTC time zone. However, when !EventAggregator indicates a problem with the event specification, an organiser can be alerted to the problem and thus fully specify the event times. Where !EventAggregator provides an implicitly assumed time (and where the organiser ignores the warnings or does not want to specify the time zone), no-one will be late for (or miss) the event: the earliest possible time will have been chosen, giving participants the opportunity to return at the "correct" time should the assumed time have proven to be "incorrect".
1.70 +
1.71 <<Anchor(PreparingACalendar)>>
1.72 == Preparing a Calendar ==
1.73
1.74 @@ -160,7 +217,7 @@
1.75 <<EventAggregator(CategoryEvents,parent=Events)>>
1.76 }}}
1.77
1.78 -Creating an event called '''Meeting''' under a parent called '''Events''' will make the page '''Events/Meeting''', and this will be shown as '''Meeting''' in the calendar. However, if a different parent is chosen, such as '''Meetings''', then the full path to the page will be shown in the calendar: '''Meetings » Meeting'''.
1.79 +Creating an event called '''Meeting''' under a parent called '''Events''' will make the page '''Events/Meeting''', and this will be shown as '''Meeting''' in the calendar. However, if a different parent is chosen, such as '''Meetings''', then the full path to the page will be shown in the calendar: '''Meetings » Meeting'''.
1.80
1.81 == Showing Event Lists and Tables ==
1.82