# HG changeset patch # User Paul Boddie # Date 1270930518 -7200 # Node ID 4d1868ee0321193626004fb197a6a2e5d8284d8c # Parent c05a82a6e3c1ea2047d48092a54f9f515728ce0c Added time-related documentation. Added missing action form field descriptions and format details. diff -r c05a82a6e3c1 -r 4d1868ee0321 pages/HelpOnEventAggregator --- a/pages/HelpOnEventAggregator Tue Mar 30 20:12:51 2010 +0200 +++ b/pages/HelpOnEventAggregator Sat Apr 10 22:15:18 2010 +0200 @@ -35,6 +35,40 @@ Obviously, duplicating the date information introduces a risk of this information becoming inconsistent, so beware! +=== Adding Time Information === + +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: + +{{{ + Start:: 2009-06-30 10:30 + End:: 2009-06-30 11:00 +}}} + +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: + +{{{ + Start:: 2009-06-30 10:30 UTC+0100 + End:: 2009-06-30 11:00 UTC+0100 +}}} + +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: + +{{{ + Start:: 2009-06-30 10:30 +01 + End:: 2009-06-30 11:00 +01 +}}} + +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: + +{{{ + Start:: 2009-06-30 10:30 Europe/London + End:: 2009-06-30 11:00 Europe/London +}}} + +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. + +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]]. + === Supported Event Properties === As well as the start and end dates of an event, the following properties are also recognised as being part of an event description: @@ -74,6 +108,29 @@ 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. +<> +=== Occasional Problems with Times === + +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: + +{{{ + Start:: 2010-03-28 02:30 Europe/London + End:: 2010-03-28 02:45 Europe/London +}}} + +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. + +Where the wall-clock time is effectively repeated, !EventAggregator will also indicate a problem with events defined using such ambiguous times. For example: + +{{{ + Start:: 2010-10-31 02:30 Europe/London + End:: 2010-10-31 02:45 Europe/London +}}} + +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. + +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". + <> == Preparing a Calendar == @@ -160,7 +217,7 @@ <> }}} -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'''. +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'''. == Showing Event Lists and Tables == diff -r c05a82a6e3c1 -r 4d1868ee0321 pages/HelpOnEventAggregatorSummary --- a/pages/HelpOnEventAggregatorSummary Tue Mar 30 20:12:51 2010 +0200 +++ b/pages/HelpOnEventAggregatorSummary Sat Apr 10 22:15:18 2010 +0200 @@ -5,9 +5,9 @@ == EventAggregatorSummary == -The !EventAggregatorSummary action provides iCalendar summaries of events whose details are recorded in pages belonging to specific categories (such as CategoryEvents). These summaries can then be imported into applications which understand the iCalendar format. +The !EventAggregatorSummary action provides iCalendar and RSS summaries of events whose details are recorded in pages belonging to specific categories (such as CategoryEvents). These summaries can then be imported into applications which understand the iCalendar or RSS formats such as calendar and scheduling applications or feed readers. -Upon invoking the action, an iCalendar response will be produced. If the action is invoked in a browser, it is most likely that a dialogue box will appear asking you whether you would like to save the response to a file or to open the response in a suitable application. This behaviour is slightly different to many !MoinMoin actions. +Upon invoking the action, an iCalendar or RSS response will be produced. If the action is invoked in a browser, it is most likely that a dialogue box will appear asking you whether you would like to save the response to a file or to open the response in a suitable application. This behaviour is slightly different to many !MoinMoin actions. == Using the Actions Menu Entry == @@ -16,6 +16,9 @@ * The names of categories known to the Wiki. * The start (first month) of the summary (optional). * The end (last month) of the summary (optional). + * The source of descriptions used in event summaries, taking either the event metadata or the comments made in the last edit of the event page. + * The format of the summary: iCalendar or RSS 2.0. + * The parent page can be specified in order to shorten any page names produced in a summary by removing their common parent (such as '''Events''' for pages called '''Events/Meeting''' and '''Events/Workshop'''). Where no start or end values are specified, all events in the chosen categories are included in the summary. @@ -49,6 +52,18 @@ A technical note: feed readers will typically detect updated events by consulting the content of each event description's `guid` element, notifying the user of changes if the content of that element has itself changed. +== Time Information in Summaries == + +The iCalendar format makes extensive use of time information and can employ complicated data structures in order to try and represent event times correctly. !EventAggregator has the following level of support for iCalendar features: + + * (./) Times applying everywhere or in an implicit time zone ("floating" times). + * (./) Times specified in the UTC time zone. + * {X} Times specified according to a particular time zone definition. + +The last of the above features involves the replication of a time zone specification for a particular time "regime", and this is arguably error-prone as well as requiring the production of large amounts of largely irrelevant information in every downloaded summary. + +!EventAggregator attempts to automatically convert time "regime" information (such as '''Europe/London''') to UTC for use in summaries. See the documentation on [[HelpOnEventAggregator#TimeProblems|problems with time information]] for some issues that might arise in some uncommon situations. + == See Also == * HelpOnEventAggregator - a macro producing event calendars and listings