summaryrefslogtreecommitdiff
path: root/KEP-0016.txt
blob: f3720c6be52aea8b3b3630f296465e784a77cc63 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
{{kep
 |number=16
 |ticketnumber=
 |title=Storage of dictionary entries
 |author=Georg Greve
 |author_email=greve@kolabsys.com
 |status=draft
 |type=design
 |creation_date=2011-09-30
 |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 object based on KEP #9<ref name="kep9">[[KEP:9]] Storage of configuration and application control information</ref> which allows storage of lists of dictionary entries to share them between several clients and users.

These lists are stored language specific, making use of best current practice as described in BCP 47<ref name="bcp47">[https://tools.ietf.org/html/bcp47 BCP 47]: Tags for Identifying Languages</ref> based language tags to identify the language to which this list of dictionary entries applies. In addition, this KEP also specifies a way to store lists of dictionary entries for all languages.

== 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:

=== 'dictionary' configuration object configuration ===
Incorporating KEP #9<ref name="kep9"></ref>, this KEP defines a new XML 'configuration' object of type 'dictionary' as follows:
* The object '''SHALL''' only be stored in a folder of type 'configuration';
* The mime-type of this object '''SHALL''' be 'application/x-vnd.kolab.configuration.dictionary';
* 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 'dictionary';
* There '''SHALL''' be two specific fields for this type of configuration object: 'language' and 'e';
* The 'language' field '''MUST''' occur exactly once, and '''SHALL''' identify the language to which this list of dictionary entries applies. The value of 'language' '''SHALL''' be a tag as set forth in BCP 47<ref name="bcp47" />;
* The 'language' field '''MAY''' be set to a special value 'XX' to indicate that this list of dictionary entries is language independent and applies to all languages;
* 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 
:* the mime-type if the value of 'language' is 'XX';
:* the mime-type concatenated with a '.' and the content of the 'language' field in all other cases;
* The 'e' field (short for 'entry') '''SHALL''' contain an individual word to be added to the dictionary;
* There '''SHALL''' be at least one 'e' record per dictionary configuration object, there is no limit to the number of 'e' records per object.

==== Examples ====
The following examples constitute valid 'dictionary' objects according to this KEP:

 <?xml version="1.1" encoding="UTF-8"?>
 <configuration version="2.1">
   <!-- Common fields -->
   <uid>7ahsdnnd61@some.host.somewhere</uid>
   <creation-date>2011-03-26T10:05:18Z</creation-date>
   <last-modification-date>2011-09-26T19:00:00Z</last-modification-date>
   <product-id>Superclient (tm)</product-id>
 
   <type>dictionary</type>
   <language>XX</language>   
 
   <e>Kolab</e>
 </configuration>

to add the word 'Kolab' to all languages, or

 <?xml version="1.1" encoding="UTF-8"?>
 <configuration version="2.1">
   <!-- Common fields -->
   <uid>7azhs@another.host.somewhere</uid>
   <creation-date>2011-03-26T10:05:18Z</creation-date>
   <last-modification-date>2011-09-26T19:00:00Z</last-modification-date>
   <product-id>Even More Superclient (tm)</product-id>
 
   <type>dictionary</type>
   <language>bg</language>   
 
   <e>Groupware</e>
   <e>Solution</e>
 </configuration>

to add the words 'Groupware' and 'Solution' to the Bulgarian dictionary.

The corresponding values for the 'X-Kolab-Type' header would be 'application/x-vnd.kolab.configuration.dictionary' for the first example, and 'application/x-vnd.kolab.configuration.dictionary.bg' for the second.

== Client behaviour ==
When words are added to the dictionary of a language for which an object of configuration type 'dictionary' already exists, clients '''SHALL''' append to the existing dictionary if sufficient permissions exist, and create a new object otherwise. When creating a new object, clients '''SHALL''' prefer the folder of type 'configuration' closes to the root of the folder tree that they have write permission for.

Clients '''SHALL''' delete objects of configuration type 'dictionary' once the last remaining 'e' entry has been deleted by the user.

== Upgrade Path ==
This KEP adds new functionality and folder types that will not be understood by older clients. 

== Rationale ==
There are two use cases for this KEP.

The first use case is about an individual user not wanting to have to re-train their dictionary on every client individually. With this KEP, dictionary changes in one client will automatically propagate to another.

The second use case is for groups or organizations that share a specific set of terminology within the group and use this mechanism to provide the canonical way of writing specific terms, such as product names.

== References ==

{{Reflist}}

== Copyright ==

This document has been placed in the public domain.