# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1463096107 -7200
# Node ID 1bf71abd78582d481dd36e65d5be8163cd26bf69
# Parent  9cb6a6acfe171c72f8d761a9fb75f7e114c1ff95
Added documentation for the schedule_for_delegate function.

diff -r 9cb6a6acfe17 -r 1bf71abd7858 docs/wiki/Preferences
--- a/docs/wiki/Preferences	Fri May 13 01:10:08 2016 +0200
+++ b/docs/wiki/Preferences	Fri May 13 01:35:07 2016 +0200
@@ -296,13 +296,20 @@
                        .. indicated quota group
                        .. (described in the [[../Resources|resources guide]])
 ==
+`same_domain_only`     || accept an invitation only if the organiser employs an
+                       .. address in the same domain as the resource
+==
 `schedule_across_quota`|| accept an invitation only if the organiser has not
                        .. reserved a resource for a conflicting period in any
                        .. other resource belonging to the indicated quota group
                        .. (described in the [[../Resources|resources guide]])
 ==
-`same_domain_only`     || accept an invitation only if the organiser employs an
-                       .. address in the same domain as the resource
+`schedule_for_delegate`|| accept an invitation only if the organiser can
+                       .. reserve the resource according to the common quota
+                       .. schedule, delegating to any other available resource
+                       .. defined as a potential delegate, declining if no
+                       .. resource is available
+                       .. (described in the [[../Resources|resources guide]])
 ==
 `schedule_in_freebusy` || accept an invitation if the event periods are free
                        .. according to the free/busy records for the resource;
diff -r 9cb6a6acfe17 -r 1bf71abd7858 docs/wiki/Resources
--- a/docs/wiki/Resources	Fri May 13 01:10:08 2016 +0200
+++ b/docs/wiki/Resources	Fri May 13 01:35:07 2016 +0200
@@ -413,6 +413,10 @@
 EOF
 }}}
 
+Note that this general quota applies to each individual identity and not
+collectively to all unspecified identities. To impose such a collective
+quota, a group may be defined for this purpose as described below.
+
 When a user identity is not listed and no general quota is defined, that
 particular user will be unable to reserve the resource unless defined as a
 member of a group listed in the `limits` file, as described below.
@@ -420,9 +424,25 @@
 ==== Sharing Quotas Across Users ====
 
 When the use of resources is to be shared between users in such a way that
-groups of users will be sharing a single quota, the `groups` file in the
-quota directory must be defined, mapping each user identity to the group to
-which they will belong. For example:
+groups of users will be sharing a single quota, a `groups` file in a quota
+directory (or records in the `quota_groups` table) must be defined, mapping
+each user identity to the group to which they will belong.
+
+A tool is provided to define groups and is used as follows:
+
+{{{
+cat <<EOF | tools/set_quota_groups.py 'mailto:resource-car-cadillac@example.com'
+mailto:vincent.vole@example.com developers
+* others
+EOF
+}}}
+
+Here, otherwise unrecognised organisers are mapped to the `others` group.
+Thus, all scheduling performed by such organisers will be done in a common
+journal with this label.
+
+The process of determining where an organiser's usage of resources is
+recorded is illustrated by the following example:
 
 {{{{#!table
 '''Scheduling Data''' || '''Decision Process'''
@@ -674,3 +694,91 @@
 }}}
 
 }}}}
+
+==== Delegating Attendance ====
+
+A number of resources may be regarded as interchangeable and can therefore
+stand in for each other when they are unavailable. The iCalendar specification
+supports the notion of delegation: the recipient of an event invitation may
+delegate their attendance to other calendar user, informing that user and the
+event organiser of this decision.
+
+To define such delegation relationships, a quota is first selected as the
+repository of common scheduling information for a group of resources. Then,
+the members of the group are defined as delegates. This can be done using a
+tool provided for this purpose. For example:
+
+{{{
+cat <<EOF | tools/set_delegates.py 'cars'
+mailto:resource-car-cadillac@example.com
+mailto:resource-car-pontiac@example.com
+EOF
+}}}
+
+Here, two resources are defined that will delegate to each other if they
+cannot attend an event according to their own schedule.
+
+{{{{#!table
+'''Scheduling Functions''' || '''Decision Process'''
+==
+<style="vertical-align: top;">
+
+{{{
+schedule_for_delegate cars
+}}}
+
+||
+
+{{{#!graphviz
+//format=svg
+//transform=notugly
+digraph scheduling_decisions {
+  node [shape=box,fontsize="13.0",fontname="Helvetica",tooltip="Scheduling decisions"];
+  edge [tooltip="Scheduling decisions"];
+
+  subgraph {
+    rank=same;
+    mail_cadillac [label="Incoming mail\nfrom vincent.vole@example.com\nto resource-car-cadillac@example.com",shape=folder,style=filled,fillcolor=cyan];
+    mail_pontiac [label="Incoming mail\nfrom vincent.vole@example.com\nto resource-car-pontiac@example.com",shape=folder,style=filled,fillcolor=cyan];
+    cancel [label="Incoming cancellation",shape=folder,style=filled,fillcolor=cyan];
+  }
+
+  subgraph {
+    rank=same;
+    schedule_for_delegate [label="Can be scheduled or delegated?",shape=ellipse,style=filled,fillcolor=gold];
+    quota_cars [label="Quota for cars",shape=folder];
+    freebusy_cars_vole [label="...recording schedule for\nvincent.vole@example.com",shape=folder];
+  }
+
+  schedule [label="Schedule event for resource",shape=ellipse,style=filled,fillcolor=gold];
+
+  subgraph {
+    rank=same;
+    accept [label="Accept",shape=folder,style=filled,fillcolor=cyan];
+    delegate [label="Delegate",shape=folder,style=filled,fillcolor=cyan];
+    decline [label="Decline",shape=folder,style=filled,fillcolor=cyan];
+  }
+
+  add_to_quota [label="Add to quota",shape=ellipse,style=filled,fillcolor=darkorange];
+  remove_from_quota [label="Remove from quota",shape=ellipse,style=filled,fillcolor=darkorange];
+
+  mail_cadillac -> schedule_for_delegate;
+  mail_pontiac -> schedule_for_delegate -> schedule -> accept;
+  schedule_for_delegate -> delegate [style=dashed];
+  schedule_for_delegate -> decline [style=dashed];
+  schedule -> add_to_quota -> quota_cars -> freebusy_cars_vole;
+  freebusy_cars_vole -> schedule_for_delegate;
+
+  cancel -> remove_from_quota -> freebusy_cars_vole;
+}
+}}}
+
+}}}}
+
+Note that it is generally more useful to have delegation decisions made on the
+basis of many resources, which is what the journal entries for each quota
+provides, but also for many organisers attempting to reserve those resources.
+Although the journal for each quota may be divided up to administer quotas for
+multiple groups of organisers, for the purposes of delegation - deciding
+whether a resource is generally available, and deciding which other resource
+would be available instead - a single group of all organisers is more desirable.