bo: doc/kolab-formats .cvsignore, NONE, 1.1 Makefile, NONE, 1.1 commonfields.sgml, NONE, 1.1 contacts.sgml, NONE, 1.1 events.sgml, NONE, 1.1 folders.sgml, NONE, 1.1 journals.sgml, NONE, 1.1 kolabformat.sgml, NONE, 1.1 mail.sgml, NONE, 1.1 notes.sgml, NONE, 1.1 overview.sgml, NONE, 1.1 tasks.sgml, NONE, 1.1

cvs at intevation.de cvs at intevation.de
Thu Jun 10 17:15:54 CEST 2004


Author: bo

Update of /kolabrepository/doc/kolab-formats
In directory doto:/tmp/cvs-serv29541

Added Files:
	.cvsignore Makefile commonfields.sgml contacts.sgml 
	events.sgml folders.sgml journals.sgml kolabformat.sgml 
	mail.sgml notes.sgml overview.sgml tasks.sgml 
Log Message:
First rough draft of the new spec. Just modified the text version I mailed around to XML, and added a few fields.

--- NEW FILE: .cvsignore ---
kolabformat.aux
kolabformat.dvi
kolabformat.log
kolabformat.out
kolabformat.pdf
kolabformat.ps
kolabformat.tex
suse-html.dsl
suse-print.dsl
CATALOG.local

--- NEW FILE: Makefile ---
# Generates HTML, Postscript and PDF from SGML source.
#
# This file is Free Software under GNU GPL v>=2.
#
# Author(s):  Martin Konold <konold at erfrakon.de>
# 	      Bernhard Reiter <bernhard at intevatin.de>
#
# Known to run on Debian GNU/Linux with docbook-utils(0.6.13-2) and (0.6.13-4).

NAME=		kolabformat
HTML_DEST_DIR=	kolabformat
SHELL=		/bin/bash
SGML_SRC=	$(NAME).sgml 
INCLUDED_SRCS=	overview.sgml folders.sgml mail.sgml commonfields.sgml

HTML_DST=	$(HTML_DEST_DIR)/index.html
PS_DST=		$(NAME).ps
PDF_DST=	$(NAME).pdf
RTF_DST=	$(NAME).rtf

#HTML_CMD=	db2html -j -f/dev/null
HTML_CMD=	db2html
#PS_CMD=		db2ps -j -f/dev/null
PS_CMD=		db2ps 
#PDF_CMD=	db2pdf -j -f/dev/null
RTF_CMD=	db2rtf


all: html ps pdf rtf clean

html: $(HTML_DST)
ps:   $(PS_DST)
pdf: $(PDF_DST)
rtf: $(RTF_DST)

concept/index.html: $(SGML_SRC) $(INCLUDED_SRCS)
	$(HTML_CMD) $(SGML_SRC)
	cp erfrakon.png $(HTML_DEST_DIR)/
	mv $(HTML_DEST_DIR)/index.html $(HTML_DEST_DIR)/index.html.tmp
	cat $(HTML_DEST_DIR)/index.html.tmp | sed -e 's/SRC=\"erfrakon\"/SRC=\"erfrakon\.png\"/g' > $(HTML_DEST_DIR)/index.html
	rm $(HTML_DEST_DIR)/index.html.tmp

$(NAME).ps: $(SGML_SRC) $(INCLUDED_SRCS)
	$(PS_CMD) $(SGML_SRC)

$(NAME).pdf: $(NAME).ps
	ps2pdf $(NAME).ps

$(NAME).rtf: $(SGML_SRC) $(INCLUDED_SRCS)
	echo '**************'
	echo Keep in mind that "erfrakon.png" is referenced in the rtf file.
	echo
	$(RTF_CMD) $<
	mv $(NAME).rtf $(NAME).rtf.tmp
	cat $(NAME).rtf.tmp | sed -e 's/INCLUDEPICTURE \"erfrakon\"/INCLUDEPICTURE \"erfrakon.png\"/g' >$(NAME).rtf
	rm $(NAME).rtf.tmp

clean:
	rm -f *.tex *.dvi *.aux *.log 
	rm -rf db2html*
	rm -rf $(NAME).junk

realclean: clean
	rm -rf $(HTML_DEST_DIR)
	rm -f $(PDF_DST) $(NAME).ps $(RTF_DST)

