1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/wiki/Preferences Wed Oct 28 18:08:40 2015 +0100
1.3 @@ -0,0 +1,255 @@
1.4 += Preferences =
1.5 +
1.6 +The correspondence between user preferences (stored in user preference
1.7 +directories) and the default settings (stored in `config.py`) is described
1.8 +below.
1.9 +
1.10 +|| '''Preference''' || '''Default Setting''' ||
1.11 +|| `LANG` || `LANG` ||
1.12 +|| `add_method_response` || `ADD_RESPONSE_DEFAULT` ||
1.13 +|| `event_refreshing` || `REFRESHING_DEFAULT` ||
1.14 +|| `freebusy_bundling` || `BUNDLING_DEFAULT` ||
1.15 +|| `freebusy_messages` || `NOTIFYING_DEFAULT` ||
1.16 +|| `freebusy_offers` || `FREEBUSY_OFFER_DEFAULT` ||
1.17 +|| `freebusy_publishing` || `PUBLISHING_DEFAULT` ||
1.18 +|| `freebusy_sharing` || `SHARING_DEFAULT` ||
1.19 +|| `incoming` || `INCOMING_DEFAULT` ||
1.20 +|| `organiser_replacement` || `ORGANISER_REPLACEMENT_DEFAULT` ||
1.21 +|| `participating` || `PARTICIPATING_DEFAULT` ||
1.22 +
1.23 +See the [[../Configuration|configuration guide]] for more information about
1.24 +the `config.py` file.
1.25 +
1.26 +== User Preference Settings ==
1.27 +
1.28 +<<TableOfContents(3,3)>>
1.29 +
1.30 +Each of the user preferences or settings are stored in a separate file within
1.31 +a dedicated preferences directory for each user, with the filename bearing the
1.32 +name of the setting concerned.
1.33 +
1.34 +=== CN ===
1.35 +
1.36 + Default:: (none)
1.37 + Alternatives:: (see below)
1.38 +
1.39 +The common name of the user, employed in iCalendar objects and user
1.40 +interfaces.
1.41 +
1.42 +=== LANG ===
1.43 +
1.44 + Default:: `en` (English)
1.45 + Alternatives:: (any recognised and supported locale)
1.46 +
1.47 +The language for messages and user interface text.
1.48 +
1.49 +=== TZID ===
1.50 +
1.51 + Default:: system timezone (see `/etc/timezone`)
1.52 + Alternatives:: (any recognised Olson time zone identifier)
1.53 +
1.54 +The default time zone/regime for calendars, new events and local times.
1.55 +
1.56 +=== add_method_response ===
1.57 +
1.58 + Default:: `refresh`
1.59 + Alternatives:: (see below)
1.60 +
1.61 +Indicate how `ADD` methods shall be responded to when received by a recipient:
1.62 +
1.63 +{{{#!table
1.64 +`add` || apply them to events as received
1.65 +==
1.66 +`ignore` || ignore attempts to add event occurrences
1.67 +==
1.68 +`refresh` || respond with a `REFRESH` message to obtain a proper request with
1.69 + .. all event details
1.70 +}}}
1.71 +
1.72 +=== event_refreshing ===
1.73 +
1.74 + Default:: `never`
1.75 + Alternative:: `always`
1.76 +
1.77 +Indicate whether messages requesting a refresh of event details shall be
1.78 +handled automatically. If not, such messages will be passed on to the
1.79 +recipient for their mail program to handle.
1.80 +
1.81 +=== freebusy_bundling ===
1.82 +
1.83 + Default:: `never`
1.84 + Alternative:: `always`
1.85 +
1.86 +Indicate whether to bundle free/busy details with other payloads such as
1.87 +event and free/busy objects. The `freebusy_sharing` setting must be
1.88 +configured for bundling to operate.
1.89 +
1.90 +=== freebusy_messages ===
1.91 +
1.92 + Default:: `none`
1.93 + Alternative:: `notify`
1.94 +
1.95 +Indicate whether recipients are notified about received free/busy payloads.
1.96 +
1.97 +=== freebusy_offers ===
1.98 +
1.99 + Default:: (none)
1.100 + Alternative:: (see below)
1.101 +
1.102 +Define the period for which free/busy offers are extended by participants
1.103 +supporting this setting when counter-proposals are made during event
1.104 +scheduling.
1.105 +
1.106 +This setting requires a value indicating a duration as described in the
1.107 +iCalendar format specification:
1.108 +
1.109 +http://tools.ietf.org/html/rfc5545#section-3.3.6
1.110 +
1.111 +For example:
1.112 +
1.113 +|| `PT10M` || extend scheduling offers for 10 minutes ||
1.114 +|| `PT600S` || extend scheduling offers for 600 seconds (10 minutes) ||
1.115 +|| `PT1D` || extend offers for 1 day ||
1.116 +
1.117 +=== freebusy_publishing ===
1.118 +
1.119 + Default:: `no`
1.120 + Alternative:: `publish`
1.121 +
1.122 +Indicate whether to publish free/busy details as Web resources. The
1.123 +`freebusy_sharing` setting must be configured for publishing to operate.
1.124 +
1.125 +=== freebusy_sharing ===
1.126 +
1.127 + Default:: `no`
1.128 + Alternative:: `share`
1.129 +
1.130 +Share free/busy details generally:
1.131 +
1.132 + * bundling in e-mail messages if bundling is configured
1.133 + * responding to free/busy requests via e-mail
1.134 + * publishing as Web resources if a static Web resource is configured and if
1.135 + publishing is configured
1.136 +
1.137 +=== incoming ===
1.138 +
1.139 + Default:: `summary-wraps-message`
1.140 + Alternatives:: (see below)
1.141 +
1.142 +Define how incoming event messages are delivered to recipients:
1.143 +
1.144 +{{{#!table
1.145 +`message-only`
1.146 +|| deliver only the incoming message as it was received
1.147 +==
1.148 +`message-then-summary`
1.149 +|| deliver the message first followed by a summary message
1.150 +==
1.151 +`summary-then-message`
1.152 +|| deliver a summary first followed by the message
1.153 +==
1.154 +`summary-only`
1.155 +|| deliver only a summary of the message
1.156 +==
1.157 +`summary-wraps-message`
1.158 +|| deliver a summary that includes the original message as an attachment
1.159 +}}}
1.160 +
1.161 +=== organiser_replacement ===
1.162 +
1.163 + Default:: `attendee`
1.164 + Alternatives:: (see below)
1.165 +
1.166 +Indicate whether the organiser of an event can be replaced and the nature of
1.167 +any replacement:
1.168 +
1.169 +{{{#!table
1.170 +`any` || any identity, regardless of whether it is already present or even
1.171 + .. previously unknown, may become the organiser
1.172 +==
1.173 +`attendee` || any new organiser must be a previously-recognised attendee
1.174 +==
1.175 +`never` || forbid the replacement of an event's organiser
1.176 +}}}
1.177 +
1.178 +=== participating ===
1.179 +
1.180 + Default:: `participate`
1.181 + Alternative:: `no`
1.182 +
1.183 +Indicate whether a recipient participates in the calendar system. Note that
1.184 +participation by default occurs because the handler programs will be defined
1.185 +in the mail system for recipients fulfilling certain criteria; other
1.186 +recipients will be handled in other ways. Thus, initial non-participation must
1.187 +be defined by initialising this setting to "no" for all eligible users, if
1.188 +this is the general policy on initial calendar system participation.
1.189 +
1.190 +=== permitted_times ===
1.191 +
1.192 + Default:: (none)
1.193 + Alternatives:: (see below)
1.194 +
1.195 +Define the time values at which events can be scheduled. In its simplest form,
1.196 +this indicates the resolution of a calendar for a participant supporting this
1.197 +setting, with the given minute values being those allowed for the start and
1.198 +end of an event. This setting requires a value of one of the following forms:
1.199 +
1.200 +{{{
1.201 +<minute values>
1.202 +<hour values>:<minute values>
1.203 +<hour values>:<minute values>:<second values>
1.204 +}}}
1.205 +
1.206 +Each list of values is a comma-separated collection of permissible values for
1.207 +the unit of time being constrained. Any unspecified list is taken to permit
1.208 +all normally permissible values for that unit of time. For example:
1.209 +
1.210 +{{{#!table
1.211 +`0,15,30,45` || every 15 minutes from the start of each hour
1.212 +==
1.213 +`10,12,14,16:0,20,40` || every 20 minutes from 10:00 until 16:40 inclusive
1.214 +==
1.215 +`12::0,30` || every 30 seconds from the start of each minute
1.216 + .. during the period from 12:00:00 until 12:59:30
1.217 + .. inclusive
1.218 +}}}
1.219 +
1.220 +The purpose of this setting is not necessarily to impose availability
1.221 +constraints but instead to impose a "grid" to which event start and end points
1.222 +shall be "locked".
1.223 +
1.224 +The values are interpreted in the local time of the participant. Thus, a time
1.225 +represented in UTC may have apparently inappropriate hour (and for some zones)
1.226 +minute values that correspond to permitted values in this participant's own
1.227 +time zone.
1.228 +
1.229 +=== scheduling_function ===
1.230 +
1.231 + Default:: `schedule_in_freebusy`
1.232 + Alternatives:: (see below)
1.233 +
1.234 +Indicates the scheduling function used by resources to find an appropriate
1.235 +period for an event. The `imiptools.handlers.scheduling` module contains the
1.236 +built-in scheduling functions which include the following:
1.237 +
1.238 +{{{#!table
1.239 +`schedule_in_freebusy` || accept an invitation if the event periods are free
1.240 + .. according to the free/busy records for the resource;
1.241 + .. decline otherwise
1.242 +==
1.243 +`schedule_corrected_in_freebusy` || correct periods in an event according to
1.244 + .. the permitted_times setting (see above),
1.245 + .. then attempt to schedule the event according to the
1.246 + .. free/busy records for the resource
1.247 +==
1.248 +`schedule_next_available_in_freebusy` || correct periods in an event according
1.249 + .. to the permitted_times setting (see
1.250 + .. above), if configured, and attempt to schedule the
1.251 + .. event according to the free/busy records for the
1.252 + .. resource and for any attendees for whom records are
1.253 + .. available, seeking the next available free period for
1.254 + .. each period that conflicts with an existing event
1.255 +}}}
1.256 +
1.257 +The scheduling mechanism can be extended by implementing additional scheduling
1.258 +functions or by extending the handler framework directly.