path: root/KEP-0012.txt
diff options
authorGeorg Greve <>2011-08-26 15:22:24 (GMT)
committerGeorg Greve <>2011-08-26 15:22:24 (GMT)
commit0683e67d006fda74f3a7ba478386957edc32c079 (patch)
tree97b814ec9e4af5938fcee1de003fbe1ae01f3e04 /KEP-0012.txt
parentac52cb17fd6a00f9c21482c0d2fff2f923540c1f (diff)
First draft for KEP
Diffstat (limited to 'KEP-0012.txt')
1 files changed, 117 insertions, 0 deletions
diff --git a/KEP-0012.txt b/KEP-0012.txt
new file mode 100644
index 0000000..b98cf2d
--- /dev/null
+++ b/KEP-0012.txt
@@ -0,0 +1,117 @@
+ |number=12
+ |ticketnumber=
+ |title=Color configuration storage for resources and categories
+ |author=Georg Greve
+ |
+ |status=draft
+ |type=design
+ |creation_date=2011-08-26
+ |obsoleted_by=
+ |related=
+== Abstract ==
+This Kolab Enhancement Proposal (KEP) <ref name="kep">[[KEP:1]] Bootstrapping the KEP process</ref> defines part of a changeset applied against Kolab XML version 1.0 of Kolab Format 2.0 for introduction of a new configuration and preference storage to be shared among clients for user defined color preferences for categories and resources such as calendars, address books or task lists. Based on KEP #9<ref name="kep9">[[KEP:9]] Storage of configuration and application control information</ref>, this KEP will make use of METADATA annotations as well as configuration XML objects and specialised folders for their storage.
+== Update to the XML Format ==
+The following changes to the Kolab Format are part of the changeset against Kolab XML version 1.0 as described by Kolab Format 2.0:
+=== '/vendor/kolab/color' RFC 5464 folder annotation ===
+Each folder '''MAY''' be annotated with an entry '/vendor/kolab/color' set to <color>, which is defined as follows:
+* The annotation '''MAY''' be used in both 'private' and 'shared' namespace. When the annotation is set in both namespaces, 'private' '''SHALL''' be authoritative for display;
+* The value of <color> '''SHALL''' be a sRGB<ref name="srgb">Wikipedia: [ sRGB]</ref> color value expressed in a web colors<ref name="webcolors">Wikipedia: [ Web colors]</ref> hexadecimal triplet of six characters with the magic value of 'XXXXXX' referring to an explicit 'No Color' selection;
+* Where clients support the usage of colors for resources, they '''SHALL''' consider the value of '/vendor/kolab/color' annotation authoritative;
+* Sub-folders '''SHALL''' inherit the <color> value of their parent folder. To break the inheritance chain a different color '''SHALL''' be specified or the magic value 'XXXXXX' '''SHALL''' be used for setting 'No Color';
+* 'No Color' '''SHALL''' mean that the client is free to visualize these entries in the most neutral manner available based on its visualization context. By default, 'No Color' '''SHOULD''' be interpreted as transparency for backgrounds, and black for foregrounds, unless the clients' standard text color is something else;
+* When the user sets the color for a folder and the user has sufficient permissions, clients '''MAY''' allow the user to choose whether to set the color for the 'private' or 'shared' namespace;
+* Where the the client does not present the user with an explicit selection in which namespace to store the selection, clients '''SHALL''' store the selection in the 'shared' namespace for all folders for which the user has admin permissions and use the 'private' namespace for all other folders;
+* Where the user is not authorized to store color preferences in the 'shared' namespace, the client '''SHALL''' automatically fall back to the 'private' namespace;
+* When '/vendor/kolab/color' is not set in a folder or any of its parent folders, clients '''MAY''' use their default colors/visualization schema, in which case they '''SHOULD''' store these preferences as appropriate by the rules defined above.
+=== 'category' object configuration ===
+==== Recital ====
+Categories are freely user defined. Their hierarchy is expressed through the special character ':' which separates the parent category name from the sub-category. There is no limit to the nesting level. An object can have an unlimited number of categories, which are storied in the 'categories' field with comma-separation.
+==== Object definition ====
+Incorporating KEP #9<ref name="kep9"></ref>, this KEP defines a new XML object 'category' as follows:
+* From the common fields, the object '''SHALL''' have all the required fields 'uid', 'creation-date', 'last-modification-date';
+* The regular 'uid' value '''SHALL''' be preceded by the string 'category:' to allow fast search for all objects of this type through the 'subject' field of the encapsulating email object;
+* The object '''SHALL''' also require the specific field 'name' which '''MAY''' define a 'color' attribute;
+* The 'name' field '''MAY''' have a nested hierarchy of sub-fields corresponding to the sub-categories which '''MAY''' each define separate 'color' attributes. Where no 'color' attribute is defined, the 'color' value is inherited from the parent;
+* The value of the 'color' attribute '''SHALL''' be identical to the value of the '/vendor/kolab/color' annotation, above, a missing 'color' attribute in a 'category' object '''SHALL''' be treated as inheritance from the parent category, and the magic value 'XXXXXX' '''SHALL''' be an explicit 'No Color' definition;
+* Objects of type 'category' '''MAY''' be stored in all non-email folders;
+* If there are several 'category' objects defining the color for the same category or categories, the following rules '''SHALL''' apply:
+** Where several 'category' objects define colors for the same category in one folder, the entry with the latest 'last-modification-date' shall prevail. A client '''MAY''' warn users of such conflicting settings and offer cleanup;
+** Where several 'category' objects define colors for the same category in different folders within one hierarchy, sub-folders prevail over parent folders. A client '''MAY''' choose to warn users of such redefinition and offer cleanup;
+** Where several 'category' objects define colors for the same category in different folders within separate hierarchies, the entry with the latest 'last-modification-date' of the prevailing entries of each hierarchical tree '''SHALL''' prevail.
+* A sub-category that has no color assigned shall inherit its color from the parent category;
+* A category that has no color assigned and has no parent category '''MAY''' either be visualized as 'No Color' '''-- OR --''' have its color assigned by the client, in which case the client '''SHOULD''' store this assignment in the users main 'configuration' folder.
+==== Examples ====
+The following examples constitute valid 'category' objects according to this KEP:
+ <?xml version="1.0" encoding="UTF-8"?>
+ <category version="2.1">
+ <uid></uid>
+ <creation-date>2011-08-26T18:00:00Z</creation-date>
+ <last-modification-date>2011-08-26T18:00:00Z</last-modification-date>
+ <product-id>Superclient (tm)</product-id>
+ <name color="8A2BE2">Work</name>
+ </category>
+to define that the category 'Work' is visualized using 'BlueViolet', or
+ <?xml version="1.0" encoding="UTF-8"?>
+ <category version="2.1">
+ <uid></uid>
+ <creation-date>2011-08-11T12:18:06Z</creation-date>
+ <last-modification-date>2011-08-11T12:18:06</last-modification-date>
+ <product-id>Another Superclient (tm)</product-id>
+ <name color="DC143C">Work
+ <name color="00008B">Meeting</name>
+ <name color="008B8B">Telephone
+ <name color="XXXXXX">ConfCall</name>
+ </name>
+ <name>Office</name>
+ </name>
+ </category>
+to define that the category 'Work' is visualized using 'Crimson', as is 'Work:Office', while 'Work:Meeting' is visualized as 'DarkBlue', 'Work:Telephone' is visualized in 'DarkCyan' and 'Work:Telephone:ConfCall' has an explicit assignment of 'No Color'.
+== Client behaviour ==
+Microsoft maintains a mapping table for its color names to Web colors in the MSDN<ref name="mscolors">MSDN: [ Colors by Name]</ref>. This table '''SHALL''' be used by Outlook connectors to most closely represent the colors defined for the resource or category. Authors of other clients are strongly encouraged to default to the Microsoft color table<ref name="mscolors"></ref> to ensure consistency across clients.
+== Upgrade Path ==
+This KEP adds new functionality and folder types that will not be understood by older clients.
+It is therefore a breaking change that will be applied in a changeset with other disruptive changes.
+== Rationale ==
+=== Colors for all resources ===
+Some Kolab clients such as Outlook<ref name="outlook">How-To Geek: [ Color Code Outlook for Easier Management]</ref> provide means for color-coding all kinds of resources, including email, so Kolab should support this as well. The same is true for an explicit 'No Color' setting<ref name="nocolor">Kolab Format posting by Shawn Walker: [ Re:Pre-KEP Request for Input: Storage of categories & colors]</ref>.
+=== Colors per folder ===
+In Kolab, one folder always represents one resource, e.g. an address book, a calendar, a task list, so storing the color for that resource as a folder annotation allows to (a) have consistent colors on one resource across the entire installation, and (b) set a different color scheme for individual users. With inheritance, it is possible to color whole trees appropriately. Annotations seem the most efficient way of storing this information because they can be read without parsing the entire folder.
+=== Colors per category ===
+In addition, colors are also supported for categories, e.g. for sorting events in a calendar. These are transversally to the folder colors, and different clients have different approaches to visualisation, e.g. KDE Kontact allows to customize the display to any of the following:
+* Category inside, calendar outside
+* Calendar inside, category outside
+* Only calendar
+* Only category
+Categories are substantially more complex than resource colors because unlike for resources, which are tied to folders, any object of any resource type anywhere in the folder tree can define any number of categories simply by using them. Any of these categories can be re-used in any object of any resource type and closely match the concept of what is also often referred to as 'tags'<ref name="tag">Wikipedia: [ Tag (metadata)]</ref>. So a client can only know all user-defined categories after having parsed the entire tree of resources for a user, including all resources in the 'shared' and 'user' namespaces that this user has access to.
+This makes annotations a poor choice to model this information, and even finding ways to make use of annotations for this purpose would not bring advantages because the client still has to parse the entire tree to know the complete set of categories.
+That is while more expensive in resource than the per folder coloring, the proposed approach for category coloring seems like the most efficient resolution of the requirement. Allowing storage in all non-email folders in particular allows addressing use cases where specific categories are defined in a shared folder with a specific coloring scheme that should be inherited by all clients that have access to the objects in this folder.
+== References ==
+== Copyright ==
+This document has been placed in the public domain.