Initial revision

svn path=/trunk/; revision=1823

3 files changed, 1339 insertions, 0 deletions

diff --git a/libical/doc/UsingLibical.lyx b/libical/doc/UsingLibical.lyx
new file mode 100644
index 0000000000..20eaffd288
--- /dev/null
+++ b/libical/doc/UsingLibical.lyx
@@ -0,0 +1,719 @@
+#This file was created by <eric> Mon Feb  7 20:19:42 2000
+#LyX 1.0 (C) 1995-1999 Matthias Ettrich and the LyX Team
+\lyxformat 2.15
+\textclass linuxdoc
+\language default
+\inputencoding default
+\fontscheme default
+\graphics default
+\paperfontsize default
+\spacing single 
+\papersize Default
+\paperpackage a4
+\use_geometry 0
+\use_amsmath 0
+\paperorientation portrait
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\defskip medskip
+\quotes_language english
+\quotes_times 2
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+
+\layout Title
+
+Using Libical
+\layout Author
+
+Eric Busboom (eric@softwarestudio.org)
+\layout Date
+
+January 2000
+\layout Section
+
+Introduction 
+\layout Standard
+
+Libical is an Open Source implementation of the iCalendar protocols and
+ protocol data units.
+ The iCalendar specification describes how calendar clients can communicate
+ with calendar servers for users can store their calendar data and arrange
+ meetings with other users.
+ 
+\layout Standard
+
+Libical implements the following specifications and protocols
+\layout Standard
+\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
+multicol5
+5 2 0 0 -1 -1 -1 -1
+1 1 0 0
+1 1 0 0
+1 1 0 0
+1 1 0 0
+1 1 0 0
+8 1 0 "" ""
+8 1 1 "" ""
+0 8 1 0 0 0 0 "" ""
+0 8 1 0 0 0 0 "" ""
+0 8 1 0 0 0 0 "" ""
+0 8 1 0 0 0 0 "" ""
+0 8 1 0 0 0 0 "" ""
+0 8 1 0 0 0 0 "" ""
+0 8 1 0 0 0 0 "" ""
+0 8 1 0 0 0 0 "" ""
+0 8 1 0 0 0 0 "" ""
+0 8 1 0 0 0 0 "" ""
+
+iCal Core
+\newline 
+2445
+\newline 
+iTIP
+\newline 
+2446
+\newline 
+iMIP
+\newline 
+2447
+\newline 
+iRIP
+\newline 
+draft
+\newline 
+CAP
+\newline 
+draft
+\layout Standard
+
+(The current version, 0.14, does not implement iRip or CAP.
+ ) 
+\layout Standard
+
+This documentation assumes that you are familiar with the iCalendar standards
+ RFC2445 and RFC2446.
+\layout Subsection
+
+The libical project
+\layout Standard
+
+This code is under active development.
+ If you would like to contribute to the project, you can contact me, Eric
+ Busboom, at eric@softwarestudio.org.
+ The project has a webpage at
+\layout Quote
+
+http://softwarestudio.org/libical/index.html 
+\layout Standard
+
+and a mailing list that you can join by sending the following mail:
+\layout Code
+
+To: minimalist@softwarestudio.org 
+\layout Code
+
+Subject: subscribe libical 
+\layout Subsection
+
+License
+\layout Standard
+
+The code and datafiles in this distribution are licensed under the Mozilla
+ Public License.
+ See http://www.mozilla.org/NPL/MPL-1.0.html for a copy of the license.
+ Alternately, you may use libical under the terms of the GNU Library General
+ Public License.
+ See http://www.fsf.org/copyleft/lesser.html for a copy of the LGPL.
+\layout Standard
+
+This dual license ensures that the library can be incorporated into both
+ proprietary code and GPL'd programs, and will benefit from improvements
+ made by programmers in both realms.
+ I will only accept changes into my version of the library if they are similarly
+ dual-licensed.
+\layout Subsection
+
+Purpose & Goals 
+\layout Subsection
+
+Document version
+\layout Standard
+
+$Id: UsingLibical.lyx,v 1.1 2000/02/17 18:02:36 alves Exp $
+\layout Section
+
+Building the Library
+\layout Section
+
+Structure 
+\layout Standard
+
+The iCal calendar model is based on four types of objects: components, propertie
+s, values and parameters.
+ 
+\layout Standard
+
+Properties are the fundamental unit of information in iCal, and they work
+ a bit like a hash entry, with a constant key and a variable value.
+ Properties may also have modifiers, called parameters.
+ In the iCal content line
+\layout Code
+
+ORGANIZER;ROLE=CHAIR:MAILTO:mrbig@host.com
+\layout Standard
+
+The property name is 
+\begin_inset Quotes eld
+\end_inset 
+
+ORGANIZER,
+\begin_inset Quotes erd
+\end_inset 
+
+ the value of the property is 
+\begin_inset Quotes eld
+\end_inset 
+
+mrbig@host.com
+\begin_inset Quotes erd
+\end_inset 
+
+ and the 
+\begin_inset Quotes eld
+\end_inset 
+
+ROLE
+\begin_inset Quotes erd
+\end_inset 
+
+ parameter specifies that Mr Big is the chair of the meetings associated
+ with this property.
+ 
+\layout Standard
+
+Components are groups of properties that represent the core objects of a
+ calendar system, such as events or timezones.
+ 
+\layout Standard
+
+The central goal of libical is to parse iTIP data into an internal representatio
+n of Components, Properties, Parameters an Values, and to allow the user
+ to manipulate the data in various ways
+\layout Subsection
+
+Components 
+\layout Subsection
+
+Properties 
+\layout Subsection
+
+Values 
+\layout Subsection
+
+Parameters 
+\layout Subsection
+
+Enumerations
+\layout Subsection
+
+Types
+\layout Subsection
+
+The Parser
+\layout Subsection
+
+Restrictions
+\layout Subsection
+
+Memory Management
+\layout Section
+
+Differences From RFCs 
+\layout Standard
+
+Libical has been designed to follow the standards as closely as possible,
+ so that the key objects in the standards are also keey objects in the library.
+ However, there are a few areas where the specifications are (arguably)
+ irregular, and following them exactly would result in an unfriendly interface.
+ These deviations make libical easier to use by maintaining a self-similar
+ interface.
+ 
+\layout Subsection
+
+Pseudo Components 
+\layout Standard
+
+Libical defines components for groups of properties that look and act like
+ components, but are not defined as components in the specification.
+ XDAYLIGHT and XSTANDARD are notable examples.
+ These pseudo components group properties within the VTIMEZONE components.
+ XDAYLIGHT starts with 
+\begin_inset Quotes eld
+\end_inset 
+
+BEGIN:DAYLIGHT
+\begin_inset Quotes erd
+\end_inset 
+
+ and ends with 
+\begin_inset Quotes eld
+\end_inset 
+
+END:DAYLIGHT, just like other components, but is not defined as a component
+ in RFC2445.
+ ( See RFC2445, page 61 ) In Libical, it is a component.
+ 
+\layout Standard
+
+There are also pseudo components that are conceptually derived classess
+ of VALARM.
+ RFC2446 defines what properties may be included in each component, and
+ for VALARM, the set of properties it may have depends on the value of the
+ ACTION property.
+ 
+\layout Standard
+
+For instance, if a VALARM component has an ACTION property with the value
+ of 
+\begin_inset Quotes eld
+\end_inset 
+
+AUDIO,
+\begin_inset Quotes erd
+\end_inset 
+
+ the component must also have an 
+\begin_inset Quotes eld
+\end_inset 
+
+ATTACH
+\begin_inset Quotes erd
+\end_inset 
+
+ property.
+ However, if the ACTION value is 
+\begin_inset Quotes eld
+\end_inset 
+
+DISPLAY,
+\begin_inset Quotes erd
+\end_inset 
+
+ the component must have a DESCRIPTION property.
+ 
+\layout Standard
+
+To handle these various, complex restrictions, libical has pseudo components
+ for each type of alarm: XAUDIOALARM, XDISPLAYALARM, XEMAILALARM and XPROCEDUREA
+LARM.
+ 
+\layout Subsection
+
+Combined Values 
+\layout Standard
+
+Many values can take more than one type.
+ TRIGGER, for instance, can have a value type of with DURATION or of DATE-TIME.
+ These multiple types make it difficult to create routines to return the
+ value associated with a property.
+ 
+\layout Standard
+
+It is natural to have interfaces that would return the value of a property,
+ but it is cumbersone for a single routine to return multiple types.
+ So, in libical, properties that can have multiple types are given a single
+ type that is the union of their RFC2445 types.
+ For instance, in libical, the value of the TRIGGER property resolves to
+ 
+\noun on 
+struct icaltriggertype
+\noun default 
+.
+ This type is a union of a DURATION and a DATE-TIME.
+ 
+\layout Subsection
+
+Multi-Valued Properties
+\layout Standard
+
+Some properties, such as CATEGORIES have only one value type, but each CATEGORIE
+S property can have multiple value instances.
+ This also results in a cumbersome interface -- CATEGORIES accessors would
+ have to return a list while all other accessors returned a single value.
+ In libical, all properties have a single value, and multi-valued properties
+ are broken down into multiple single valued properties during parsing.
+ That is, an input line like, 
+\layout Code
+
+CATEGORIES: work, home
+\layout Standard
+
+becomes in libical's internal representation
+\layout Code
+
+CATEGORIES: work
+\layout Code
+
+CATEGORIES: home
+\layout Standard
+
+Oddly, RFC2445 allows some multi-valued properties ( like FREEBUSY ) to
+ exist as both a multi-values property and as multiple single value properties,
+ while others ( like CATEGORIES ) can only exist as single multi-valued
+ properties.
+ This makes the internal representation for CATEGORIES illegal.
+ However when you convert a component to a string, the library will collect
+ all of the CATEGORIES properties into one.
+ 
+\layout Section
+
+Implementation Limitations 
+\layout Section
+
+Using libical
+\layout Subsection
+
+Creating Components 
+\layout Standard
+
+There are three ways to create components in Libical: creating individual
+ objects and assembling them, building entire objects in massive vaargs
+ calls, and parsing a text file containing iCalendar data.
+ 
+\layout Subsubsection
+
+Constructor Interfaces 
+\layout Standard
+
+Using constructor interfaces, you create each of the objects seperately
+ and them assemble them in to components: 
+\layout Code
+
+event = icalcomponent_new(ICAL_VEVENT_COMPONENT);
+\layout Code
+
+icalcomponent_add_property(event, icalproperty_new_dtstamp(atime) );
+\layout Code
+
+icalcomponent_add_property(event,icalproperty_new_uid(strdup("guid-1.host1.com"))
+ );
+\layout Code
+
+property=icalproperty_new_organizer(strdup("mrbig@host.com")); 
+\layout Code
+
+icalproperty_add_parameter(property,icalparameter_new_role(ICAL_ROLE_CHAIR)
+ );
+\layout Code
+
+icalcomponent_add_property(event,property);
+\layout Subsubsection
+
+vaargs Constructors 
+\layout Subsubsection
+
+Parsing Text Files 
+\layout Subsection
+
+Accessing Components 
+\layout Subsubsection
+
+Finding Components 
+\layout Subsubsection
+
+Removing Components 
+\layout Standard
+
+Removing an element from a list while iterating through the list can cause
+ problems, since you will probably be removing the element that the internal
+ iterator points to.
+ This will result in the iteration loop terminating immediately after removing
+ the element.
+ To avoid the problem, you will need to step the iterator ahead of the element
+ you are going to remove, like this:
+\layout Code
+
+for(c = icalcomponent_get_first_component(parent_comp,ICAL_ANY_COMPONENT);
+ 
+\layout Code
+
+
+\protected_separator 
+ 
+\protected_separator 
+ 
+\protected_separator 
+ 
+\protected_separator 
+c != 0; 
+\layout Code
+
+
+\protected_separator 
+ 
+\protected_separator 
+ 
+\protected_separator 
+ 
+\protected_separator 
+c = next
+\layout Code
+
+{ 
+\layout Code
+
+
+\protected_separator 
+ 
+\protected_separator 
+ next = icalcomponent_get_next_component(parent_comp,ICAL_ANY_COMPONENT);
+\layout Code
+
+
+\protected_separator 
+ 
+\protected_separator 
+ icalcomponent_remove_component(parent_comp,c); 
+\layout Code
+
+}
+\layout Subsubsection
+
+Finding Properties 
+\layout Subsubsection
+
+Removing Properties 
+\layout Subsubsection
+
+Getting Values 
+\layout Subsubsection
+
+Setting Values 
+\layout Subsubsection
+
+Getting Parameters
+\layout Subsubsection
+
+Setting Parameters 
+\layout Subsubsection
+
+Removing Parameters 
+\layout Subsubsection
+
+Checking Component Validity
+\layout Subsection
+
+Storing Objects
+\layout Standard
+
+The libical distribution inclues a seperate library, libicalss, that allows
+ you to store iCal component data to disk in a variety of ways.
+ This library is documented seperately.
+ 
+\layout Subsection
+
+Memory Management 
+\layout Standard
+
+Libical relies heavily on dynamic allocation for both the core objects and
+ for the strings used to hold values.
+ Some of this memory the library caller owns and must free, and some of
+ the memory is managed by the library.
+ Here is a summary of the memory rules.
+ 
+\layout Description
+
+1) If the function name has "new" in it, the caller gets control of the
+ memory.
+ ( such as icalcomponent_new(), or icalproperty_new_clone() ) 
+\layout Description
+
+2) If you got the memory from a routine with new in it, you must call the
+ corresponding *_free routine to free the memory.
+ ( Use icalcomponent_free() to free objects created with icalcomponent_new())
+ 
+\layout Description
+
+3) If the function name has "add" in it, the caller is transfering control
+ of the memory to the routine.
+ ( icalproperty_add_parameter() )
+\layout Description
+
+4) If the function name has "remove" in it, the caller passes in a pointer
+ to an object and after the call returns, the caller owns the object.
+ So, before you call icalcomponent_remove_property(comp,foo), you do not
+ own "foo" and after the call returns, you do.
+ 
+\layout Description
+
+5) If the routine returns a string, libical owns the memory and will put
+ it on a ring buffer to reclaim later.
+ You'd better strdup() it if you want to keep it, and you don't have to
+ delete it.
+ 
+\layout Subsection
+
+Error Handling
+\layout Standard
+
+icalerror_errno.
+ Return values.
+ #defines.
+ icalerror_stop_here
+\layout Subsubsection
+
+Return values
+\layout Subsubsection
+
+icalerrno
+\layout Subsubsection
+
+Component errors
+\layout Subsection
+
+Naming Standard
+\layout Standard
+
+Structures that you access with the 
+\begin_inset Quotes eld
+\end_inset 
+
+struct
+\begin_inset Quotes erd
+\end_inset 
+
+ keyword, such as 
+\begin_inset Quotes eld
+\end_inset 
+
+struct icaltimetype
+\begin_inset Quotes erd
+\end_inset 
+
+ are things that you are allowed to see inside and poke at.
+ 
+\layout Standard
+
+Structures that you access though a typedef, such as 
+\begin_inset Quotes eld
+\end_inset 
+
+icalcomponent
+\begin_inset Quotes erd
+\end_inset 
+
+ are things where all of the data is hidden.
+ 
+\layout Standard
+
+Component names that start with 
+\begin_inset Quotes eld
+\end_inset 
+
+V
+\begin_inset Quotes erd
+\end_inset 
+
+ are part of RFC 2445 or another iCal standard.
+ Component names that start with 
+\begin_inset Quotes eld
+\end_inset 
+
+X
+\begin_inset Quotes erd
+\end_inset 
+
+ are also part of the spec, but they are not actually components in the
+ spec.
+ However, they look and act like components, so they are components in libical.
+ Names that start with 
+\begin_inset Quotes eld
+\end_inset 
+
+XLIC
+\begin_inset Quotes erd
+\end_inset 
+
+ or 
+\begin_inset Quotes eld
+\end_inset 
+
+X-LIC
+\begin_inset Quotes erd
+\end_inset 
+
+ are not part of any iCal spec.
+ They are used internally by libical.
+ 
+\layout Standard
+
+Enums that identify a component, property, value or parameter end with 
+\begin_inset Quotes eld
+\end_inset 
+
+_COMPONENT,
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+_PROPERTY,
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+_VALUE,
+\begin_inset Quotes erd
+\end_inset 
+
+ or 
+\begin_inset Quotes eld
+\end_inset 
+
+_PAAMETER
+\begin_inset Quotes erd
+\end_inset 
+
+s
+\layout Standard
+
+Enums that identify a parameter value have the name of the parameter as
+ the second word.
+ For instance: ICAL_ROLE_REQPARTICIPANT or ICAL_PARTSTAT_ACCEPTED.
+\layout Standard
+
+The enums for the parts of a recurarance rule and request statuses are irregular.
+ 
+\layout Section
+
+Useful Recipies
+\layout Standard
+
+Iteration
+\layout Standard
+
+Copying components.
+ Remember that you must clone or remove an object before putting in on anothr
+ list.
+ 
+\layout Standard
+
+Finding compliance errors
+\layout Section
+
+Performance
+\layout Standard
+
+Checking restrictions is computationally expensive
+\layout Section
+
+Hacks and Bugs
+\the_end
diff --git a/libical/doc/UsingLibical.sgml b/libical/doc/UsingLibical.sgml
new file mode 100644
index 0000000000..d967bd860c
--- /dev/null
+++ b/libical/doc/UsingLibical.sgml
@@ -0,0 +1,318 @@
+<!doctype linuxdoc system>
+
+<!-- LinuxDoc file was created by LyX 1.0 (C) 1995-1999 by <eric> Wed Jan  5 22:30:06 2000
+ -->
+ <article>
+ <title>
+Using Libical
+ </title>
+ <author>
+Eric Busboom (eric@softwarestudio.org)
+ </author>
+ <date>
+January 2000
+ </date>
+ <sect>
+Introduction 
+ <p>
+Libical is an Open Source implementation of the iCalendar protocols and
+ protocol data units. The iCalendar specification describes how calendar clients
+ can communicate with calendar servers for users can store their calendar data
+ and arrange meetings with other users. 
+ </p>
+ <p>
+Libical implements the following specifications and protocols
+ </p>
+ <p>
+iCal Core
+2445
+iTIP
+2446
+iMIP
+2447
+iRIP
+draft
+CAP
+draft
+ </p>
+ <p>
+(The current version, 0.14, does not implement iRip or CAP. ) 
+ </p>
+ <p>
+This code is under active development. If you would like to contribute
+ to the project, you can contact me, Eric Busboom, at eric@softwarestudio.org.
+ The project has a webpage at
+ </p>
+ <p>
+ <quote>
+http://softwarestudio.org/libical/index.html 
+ </quote>
+</p> <p>
+and a mailing list that you can join by sending the following mail:
+ </p>
+ <p>
+ <code>
+------------ 
+To: minimalist@softwarestudio.org 
+Subject: subscribe libical 
+------------
+ </code>
+</p> <p>
+&dollar;Id: UsingLibical.lyx,v 1.3 2000/01/06 06:20:06 eric Exp eric &dollar;
+ </p>
+ <sect1>
+License
+ <p>
+The code and datafiles in this distribution are licensed under the Mozilla
+ Public License. See http://www.mozilla.org/NPL/MPL-1.0.html for a copy of the
+ license. Alternately, you may use libical under the terms of the GNU Library
+ General Public License. See http://www.fsf.org/copyleft/lesser.html for a copy
+ of the LGPL.
+ </p>
+ <p>
+This dual license ensures that the library can be incorporated into both
+ proprietary code and GPL'd programs, and will benefit from improvements made
+ by programmers in both realms. I will only accept changes into my version of
+ the library if they are similarly dual-licensed.
+ </p>
+ <sect1>
+Purpose &amp; Goals 
+ <sect>
+Building the Library
+ <sect>
+Structure 
+ <p>
+The iCal calendar model is based on four types of objects: components,
+ properties, values and parameters. 
+ </p>
+ <p>
+Components are the fundamental grouping of calendar information
+ </p>
+ <p>
+Properties are the fundamental unit of information. Each property is composed
+ of a type, a value and collection of parameters. 
+ </p>
+ <sect1>
+Components 
+ <p>
+Components are named clusters of properties
+ </p>
+ <sect1>
+Properties 
+ <sect1>
+Values 
+ <sect1>
+Parameters 
+ <sect1>
+Storage
+ <sect2>
+Cluster
+ <sect2>
+Store
+ <sect2>
+Calendar
+ <sect1>
+Other bits
+ <p>
+Restrictions
+ </p>
+ <p>
+Types
+ </p>
+ <sect>
+Differences From RFCs 
+ <p>
+Although libical has been design to follow the standards as closely as
+ possible, there are a few areas where the specifications are irregular, and
+ following them exactly would result in an unfriendly interface. 
+ </p>
+ <sect1>
+Pseudo Components 
+ <p>
+Libical defines pseudo components for groups of properties that look and
+ act like components, but are not defined as components in the specification.
+ XDAYLIGHT and XSTANDARD are notable examples. These pseudo components group
+ properties within the VTIMEZONE components. XDAYLIGHT starts with "BEGIN:DAYLIGHT"
+ and ends with "END:DAYLIGHT, just like other components, but is not defined
+ as a component in RFC2445. ( See RFC2445, page 61 ) In Libical, it is a component.
+ 
+ </p>
+ <p>
+There are also pseudo componentsthat are conceptually derived classess
+ of VALARM. RFC2446 defines what properties may be included in each component,
+ and for VALARM, the set of properties it may have depends on the value of the
+ ACTION property. 
+ </p>
+ <p>
+For instance, if a VALARM component has an ACTION property with the value
+ of "AUDIO," the component must also have an "ATTACH" property. However, if the
+ ACTION value is "DISPLAY," the component must have a DESCRIPTION property. 
+ </p>
+ <p>
+To handle these various, complex restrictions, libical has pseudo components
+ for each type of alarm: XAUDIOALARM, XDISPLAYALARM, XEMAILALARM and XPROCEDUREALARM.
+ 
+ </p>
+ <sect1>
+Combined Values 
+ <p>
+Many values can take more than one type. TRIGGER, for instance, can have
+ a value type of with DURATION or of DATE-TIME. It is natural to have interfaces
+ that would return the value of a property, but it is cumbersone for a single
+ routine to return multiple types. So, in libical, properties that can have
+ multiple types are given a single type that is the union of their RFC2445 types.
+ In libical, the value of the TRIGGER property resolves to 
+ </p>
+ <p>
+struct icaltriggertype
+ </p>
+ <p>
+This type is a union of a DURATION and a DATE-TIME. 
+ </p>
+ <sect1>
+Multi-Valued Properties
+ <p>
+Some properties, such as CATEGORIES, have a single value type, but may
+ have multiple values in a single instance. This also results in a cumbersome
+ interface -- CATEGORIES accessors would have to return a list which all other
+ accessors returned a single value. In libical, all properties have a single
+ value, and multi-valued properties are broken down into multiple single valued
+ properties during parsing. The is, 
+ </p>
+ <p>
+ <code>
+CATEGORIES: work, home
+ </code>
+</p> <p>
+becomes in libical's internal representation
+ </p>
+ <p>
+ <code>
+CATEGORIES: work
+CATEGORIES: home
+ </code>
+</p> <p>
+Oddly, RFC2445 allows some multi-valued properties ( like FREEBUSY ) to
+ exist as both a multi-values property and as multiple single value properties,
+ while others ( like CATEGORIES ) can only exist as single multi-valued properties.
+ This makes the internal representation for CATEGORIES illegal. However when
+ you convert a component to a string, the library will collect all of the CATEGORIES
+ properties into one. 
+ </p>
+ <sect>
+Implementation Limitations 
+ <sect>
+Using libical
+ <sect1>
+Creating Components 
+ <sect2>
+Constructor interfaces 
+ <sect2>
+vaargs Constructors 
+ <sect2>
+Parsing Text Files 
+ <sect1>
+Accessing Components 
+ <sect2>
+Finding Components 
+ <sect2>
+Removing Components 
+ <p>
+Removing an element from a list while iterating through the list can cause
+ problems, since you will probably be removing the element that the internal
+ iterator points to. This will result in the iteration loop terminating immediately
+ after removing the element. To avoid the problem, you will need to step the
+ iterator ahead of the element you are going to remove, like this:
+ </p>
+ <p>
+ <code>
+for(c = icalcomponent_get_first_component(s); 
+    c != 0; 
+    c = next)
+&lcub; 
+    next = icalcomponent_get_next_component(s);
+    icalcomponent_remove_component(s,c); 
+&rcub;
+ </code>
+</p> <sect2>
+Finding Properties 
+ <sect2>
+Removing Properties 
+ <sect2>
+Getting Values 
+ <sect2>
+Setting Values 
+ <sect2>
+Getting Parameters
+ <sect2>
+Setting Parameters 
+ <sect2>
+Removing Parameters 
+ <sect1>
+Storing Objects
+ <p>
+When you store a component to the database with icalstore_add_component,
+ you give the library takes the memory, so the caller does not own the component
+ anymore. If you want to keep ownership, use clone to make a copy. ( See "Memory
+ Management" and "Naming Starndard for more about routines with "add" in the name.
+ ) 
+ </p>
+ <sect1>
+Memory Management 
+ <p>
+Here are the memory rules for the C library:
+ </p>
+ <p>
+ <descrip>
+  <tag>
+1)</tag>If the function name has &quot;new&quot; in it, the caller gets
+ control of the memory. ( such as icalcomponent_new(), or icalproperty_new_clone()
+ ) 
+  <tag>
+2)</tag>If you got the memory from a routine with new in it, you must
+ call the corresponding *_free routine to free the memory. ( Use icalcomponent_free()
+ to free objects created with icalcomponent_new()) 
+  <tag>
+3)</tag>If the function name has &quot;add&quot; in it, the caller is
+ transfering control of the memory to the routine. ( icalproperty_add_parameter()
+ )
+  <tag>
+4)</tag>If the function name has &quot;remove&quot; in it, the caller
+ passes in a pointer to an object and after the call returns, the caller owns
+ the object. So, before you call icalcomponent_remove_property(comp,foo), you
+ do not own &quot;foo&quot; and after the call returns, you do. 
+  <tag>
+5)</tag>If the routine returns a string, libical owns the memory and will
+ put it on a ring buffer to reclaim later. You'd better strdup it if you want
+ to keep it, and you don't have to delete it. 
+ </descrip>
+</p> <sect1>
+Error Handling
+ <sect2>
+Return values
+ <sect2>
+icalerrno
+ <sect2>
+Component errors
+ <sect1>
+Naming Standard
+ <p>
+Structures that you access with the "struct" keyword, such as "struct icaltimetype"
+ are things that you are allowed to see inside and poke at. 
+ </p>
+ <p>
+Structures that you access though a typedef, such as "icalcomponent" are
+ things where all of the data is hidden. 
+ </p>
+ <p>
+Component names that start with "V" are part of RFC 2445 or another iCal
+ standard. Component names that start with "X" are also part of the spec, but
+ they are not actually components in the spec. However, they look and act like
+ components, so they are components in libical. Names that start with "XLIC" or
+ "X-LIC" are not part of any iCal spec. They are used internally by libical. 
+ </p>
+ <sect>
+Hacks and Bugs
+
+
+ </article>
diff --git a/libical/doc/UsingLibical.txt b/libical/doc/UsingLibical.txt
new file mode 100644
index 0000000000..f80ea31121
--- /dev/null
+++ b/libical/doc/UsingLibical.txt
@@ -0,0 +1,302 @@
+
+
+Using Libical
+
+Eric Busboom (eric@softwarestudio.org)
+
+January 2000
+
+1 Introduction 
+
+Libical is an Open Source implementation of the iCalendar protocols
+and protocol data units. The iCalendar specification describes how
+calendar clients can communicate with calendar servers for users can
+store their calendar data and arrange meetings with other users. 
+
+Libical implements the following specifications and protocols
+
++----------+-------+
+|iCal Core | 2445  |
++----------+-------+
++----------+-------+
+|  iTIP    | 2446  |
++----------+-------+
++----------+-------+
+|  iMIP    | 2447  |
++----------+-------+
++----------+-------+
+|  iRIP    | draft |
++----------+-------+
++----------+-------+
+|   CAP    | draft |
++----------+-------+
+
+
+(The current version, 0.14, does not implement iRip or CAP. ) 
+
+This documentation assumes that you are familiar with the iCalendar
+standards RFC2445 and RFC2446.
+
+1.1 The libical project
+
+This code is under active development. If you would like to contribute
+to the project, you can contact me, Eric Busboom, at eric@softwarestudio.org.
+The project has a webpage at
+
+http://softwarestudio.org/libical/index.html 
+
+and a mailing list that you can join by sending the following mail:
+
+------------ 
+
+To: minimalist@softwarestudio.org 
+
+Subject: subscribe libical 
+
+------------
+
+1.2 License
+
+The code and datafiles in this distribution are licensed under the
+Mozilla Public License. See http://www.mozilla.org/NPL/MPL-1.0.html
+for a copy of the license. Alternately, you may use libical under
+the terms of the GNU Library General Public License. See http://www.fsf.org/copyleft/lesser.html
+for a copy of the LGPL.
+
+This dual license ensures that the library can be incorporated into
+both proprietary code and GPL'd programs, and will benefit from improvements
+made by programmers in both realms. I will only accept changes into
+my version of the library if they are similarly dual-licensed.
+
+1.3 Purpose & Goals 
+
+1.4 Document version
+
+$Id$
+
+2 Building the Library
+
+3 Structure 
+
+The iCal calendar model is based on four types of objects: components,
+properties, values and parameters. 
+
+Properties are the fundamental unit of information in iCal, and they
+work a bit like a hash entry, with a constant key and a variable value.
+Properties may also have modifiers, called parameters. In the iCal
+content line
+
+ORGANIZER;ROLE=CHAIR:MAILTO:mrbig@host.com
+
+The property name is ``ORGANIZER,'' the value of the property is ``mrbig@host.com''
+and the ``ROLE'' parameter specifies that Mr Big is the chair of the
+meetings associated with this property. 
+
+Components are groups of properties that represent the core objects
+of a calendar system, such as events or timezones. 
+
+The central goal of libical is to parse iTIP data into an internal
+representation of Components, Properties, Parameters an Values, and
+to allow the user to manipulate the data in various ways
+
+3.1 Components 
+
+3.2 Properties 
+
+3.3 Values 
+
+3.4 Parameters 
+
+3.5 Enumerations
+
+3.6 Types
+
+3.7 The Parser
+
+3.8 Restrictions
+
+3.9 Memory Management
+
+4 Differences From RFCs 
+
+Libical has been designed to follow the standards as closely as possible,
+so that the key objects in the standards are also keey objects in
+the library. However, there are a few areas where the specifications
+are (arguably) irregular, and following them exactly would result
+in an unfriendly interface. These deviations make libical easier to
+use by maintaining a self-similar interface. 
+
+4.1 Pseudo Components 
+
+Libical defines components for groups of properties that look and act
+like components, but are not defined as components in the specification.
+XDAYLIGHT and XSTANDARD are notable examples. These pseudo components
+group properties within the VTIMEZONE components. XDAYLIGHT starts
+with ``BEGIN:DAYLIGHT'' and ends with ``END:DAYLIGHT, just like other
+components, but is not defined as a component in RFC2445. ( See RFC2445,
+page 61 ) In Libical, it is a component. 
+
+There are also pseudo components that are conceptually derived classess
+of VALARM. RFC2446 defines what properties may be included in each
+component, and for VALARM, the set of properties it may have depends
+on the value of the ACTION property. 
+
+For instance, if a VALARM component has an ACTION property with the
+value of ``AUDIO,'' the component must also have an ``ATTACH'' property.
+However, if the ACTION value is ``DISPLAY,'' the component must have
+a DESCRIPTION property. 
+
+To handle these various, complex restrictions, libical has pseudo components
+for each type of alarm: XAUDIOALARM, XDISPLAYALARM, XEMAILALARM and
+XPROCEDUREALARM. 
+
+4.2 Combined Values 
+
+Many values can take more than one type. TRIGGER, for instance, can
+have a value type of with DURATION or of DATE-TIME. These multiple
+types make it difficult to create routines to return the value associated
+with a property. 
+
+It is natural to have interfaces that would return the value of a property,
+but it is cumbersone for a single routine to return multiple types.
+So, in libical, properties that can have multiple types are given
+a single type that is the union of their RFC2445 types. For instance,
+in libical, the value of the TRIGGER property resolves to struct icaltriggertype.
+This type is a union of a DURATION and a DATE-TIME. 
+
+4.3 Multi-Valued Properties
+
+Some properties, such as CATEGORIES have only one value type, but each
+CATEGORIES property can have multiple value instances. This also results
+in a cumbersome interface -- CATEGORIES accessors would have to return
+a list while all other accessors returned a single value. In libical,
+all properties have a single value, and multi-valued properties are
+broken down into multiple single valued properties during parsing.
+That is, an input line like, 
+
+CATEGORIES: work, home
+
+becomes in libical's internal representation
+
+CATEGORIES: work
+
+CATEGORIES: home
+
+Oddly, RFC2445 allows some multi-valued properties ( like FREEBUSY
+) to exist as both a multi-values property and as multiple single
+value properties, while others ( like CATEGORIES ) can only exist
+as single multi-valued properties. This makes the internal representation
+for CATEGORIES illegal. However when you convert a component to a
+string, the library will collect all of the CATEGORIES properties
+into one. 
+
+5 Implementation Limitations 
+
+6 Using libical
+
+6.1 Creating Components 
+
+6.1.1 Constructor Interfaces 
+
+6.1.2 vaargs Constructors 
+
+6.1.3 Parsing Text Files 
+
+6.2 Accessing Components 
+
+6.2.1 Finding Components 
+
+6.2.2 Removing Components 
+
+Removing an element from a list while iterating through the list can
+cause problems, since you will probably be removing the element that
+the internal iterator points to. This will result in the iteration
+loop terminating immediately after removing the element. To avoid
+the problem, you will need to step the iterator ahead of the element
+you are going to remove, like this:
+
+for(c = icalcomponent_get_first_component(s); 
+
+    c != 0; 
+
+    c = next)
+
+{ 
+
+    next = icalcomponent_get_next_component(s);
+
+    icalcomponent_remove_component(s,c); 
+
+}
+
+6.2.3 Finding Properties 
+
+6.2.4 Removing Properties 
+
+6.2.5 Getting Values 
+
+6.2.6 Setting Values 
+
+6.2.7 Getting Parameters
+
+6.2.8 Setting Parameters 
+
+6.2.9 Removing Parameters 
+
+6.2.10 Checking Component Validity
+
+6.3 Storing Objects
+
+The libical distribution inclues a seperate library, libicalss, that
+allows you to store iCal component data to disk in a variety of ways.
+This library is documented seperately. 
+
+6.4 Memory Management 
+
+Here are the memory rules for the library:
+
+1) If the function name has "new" in it, the caller gets control
+  of the memory. ( such as icalcomponent_new(), or icalproperty_new_clone()
+  ) 
+
+2) If you got the memory from a routine with new in it, you must
+  call the corresponding *_free routine to free the memory. ( Use
+  icalcomponent_free() to free objects created with icalcomponent_new()) 
+
+3) If the function name has "add" in it, the caller is transfering
+  control of the memory to the routine. ( icalproperty_add_parameter() )
+
+4) If the function name has "remove" in it, the caller passes in
+  a pointer to an object and after the call returns, the caller owns
+  the object. So, before you call icalcomponent_remove_property(comp,foo),
+  you do not own "foo" and after the call returns, you do. 
+
+5) If the routine returns a string, libical owns the memory and will
+  put it on a ring buffer to reclaim later. You'd better strdup it
+  if you want to keep it, and you don't have to delete it. 
+
+6.5 Error Handling
+
+6.5.1 Return values
+
+6.5.2 icalerrno
+
+6.5.3 Component errors
+
+6.6 Naming Standard
+
+Structures that you access with the ``struct'' keyword, such as ``struct
+icaltimetype'' are things that you are allowed to see inside and poke
+at. 
+
+Structures that you access though a typedef, such as ``icalcomponent''
+are things where all of the data is hidden. 
+
+Component names that start with ``V'' are part of RFC 2445 or another
+iCal standard. Component names that start with ``X'' are also part
+of the spec, but they are not actually components in the spec. However,
+they look and act like components, so they are components in libical.
+Names that start with ``XLIC'' or ``X-LIC'' are not part of any iCal
+spec. They are used internally by libical. 
+
+7 Hacks and Bugs