KEP-0012.txt

Georg Greve greve at kolabsys.com
Wed Sep 28 19:57:04 CEST 2011


 KEP-0012.txt |   83 ++++++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 52 insertions(+), 31 deletions(-)

New commits:
commit 4475cb0ecaafb0a5a1306143db89785f017f899d
Author: Georg Greve <greve at kolabsys.com>
Date:   Wed Sep 28 19:56:27 2011 +0200

    Worked in feedback from http://kolab.org/pipermail/kolab-format/2011-September/001463.html and http://kolab.org/pipermail/kolab-format/2011-September/001478.html

diff --git a/KEP-0012.txt b/KEP-0012.txt
index b98cf2d..bc485eb 100644
--- a/KEP-0012.txt
+++ b/KEP-0012.txt
@@ -21,12 +21,12 @@ The following changes to the Kolab Format are part of the changeset against Kola
 === '/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: [https://secure.wikimedia.org/wikipedia/en/wiki/SRGB sRGB]</ref> color value expressed in a web colors<ref name="webcolors">Wikipedia: [https://secure.wikimedia.org/wikipedia/en/wiki/Web_colors Web colors]</ref> hexadecimal triplet of six characters with the magic value of 'XXXXXX' referring to an explicit 'No Color' selection;
+* The value of <color> '''SHALL''' be a sRGB<ref name="srgb">Wikipedia: [https://secure.wikimedia.org/wikipedia/en/wiki/SRGB sRGB]</ref> color value expressed in a 6-digit hexadecimal web color<ref name="webcolors">Wikipedia: [https://secure.wikimedia.org/wikipedia/en/wiki/Web_colors Web colors]</ref> 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 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.
 
@@ -35,11 +35,13 @@ Each folder '''MAY''' be annotated with an entry '/vendor/kolab/color' set to <c
 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;
+Incorporating KEP #9<ref name="kep9"></ref>, this KEP defines a new XML 'configuration' object of type 'category' as follows:
+* The 'X-Kolab-Type' {{rfc|2822}} <ref name="rfc2822">{{rfc|2822|title=Internet Message Format}}</ref> message header of the encapsulating email object '''SHALL''' be set to 'application/x-vnd.kolab.configuration.category';
+* From the common fields, the object '''SHALL''' have all the required fields 'uid', 'creation-date', 'last-modification-date', and 'type';
+* The 'type' field '''SHALL''' be set to 'category';
+* The object '''SHALL''' also require at least one occurance of the specific field 'name' which '''MAY''' define a 'color' attribute;
+* The field 'name' '''MAY''' occur multiple times in one object;
+* Each '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:
@@ -52,36 +54,49 @@ Incorporating KEP #9<ref name="kep9"></ref>, this KEP defines a new XML object '
 ==== Examples ====
 The following examples constitute valid 'category' objects according to this KEP:
 
-    <?xml version="1.0" encoding="UTF-8"?>
-    <category version="2.1">
-    <uid>category:lahb1625akx at some.host.somewhere</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>
+ <?xml version="1.1" encoding="UTF-8"?>
+ <configuration version="2.1">
+   <!-- Common fields -->
+   <uid>lahb1625akx at some.host.somewhere</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>
+ 
+   <type>category</type>
+   
+   <name color="8A2BE2">Work</name>
+ </configuration>
 
 to define that the category 'Work' is visualized using 'BlueViolet', or
 
-    <?xml version="1.0" encoding="UTF-8"?>
-    <category version="2.1">
-    <uid>category:anotherrandomstring at some.host.somewhere</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
+ <?xml version="1.1" encoding="UTF-8"?>
+ <configuration version="2.1">
+   <!-- Common fields -->
+   <uid>anotherrandomstring at some.host.somewhere</uid>
+   <creation-date>2011-08-11T12:18:06Z</creation-date>
+   <last-modification-date>2011-08-11T12:18:06Z</last-modification-date>
+   <product-id>Another Superclient (tm)</product-id>
+ 
+   <type>category</type>
+   
+   <name color="DC143C">Work
     	  <name color="00008B">Meeting</name>
  	  <name color="008B8B">Telephone
- 	  	<name color="XXXXXX">ConfCall</name>
- 	  	</name>
+ 	        <name color="XXXXXX">ConfCall</name>
+ 	        </name>
      	  <name>Office</name>
  	  </name>
-    </category>
+   <name color="8A2BE2">Play</name>
+ </configuration>
 
-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'.
+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'. And finally the category 'Play' is assigned 'BlueViolet'.
 
 == Client behaviour ==
-Microsoft maintains a mapping table for its color names to Web colors in the MSDN<ref name="mscolors">MSDN: [http://msdn.microsoft.com/en-us/library/aa358802%28v=VS.85%29.aspx 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.
+Microsoft maintains a mapping table for its color names to Web colors in the MSDN<ref name="mscolors">MSDN: [http://msdn.microsoft.com/en-us/library/aa358802%28v=VS.85%29.aspx 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 '''SHOULD''' default to the Microsoft color table<ref name="mscolors"></ref> to promote consistency across clients. Clients '''MAY''' allow custom color definitions and tables.
+
+If a category is defined in a configuration object according to this KEP and this category is '''not''' currently assigned to any object in the users data set, clients '''SHOULD''' present it along with all other categories in the appropriate dialog(s) that are used to assign categories.
 
 == Upgrade Path ==
 This KEP adds new functionality and folder types that will not be understood by older clients. 
@@ -90,7 +105,9 @@ It is therefore a breaking change that will be applied in a changeset with other
 
 == Rationale ==
 === Colors for all resources ===
-Some Kolab clients such as Outlook<ref name="outlook">How-To Geek: [http://www.howtogeek.com/howto/4693/color-code-outlook-for-easier-management/ 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: [http://kolab.org/pipermail/kolab-format/2011-May/001355.html Re:Pre-KEP Request for Input: Storage of categories & colors]</ref>.
+Most groupware clients provide the means to color-code all types of groupware objects, including email (with flags), such as Outlook<ref name="outlook">How-To Geek: [http://www.howtogeek.com/howto/4693/color-code-outlook-for-easier-management/ Color Code Outlook for Easier Management]</ref>, but no client currently shares this information with other client (instances) through IMAP.
+
+This is highly desirable as consistent use of colors across all clients will make usage more intuitive and users will no longer need to set the colors in each client individually. The same is true for an explicit 'No Color' setting<ref name="nocolor">Kolab Format posting by Shawn Walker: [http://kolab.org/pipermail/kolab-format/2011-May/001355.html 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.
@@ -102,11 +119,15 @@ In addition, colors are also supported for categories, e.g. for sorting events i
 * 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: [https://secure.wikimedia.org/wikipedia/en/wiki/Tag_%28metadata%29 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. 
+KDE Kontact also allows nested levels of categories, making it necessary for this KEP to provide means of storage for them.
+
+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: [https://secure.wikimedia.org/wikipedia/en/wiki/Tag_%28metadata%29 Tag (metadata)]</ref>. So a client can only know all user-defined categories after having parsed all objects within the entire IMAP tree of resources for a user, including all resources in the 'shared' and 'user' namespaces that this user has access to. 
+
+This makes annotations an inferior choice to store 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.
 
-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.
+Clients '''can''' however make use of the 'X-Kolab-Type' {{rfc|2822}} <ref name="rfc2822" /> message header by searching for the value 'application/x-vnd.kolab.configuration.category' to quickly identify all objects that contain categories and their color definitions, making retrieval of category objects more efficient than retrieval of category names/definitions.
 
-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.
+So 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 ==
 





More information about the commits mailing list