--- NEW FILE: commonfields.sgml ---
<chapter><title>Common Fields</title>

<sect1><title>Common In All Types</title>

<para>There are a number of fields that are present in all non-mail
folder types. These are:</para>

<itemizedlist>
<listitem><para>UID (string)</para></listitem>

<listitem><para>Body (string)</para></listitem>

<listitem><para>Categories (string - uses comma separation between
multiple categories)</para></listitem>

<listitem><para>CreationDate (datetime)</para></listitem>

<listitem><para>LastModificationDate (datetime)</para></listitem>

<listitem><para>Sensitivity (string, possibilites are Private,
Confidential and Public)</para></listitem>
</itemizedlist>

<para>The sensitivity (aka access) is sort of an enum. The enums are
all case insensitive.</para>
</sect1>

<sect1><title>Common In Tasks And Events</title>

<para>These are the fields that are both in tasks and events. This
base class can be called incidence.</para>

<para><programlisting><![CDATA[
        <Summary>(string, default empty)</Summary>
        <Location>(string, default empty)</Location>
        <Organizer>
          <DisplayName>(string, default empty)</DisplayName>
          <Email>(string, default empty)</Email>
        </Organizer>
        <StartDate>(date or datetime, default not present)</StartDate>
        <Alarm>(number, no default)</Alarm>
        <Recurrence Cycle="cycletype" [Type="Extra type"]>
          <Interval>(number, default 1)</Interval>
          {<Day>(string, no default)</Day>}
          <Daynumber>(number, no default)</Daynumber>
          <Date>(number, no default)</Date>
          <Month>(string, no default></Month>
          <Range Type="rangetype">(date or number or nothing, no default)</Range>
          {<Exclusion>(date, no default)</Exclusion>}
        </Recurrence>
        {<Attendee>
          <DisplayName>(string, default empty)</DisplayName>
          <Email>(string, default empty)</Email>
          <Status>(string, default None)</Status>
          <RequestResponse>(bool, default true)</RequestResponse>
          <InvitationSent>(bool, default false)<InvitationSent>
          <Role>(string, default Required)</Role>
        </Attendee>}
]]></programlisting></para>

<para>The StartDate and DueDate are optional for the incidences. If
they are there, they can either have a date or a datetime as the
type. Parsing this is just a matter of looking at the length of the
date string.</para>

<para>The alarm specifies number of minutes before the incidence that
the alarm should fire. In case of incidences with only a start date
but no specific time, this means minutes before 0:00 on that
day.</para>

<sect2><title>Recurrance</title>

<para>There can be one <Recurrence> tag. This tag has an
attribute Cycle that is one of "Daily", "Weekly", "Monthly", or
"Yearly". Depending on the Cycle, different subtags are valid:</para>

<para>Daily: Interval specifies "every X days".</para>

<para>Weekly: Interval specifies "every X weeks". Day can be Monday,
Tuesday Wednesday, Thursday, Friday, Saturday, and Sunday. There can
be 1 to 7 of these days.</para>

<para>Monthly: The Recurrence tag has a second attribute type, which
can be either "Daynumber" or "Weekday". In both cases, Interval
specifies "every X months". In the case of Daynumber, tag <Date>
gives the date in the month this recurs on. For Weekday, tags
<Daynumber> and <Day> must be there.</para>

<para>Yearly: The Recurrence tag has a second attribute type, which
can be either "Monthday" or "Yearday". In both cases, Interval
specifies "every X years". If it's Monthday, tags <Date> and
<Month> apply. For Yearday, <Daynumber> is needed.</para>

<para>And the range must also be present. Finally there can be any
number of exclusions. These are dates that are removed from the list
of recurrences after all other calculations are done. This
specifically means if you recur three times but have an exclusion on
one of the dates, there will actually only be two recurrences.</para>
</sect2>

<sect2><title>Attendees</title>

<para>There can be any number of attendees.</para>

<para>The Status must be one of None, Tentative, Accepted, or
Declined.  InvitationSent only makes sense if RequestResponse is
true. If it's false, InvitationSent should be ignored. Role is one of
Required, Optional, or Resource.</para>
</sect2>

<sect2><title>Examples</title>

<para>Neverending incidence every 4 days with no exceptions:</para>

<para><programlisting><![CDATA[
        <Recurrence Cycle="Daily">
          <Interval>4</Interval>
          <Range type="None"/>
        </Recurrence>
]]></programlisting></para>

<para>Recurrence weekly on mondays and thursdays, until 5 has
happened. No exceptions:</para>

<para><programlisting><![CDATA[
        <Recurrence Cycle="Weekly">
          <Interval>3</Interval>
          <Day>Monday</Day>
          <Day>Thursday</Day>
          <Range type="Number">5</Range>
        </Recurrence>
]]></programlisting></para>

<para>Same one, but this time with one exception. Note that the actual
ending is the same, meaning in reality only four incidences
happened:</para>

<para><programlisting><![CDATA[
        <Recurrence Cycle="Weekly">
          <Interval>3</Interval>
          <Day>Monday</Day>
          <Day>Thursday</Day>
          <Range type="Number">5</Range>
          <Exception>20050504</Exception>
        </Recurrence>
]]></programlisting></para>

<para>Monthly recurrence. Happens until June 1st 2006 on the 3rd of
every second month with no exceptions:</para>

<para><programlisting><![CDATA[
        <Recurrence Cycle="Monthly" Type="Daynumber">
          <Interval>2</Interval>
          <Date>3</Date>
          <Range type="Date">20060601</Range>
        </Recurrence>
]]></programlisting></para>

<para>Monthly infinite recurrence with two exceptions. Happens every
second thursday of every sixth month:</para>

<para><programlisting><![CDATA[
        <Recurrence Cycle="Monthly" Type="Weekday">
          <Interval>6</Interval>
          <Daynumber>2</Daynumber>
          <Day>Thursday</Day>
          <Range type="None"/>
          <Exception>20051212</Exception>
          <Exception>20060615</Exception>
        </Recurrence>
]]></programlisting></para>

<para>Yearly recurrence ending after 2005 with no exceptions. Happens
every May 4th:</para>

<para><programlisting><![CDATA[
        <Recurrence Cycle="Yearly" Type="Monthday">
          <Interval>1</Interval>
          <Date>4</Date>
          <Month>June</Month>
          <Range type="Date">20051231</Range>
        </Recurrence>
]]></programlisting></para>

<para>Yearly infinite recurrence with no exceptions. Happens every
second year on the 125th day:</para>

<para><programlisting><![CDATA[
        <Recurrence Cycle="Yearly" Type="Yearday">
          <Interval>2</Interval>
          <Daynumber>125</Daynumber>
          <Range type="None"/>
        </Recurrence>
]]></programlisting></para>
</sect2>
</sect1>

</chapter>

--- NEW FILE: contacts.sgml ---
<chapter><title>Format Of Contacts</title>

<para>The mimetype for contacts is "application/kolab.contact". This
is the specification of the body contents:</para>

<para><programlisting><![CDATA[
        <?xml version="1.0" encoding="UTF-8"?>
        <!DOCTYPE Kolab-storage>
        <Contact Version="1.0">
          <!-- Base class attributes -->
          <UID>(string, no default)</UID>
          <Body>(string, default empty)</Body>
          <Categories>(string, default empty)</Categories>
          <CreationDate>(datetime, no default)</CreationDate>
          <LastModified>(datetime, no default)</LastModified>
          <Sensitivity>(string, default Public)</Sensitivity>
          {<Attachment>(string, no default)</Attachment>}
        
          <!-- Contact specific attributes -->
          <Name>
            <GivenName>(string, default empty)</GivenName>
            <LastName>(string, default empty)</LastName>
            <Initials>(string, default empty)</Initials>
            <FullName>(string, default empty)</FullName>
            <MiddleNames>(string, default empty)</MiddleNames>
            <Prefix>(string, default empty)</Prefix>
            <Suffix>(string, default empty)</Suffix>
          </Name>
          <Role>(string, default empty)</Role>
          <FreeBusyURL>(string, default empty)</FreeBusyURL>
          <Organization>(string, default empty)</Organization>
          <WebPage>(string, default empty)</WebPage>
          <IMAddress>(string, default empty)</IMAddress>
          <Department>(string, default empty)</Department>
          <OfficeLocation>(string, default empty)</OfficeLocation>
          <Profession>(string, default empty)</Profession>
          <JobTitle>(string, default empty)</JobTitle>
          <ManagerName>(string, default empty)</ManagerName>
          <Assistant>(string, default empty)</Assistant>
          <NickName>(string, default empty)</NickName>
          <SpouseName>(string, default empty)</SpouseName>
          <Birthday>(date, no default)</Birthday>
          <Anniversary>(date, no default)</Anniversary>
          <Picture>(string(attachment url), default empty)</Picture>
          <Children>(string, default empty)</Children>
          <Gender>(string, default empty)</Gender>
          <Language>(string, default empty)</Language>
          {<Phone>
            <Type>(string, no default)</Type>
            <Number>(string, default empty)</Number>
          </Phone>}
          {<Email>
            <DisplayName>(string, default empty)</DisplayName>
            <Email>(string, default empty)</Email>
          </Email>}
          {<Address>
            <Type>(string, default Home)</Type>
            <Street>(string, default empty)</Street>
            <City>(string, default empty)</City>
            <State>(string, default empty)</State>
            <Zip>(string, default empty)</Zip>
            <Country>(string, default empty)</Country>
          </Address>}
          <PreferredAddress>(string, default None)</PreferredAddress>
        </Contact>
]]></programlisting></para>

<para>In a contact, the body is the note.</para>

<para>You can have one phone number of each type. The types are:
Business1, Business2, BusinessFax, Callback, Car, Company, Home1,
Home2, HomeFax, ISDN, Mobile, Pager, Primary, Radio, Telex, TTYTDD,
Assistant, and Other.</para>

<para>The Kontact and Horde address books have the notion of a
preferred email address. This could be done by a bool on the emails or
a separate tag like for preferred address.</para>

<para>The Address Type can be Home, Business, and Other. The preferred
address can be set to one of these or None.</para>

</chapter>

--- NEW FILE: events.sgml ---
<chapter><title>Format Of Events</title>

<para>The mimetype for events is "application/kolab.event". This is
the specification of the body contents:</para>

<para><programlisting><![CDATA[
        <?xml version="1.0" encoding="UTF-8"?>
        <!DOCTYPE Kolab-storage>
        <Event Version="1.0">
          <!-- Base class attributes -->
          <UID>(string, no default)</UID>
          <Body>(string, default empty)</Body>
          <Categories>(string, default empty)</Categories>
          <CreationDate>(datetime, no default)</CreationDate>
          <LastModified>(datetime, no default)</LastModified>
          <Sensitivity>(string, default Public)</Sensitivity>
          {<Attachment>(string, no default)</Attachment>}
        
          <!-- Incidence base class specific attributes -->
          <Summary>(string, default empty)</Summary>
          <Location>(string, default empty)</Location>
          <Organizer>
            <DisplayName>(string, default empty)</DisplayName>
            <Email>(string, default empty)</Email>
          </Organizer>
          <StartDate>(date or datetime, default not present)</StartDate>
          <Alarm>(number, no default)</Alarm>
          <Recurrence Cycle="cycletype" [Type="Extra type"]>
            <Interval>(number, default 1)</Interval>
            {<Day>(string, no default)</Day>}
            <Daynumber>(number, no default)</Daynumber>
            <Date>(number, no default)</Date>
            <Month>(string, no default></Month>
            <Range Type="rangetype">(date or number or nothing, no default)</Range>
            {<Exclusion>(date, no default)</Exclusion>}
          </Recurrence>
          {<Attendee>
            <DisplayName>(string, default empty)</DisplayName>
            <Email>(string, default empty)</Email>
            <Status>(string, default None)</Status>
            <RequestResponse>(bool, default true)</RequestResponse>
            <InvitationSent>(bool, default false)<InvitationSent>
            <Role>(string, default Required)</Role>
          </Attendee>}
        
          <!-- Event specific attributes -->
          <ShowTimeAs>(string, default Busy)</ShowTimeAs>
          <ColorLabel>TODO: Joon will do this</ColorLabel>
          <EndDate>(date or datetime, default not present)</EndDate>
        </Event>
]]></programlisting></para>

<para>ShowTimeAs is one of Free, Tentative, Busy, or
OutOfOffice.</para>

<para>TODO: Joon will add the info on the possible entries in
ColorLabel.</para>

</chapter>

--- NEW FILE: folders.sgml ---
<chapter><title>Per Folder requirements</title>

<para>This chapter describes all necessary settings on the IMAP
folders in the Kolab storage format.</para>

<sect1><title>IMAP requirements</title>

<para>We will be using the ANNOTATEMORE proposal. If changes are made to
this in the standardization process, we will incorporate these. Also,
we must support IMAP namespaces. All relevant RFCs will be followed
(i.e. folder name encoding is by RFC 3501).</para>

<para>The INBOX is the default inbox of the user. The user can not
change this default. The INBOX will have the IMAP resource subfolders
(like we do today in the clients), and this location can not be set by
the user.</para>

<para>We will annotate all folders with this string:</para>

<para><programlisting><![CDATA[
        kolab.<type>[.<subtype>]
]]></programlisting></para>

<para>The <type> can be: mail, event, journal, task, note, or
contact.</para>

<para>The <subtype> for a mail folder can be inbox, drafts, sentitems,
or junkemail (this one holds spam mails). For the other <type>s, it
can only be default, or not set.</para>

<para>For other types of folders supported by the clients, these
should be prefixed with k for KMail, h for Horde and o for Outlook,
and look like for example "kolab.o-voicemail".</para>

<para>We will use "application/kolab.<type>" as the mimetype for the
emails used for storage.</para>

<para>The annotation must be set on creation, and can not be
changed. (TODO: We need to discuss what we should do with folders created
with other IMAP clients.)  If a folder has no annotation, Outlook and
the Toltec connector will ignore it completely. This is not an option
for Kontact and Horde, so we will by default consider them to hold
mail.</para>

<para>This is all quite restricted, but this is the only way Outlook
can do it. And when thinking of these rules, we could not come up with
many problems with them.</para>
</sect1>

<sect1><title>Mail contents</title>

<para>The mail we store in will have the some so far undefined text as
the body, and any number of attachments. One of these attachments will
be the XML file containing the entry. The mimetype will be
"application/kolab.<type>" where type is the content type of the
file. Some of these attachments can be referenced in the file, and
these are "owned" by the XML file.  Those that are not referenced must
be preserved when the mail is saved again.</para>
</sect1>

</chapter>

--- NEW FILE: journals.sgml ---
<chapter><title>Format Of Journals</Title>

<para>The mimetype for journals is "application/kolab.journal". This
is the specification of the body contents:</para>

<para><programlisting><![CDATA[
        <?xml version="1.0" encoding="UTF-8"?>
        <!DOCTYPE Kolab-storage>
        <Journal Version="1.0">
          <!-- Base class attributes -->
          <UID>(string, no default)</UID>
          <Body>(string, default empty)</Body>
          <Categories>(string, default empty)</Categories>
          <CreationDate>(datetime, no default)</CreationDate>
          <LastModified>(datetime, no default)</LastModified>
          <Sensitivity>(string, default Public)</Sensitivity>
          {<Attachment>(string, no default)</Attachment>}
        
          <!-- Journal specific attributes -->
          <Summary>(string, default empty)</Summary>
          <StartDate>(datetime, default not present)</StartDate>
          <EndDate>(datetime, default not present)</EndDate>
          {<Contact>
            <DisplayName>(string, default empty)</DisplayName>
            <Email>(string, default empty)</Email>
          </Contact>}
        </Journal>
]]></programlisting></para>

<para>There can be any number of attachments and contacts, which is
why these are in {}.</para>

<para>The Sensitivity can only be one of Public, Confidential, or
Private.</para>

</chapter>

--- NEW FILE: kolabformat.sgml ---
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!entity chapter-overview SYSTEM "overview.sgml">
<!entity chapter-folders SYSTEM "folders.sgml">
<!entity chapter-mail SYSTEM "mail.sgml">
<!entity chapter-common SYSTEM "commonfields.sgml">
<!entity chapter-notes SYSTEM "notes.sgml">
<!entity chapter-contacts SYSTEM "contacts.sgml">
<!entity chapter-journals SYSTEM "journals.sgml">
<!entity chapter-events SYSTEM "events.sgml">
<!entity chapter-tasks SYSTEM "tasks.sgml">
]>

<book>

<bookinfo>
<title>The Kolab Storage Format</title>
<subtitle>Very early draft</subtitle>
<authorgroup>
<othercredit>
<othername> Bo Thorsen, bo at sonofthor.dk </othername>
<othername> Joon Radley, joon at radleys.co.za </othername>
<othername> Stephan Buys, s.buys at codefusion.co.za </othername>
<othername> Stuart Binge, s.binge at codefusion.co.za </othername>
<othername> Martin Konold, martin.konold at erfrakon.de </othername>
<othername> http://www.kolab.org </othername>
</othercredit>
</authorgroup>
<pubdate>June 9th, 2004</pubdate>
<legalnotice>
<para> This documentation was written in SGML using the DocBook DTD. HTML
and Postscript output is generated automatically and depends on the
tools used. </para>
<para>
<trademark class='registered'>Windows XP</trademark>,
<trademark class='registered'>Microsoft Outlook</trademark>
are registered trademarks of Microsoft Corporation Inc.
<trademark>Toltec Connector</trademark>
is a trademark of Toltec Inc..
<trademark>K Desktop Environment</trademark> and <trademark>KDE</trademark>
are trademarks of the KDE e.V.
</para>
<para>
All other herein mentioned trademarks belong
to their respective owners.  Use of a term in this book should not be regarded as 
affecting the validity of any trademark or service mark.
</para>
<para>
Finally, the authors of this book are not liable for any errors found as well as anything that may cause a fault. However, if that does occur, please notify the authots so corrections can be made. Furthermore, the reader must also agree to use the information in this book at his/her own risk and relinquish the authors, from any mistakes due to this book. If not, please stop reading now.
</para>
<para>
BECAUSE THE CONTENT IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE CONTENT, TO THE EXTENT PERMITTED BY APPLICABLE LAW. THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE CONTENT "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK OF USE OF THE CONTENT IS WITH YOU. SHOULD THE CONTENT PROVE FAULTY, INACCURATE, OR OTHERWISE UNACCEPTABLE YOU ASSUME THE COST OF ALL NECESSARY REPAIR OR CORRECTION. 
</para>
<para>
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MIRROR AND/OR REDISTRIBUTE THE CONTENT AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE CONTENT, EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
</para>
</legalnotice>
<revhistory>

<revision>
<revnumber>0.0.1</revnumber>
<date>June 9th 2004</date>
</revision>

</revhistory>
</bookinfo>

&chapter-overview
&chapter-folders
&chapter-mail
&chapter-common
&chapter-notes
&chapter-contacts
&chapter-journals
&chapter-events
&chapter-tasks

</book>

--- NEW FILE: mail.sgml ---
<chapter><title>Mail Folders</title>

<para>Mail folders hold mails in the format as described in RFC 822.</para>

</chapter>

--- NEW FILE: notes.sgml ---
<chapter><title>Format Of Notes</title>

<para>The mimetype for notes is "application/kolab.note". This is the
specification of the body contents:</para>

<para><programlisting><![CDATA[
        <?xml version="1.0" encoding="UTF-8"?>
        <!DOCTYPE Kolab-storage>
        <Note Version="1.0">
          <!-- Base class attributes -->
          <UID>(string, no default)</UID>
          <Body>(string, default empty)</Body>
          <Categories>(string, default empty)</Categories>
          <CreationDate>(datetime, no default)</CreationDate>
          <LastModified>(datetime, no default)</LastModified>
          <Sensitivity>(string, default Public)</Sensitivity>
          {<Attachment>(string, no default)</Attachment>}
        
          <!-- Note specific attributes -->
          <Summary>(string, default empty)</Summary>
          <BackgroundColor>(color, default 0x000000)</BackgroundColor>
          <ForegroundColor>(color, default 0xFFFF00)</ForegroundColor>
        </Note>
]]></programlisting></para>
        
<para>There can be any number of attachments, which is why these are
in {}.</para>

<para>The Sensitivity can only be one of Public, Confidential, or
Private.</para>

</chapter>

--- NEW FILE: overview.sgml ---
<chapter><title>Kolab Storage Format Overview</title>

<para>The Kolab storage format is designed to provide a unified
storage format for several Kolab client implementations.</para>

<para>The storage format specifies an XML format to be saved in IMAP
folders.</para>

<sect1><title>XML format description</title>

<para>The fields in the XML file are written like this:</para>

<para><programlisting><![CDATA[
        <Field>(type, default)</Field>
]]></programlisting></para>

<para>If a field entry is the same as the default, then it's optional
whether to write it or not - exception from this is the creation and
last modification dates. If there are attributes with a limited amount
of options, these are specified after the text, and they are typically
case insensitive.</para>

<para>If a client sees a tag it does not understand, this tag must be
preserved and saved back to the file. This allows for client specific
tags. Outlook writes it client specific tags directly in a tnef file
that is saved as an unreferenced attachment.</para>

<para>Each type of folder has it's own subclass of the
specification. They all share this same XML header:</para>

<para><programlisting><![CDATA[
        <?xml version="1.0" encoding="UTF-8"?>
        <!DOCTYPE Kolab-storage>
]]></programlisting></para>

<para>After this, we have a single node with the content of the
file. One file can only hold one instance of the events, contacts,
... This looks like:</para>

<para><programlisting><![CDATA[
        <Type>
          Entry fields go here
        </Type>
]]></programlisting></para>

<para>All node names are case insensitive.</para>

<sect2><title>Types Used</title>

<para>The types that each entry can be are:</para>

<itemizedlist>
<listitem><para>String (utf8 encoded, can be multiple
lines)</para></listitem>

<listitem><para>Number (actually an int)</para></listitem>

<listitem><para>Date YYYYMMDD</para></listitem>

<listitem><para>Datetime YYYYMMDDHHMMSS - always in
UTC</para></listitem>

<listitem><para>Color 0xRRGGBB</para></listitem>

<listitem><para>Bool (True or False)</para></listitem>
</itemizedlist>

<para>The color and bool types are also case insensitive.</para>

</sect2>
</sect1>

</chapter>

--- NEW FILE: tasks.sgml ---
<chapter><title>Format Of Tasks</title>

<para>The mimetype for tasks is "application/kolab.task". This is the
specification of the body contents:</para>

<para><programlisting><![CDATA[
        <?xml version="1.0" encoding="UTF-8"?>
        <!DOCTYPE Kolab-storage>
        <Task Version="1.0">
          <!-- Base class attributes -->
          <UID>(string, no default)</UID>
          <Body>(string, default empty)</Body>
          <Categories>(string, default empty)</Categories>
          <CreationDate>(datetime, no default)</CreationDate>
          <LastModified>(datetime, no default)</LastModified>
          <Sensitivity>(string, default Public)</Sensitivity>
          {<Attachment>(string, no default)</Attachment>}
        
          <!-- Incidence base class specific attributes -->
          <Summary>(string, default empty)</Summary>
          <Location>(string, default empty)</Location>
          <Organizer>
            <DisplayName>(string, default empty)</DisplayName>
            <Email>(string, default empty)</Email>
          </Organizer>
          <StartDate>(date or datetime, default not present)</StartDate>
          <Alarm>(number, no default)</Alarm>
          <Recurrence Cycle="cycletype" [Type="Extra type"]>
            <Interval>(number, default 1)</Interval>
            {<Day>(string, no default)</Day>}
            <Daynumber>(number, no default)</Daynumber>
            <Date>(number, no default)</Date>
            <Month>(string, no default></Month>
            <Range Type="rangetype">(date or number or nothing, no default)</Range>
            {<Exclusion>(date, no default)</Exclusion>}
          </Recurrence>
          {<Attendee>
            <DisplayName>(string, default empty)</DisplayName>
            <Email>(string, default empty)</Email>
            <Status>(string, default None)</Status>
            <RequestResponse>(bool, default true)</RequestResponse>
            <InvitationSent>(bool, default false)<InvitationSent>
            <Role>(string, default Required)</Role>
          </Attendee>}
        
          <!-- Task specific attributes -->
          <Priority>(number, default 3)</Priority>
          <Completed>(number, default 0)</Completed>
          <Status>(string, default NotStarted)</Status>
          <DueDate>(date or datetime, default not present)</DueDate>
          <Parent>(string, default empty)</Parent>
        </Task>
]]></programlisting></para>

<para>Status can be one of NotStarted, InProgress, Completed,
WaitingOnSomeElse, or Deferred.</para>

<para>The priority can be a number between 1 and 5, with 1 being the
highest priority.</para>

<para>Completed is a percentage, so it must be between 0 and
100.</para>

<para>If this is a subtask, the Parent is set to the UID of the parent
task. If it's not a subtask, then the Parent field must be
empty.</para>

</chapter>





More information about the commits mailing list