initial import of icalsrv documentation

phpgwapi/doc/icalsrv/IcalSrv-BUGS-and-TODOS.txt

@@ -0,0 +1,107 @@
+/*! \page bugandtodopage BUGS and TODOS
+
+<PRE>
+Know BUGS and things todo
+---------------------------
+TODO means: should be done/would be nice  in a newer release
+BUG means: known problem needs to be fixed
+FAIl means: known failure to provide (not easily to be done/fixed
+
+(note: this list is probably not quite up todate)
+
+
+release: VERSION 0.7.80 NEED TO UPDATE THIS!!
+
+new in V0.7.78 versus v0.7.70:
+
+  bovevents:
+
++ whole day events import/export seems to work nice
++ continue on erroneous overwrites (errors only visible in errorlog)
++ no error messages for forbidden overwrite events of non owned events
++ errormessages (when activated) only shows problematic events
+++ basic (multiple) VALARM import and export, working! (without action select)
++ allow for vevents with either DTEND or DURATION
++ provided (horde iCalendar) patch to prevent segfaults on some bad iCal inputs
+
+1) general (V0.7)
+----------------
+
+1.1 TODO build egw install/setup system for icalsrv 
+1.2 TODO get it nicely into egw cvs
+1.3 TODO build user preferences (export/import period setting) gui
+[ ]1.7 TODO/WISH allow for import of ATTENDEEs not in Egw yet (create new addressbook entry?)
+         (ad hoc solution: add CN and mailto to description)
+1.4 TODO check and generate source code documentation(phpdoc or doxygen)
+
+1.5 TODO test these routines in use for syncml import/export
+
+1.6 TODO/WISH: nothing done yet for vfreebusy, vjournal, notes, components 
+    only vevents and vtodos are supported.
+
+
+2) icalsrv.php (V0.7)
+--------------------
+
+[+]2.1 BUG/CHECK repair/improve the http error return (403) (seems to work) 
+2.2 TODO integrate with 1.3 TODO
+
+[+]2.3 TODO handle (V)alarms
+
+[ ]2.4 TODO(for v0.7.80 ?) for expor: get the agent name from the http header and use
+    to set the ical product field. Then in egwical use it to set the supportedfields()
+
+
+3) egwical (V0.7.75)
+--------------------
+
+[+?]3.1 TODO check/implement correct timezone handling (seems ok) 
+3.2 TODO/WISH handle location (GEO), link(?), url, delegation, ()CONTACT?
+3.3 TODO set and use the productid in the ical, and use it to
+  setsupportedFields() (for mozilla, korganizer etc. ... with a default of.. )
+
+
+4) calendar.bovevents (V0.7.75)
+------------------------------
+
+[+?]4.1 TODO check/implement correct timezone handling (related 3.1)
+[ ]4.2 FAIL rrule-COUNT import not implemented in egw?
+[+]4.2 BUG!!!!  rrule-BYDAY import goes wrong. FIXED (v0.7.76)
+[+]4.3 TODO check and improve ORGANIZER,ATTENDEE<-> participants mapping
+	     ATTENDEE s import and export (appears to work oke >= V0.7.71) 
+[+]4.4 TODO handle import and export of ALARMS
+[ ]4.7 TODO (ad hoc) add non egw known attendees to description on import
+
+4.9 see 3.2
+
+
+5) infolog.bovtodos (V0.7.x)
+----------------------------
+5.1 TODO check/implement correct timezone handling  (related 3.1)
+5.3 FAIL import/export more than 1 category per task (egw doesnot allow)
+5.3 TODO check and improve ORGANIZER,ATTENDEE<-> info_responsible etc mapping
+5.4 TODO handle import and export of ALARMS
+5.5 TODO rewrite code into supportedFields structure (for next version)
+
+5.9 see 3.2
+
+
+
+
+10.) in  used routines from others:
+
+10.1 BUG Horde_iCalendar(1.2rc6): EXDATE bug
+  -[+]fixed by patch 'exdate ....'
+10.2 BUG  Horde_iCalendar(1.2rc6): standard.php Warning
+  -[+]fixed by patch '...??..'
+
+10.3 BUG infolog(1.2rc6): datetime is 1 hour wrong for untimed due field in tasks
+
+11) detected errors/flaws in other programs
+
+11.1 Korganizer 3.5: recurrence endondate display is interpreted different from egw and
+mozilla (and probable also rfc 2445) 
+
+
+</PRE>
+*/

phpgwapi/doc/icalsrv/IcalSrv-Manual-install-howto.txt

@@ -0,0 +1,168 @@
+/*!  @mainpage Ical Service for Egroupware
+
+@NOTE: this text is not up to date
+@version 0.9.01
+@author jvl
+
+@section secinstall SHORT experimental Install How-To:
+
+ - Install the icalsrv package by either checking out the icalsrv module from cvs
+ or untarring some tarball icalsrv-vx.y.x.tgz of the package (when available).
+
+ - @note: The IcalSrv package depends on the availability of an
+ EgwIcal (>= 0.9.x) package. So if you dont have this already, be sure
+ to install that too.
+
+ - Take care that icalsrv.php is .../egroupware/icalsrv.php (and the
+ other files from the icalsrv package also in their appropiate places)
+
+- Append something like the following onto your apache httpd.conf part for
+egroupware (assuming that your standard egroupware root path is e.g in
+/var/www/egroupware and with a http alias 'egroupware' pointing to
+it):
+<PRE>
+ <Location /egroupware/icalsrv.php>
+    Script PUT /var/www/egroupware/icalsrv.php
+    AddHandler ical/ics .ics
+    Action ical/ics /var/www/egroupware/icalsrv.php
+    Order allow,deny
+    Allow from all
+ </Location>
+</PRE>
+
+- Restart apache (or other webserver) ( /etc/init.d/httpd restart )
+
+- Connect your ical client (e.g: Sunbird)
+	   with http://your.host.com/egroupware/icalsrv.php
+        
+- now you should need to authenticate (with your normal EGW login and password)
+  and when done you receive the calendar on doing a "reload remote calendars" or so.
+
+- using the "publish" calendar action you can write the (modified) calendar
+  from the sunbird client back to EGW
+
+
+@section secdeletions Deleting Calendars, events or todos
+
+deletion of the whole remote calendar is not supported see the @ref
+webcaldiscusspage webcal protocol discussion.
+
+Individual calendar events or todos cannot be deleted either by just
+deleting them on the client and then hoping that this propagates to
+Egroupware on publish. There are various reasons for why this is not
+implemented. 
+
+But, you can though delete items by simply renaming them to
+<code>X-DELETE</code>.  I you do so they will get deleted in Egw on
+publishing. When you later dowload ("reload"/"refresh") the remote
+calendar in your client you should notice that the event is gone..
+
+
+@section secicalsrvclients Clients for IcalSrv
+
+This is tested with egw1.2rc6 and clients:
+
+  * Korganizer (3.3.2,(read)  3.4.2, 3.5.0 (READ+WRITE))
+  * Mozilla calendar (2004040813-cal) (READ+WRITE)
+  * Evolution 2.2 (READ)
+
+For further use and experience with these clients see @ref
+pageicalsrvclients IcalSrvClients page.
+
+
+@section secpatches Patches
+
+
+You may need to apply some of the patches found in PATCHES.
+Currently there a two patches to fix a warning and a bug (related to EXDATE 
+fields handling) in the horde routines.
+Note these may be already committed in the CVS version.
+
+
+
+@section sectest Extra testing
+
+The package contains "compatibility" classes with which you can replace 
+the current infolog/inc/class.vcalinfolog.inc.php resp. calendar/inc/class.boical.inc.php
+files.
+
+When done so, the egw syncml, ical import/export and infolog import/export in egw 
+will all use the new code. This way you can discover more bugs and failure in the code :)
+
+But, when not renamed, these programs will use the old code (and thus are not broken or
+improved by the new one..)
+
+
+@section secdocumentation Documentation
+
+There is (somewhere) complete doxygen generated documentation for the
+IcalSrv package. Otherwise you can generate it yourself by using
+doxygen on the source filetree. Maybe you are just reading it now ...
+
+
+@section sectestandebug Testing and Debugging
+
+As IcalSrv is still a young and experimental new service for
+Egroupware, that must mediate between a multitude of clients, each
+with their own peculiarities and various internal applications of Egw,
+it is very likely that a lot of problems, deficiencies and bugs will
+appear. 
+
+Thus to get error feedback for it is a healthy thing. You should best
+do this --as with any egw application-- using the sourcforge.net
+buglist and the dedicated egroupware forums or mailinglist (see the
+egroupware wiki for more instructions on this).
+
+What to report? Well you should realize that IcalSrv is --currently--
+on it self just a rather simple http interface script, that relies for
+it connection to the egw backends heavily on the new (re) written
+EgwIcal package. This means that problems with in and export of
+iCalendar data will mostly have their source in that (i.e. EgwIcal)
+package! So in case of errors allways report info on that package and
+when debugging try the debug tools for that package.
+
+@subsection subsecdebugtools Debugging of IcalSrv.
+
+IcalSrv does not generate webpages, so to see any error or debug
+information you there a jsut three other places to look at:
+
++ If you have a really problematic error, IcalSrv will answer your http
+ request with a 403 error and --hopefully-- a short message. In some
+ clients (like Korganize) this is reported back via a popup with a
+ silly message that "exporting went wrong or access denied" or so, instead of displaying
+ this message it got together with the 403 error. Note: Sunbird does
+ display the message. Unfortunately at the moment this will be mostly
+ "VEVENTS import ERROR" or so..
+
++ The httpd errorlog file/stream. Most problematic errors are reported
+ to this file of the egw server. So this is indeed the best source for
+ debug info. But to read it, you need access to the
+ server and to this log file. So only egw administrators are likely
+ the only ones for who this can be of help.
+ 
++ The ical.log files and ical.exportxxxx plus ical.importxxxx
+ files. If you did install the icalsrv.php file with the variable
+ $logdir set to folder where the httpd is allowed to write, you will
+ get a detailed log in file ical.log of all uploads and downloads via
+ IcalSrv furhtermore for each of these the associated iCalendar data
+ will be logged in ical.exportXXXXXX files with XXXX the utime of the
+ action. These files reside on the egw server, mostly in /tmp. So again
+ to read them you will need access to this server directory.
+ Off course this feature needs to be disabled in a production setting:
+ the file growth and the security issues of it demand it.
+
+
+@section secbugandtodo BuG and todo list
+
+  -see BUGs and TODOs in  @ref pageicalsrvbugandtodopage
+
+
+
+
+have fun
+
+
+JVL
+
+
+*/

phpgwapi/doc/icalsrv/IcalSrv-Overview.txt

@@ -0,0 +1,149 @@
+/*!  @mainpage Ical Service for Egroupware
+
+@NOTE: this text is not up to date
+@version 0.9.01
+@author jvl
+
+@section secinstall SHORT experimental Install How-To:
+
+ - Install the icalsrv package by either checking out the icalsrv module from cvs
+ or untarring some tarball icalsrv-vx.y.x.tgz of the package (when available).
+
+ - @note: The IcalSrv package depends on the availability of an
+ EgwIcal (>= 0.9.x) package. So if you dont have this already, be sure
+ to install that too.
+
+ - Take care that icalsrv.php is .../egroupware/icalsrv.php (and the
+ other files from the icalsrv package also in their appropiate places)
+
+- Append something like the following onto your apache httpd.conf part for
+egroupware (assuming that your standard egroupware root path is e.g in
+/var/www/egroupware and with a http alias 'egroupware' pointing to
+it):
+<PRE>
+ <Location /egroupware/icalsrv.php>
+    Script PUT /var/www/egroupware/icalsrv.php
+    AddHandler ical/ics .ics
+    Action ical/ics /var/www/egroupware/icalsrv.php
+    Order allow,deny
+    Allow from all
+ </Location>
+</PRE>
+
+- Restart apache (or other webserver) ( /etc/init.d/httpd restart )
+
+- Connect your ical client (e.g: Sunbird)
+	   with http://your.host.com/egroupware/icalsrv.php
+        
+- now you should need to authenticate (with your normal EGW login and password)
+  and when done you receive the calendar on doing a "reload remote calendars" or so.
+
+- using the "publish" calendar action you can write the (modified) calendar
+  from the sunbird client back to EGW
+
+
+@section secdeletions Deleting Calendars, events or todos
+
+deletion of the whole remote calendar is not supported see the @ref
+webcaldiscusspage webcal protocol discussion.
+
+Individual calendar events or todos cannot be deleted either by just
+deleting them on the client and then hoping that this propagates to
+Egroupware on publish. There are various reasons for why this is not
+implemented. 
+
+But, you can though delete items by simply renaming them to
+<code>X-DELETE</code>.  I you do so they will get deleted in Egw on
+publishing. When you later dowload ("reload"/"refresh") the remote
+calendar in your client you should notice that the event is gone..
+
+
+@section secicalsrvclients Clients for IcalSrv
+
+This is tested with egw1.2rc6 and clients:
+
+  * Korganizer (3.3.2,(read)  3.4.2, 3.5.0 (READ+WRITE))
+  * Mozilla calendar (2004040813-cal) (READ+WRITE)
+  * Evolution 2.2 (READ)
+
+For further use and experience with these clients see @ref
+pageicalsrvclients IcalSrvClients page.
+
+
+
+
+
+
+@section secdocumentation Documentation
+
+There is (somewhere) complete doxygen generated documentation for the
+IcalSrv package. Otherwise you can generate it yourself by using
+doxygen on the source filetree. Maybe you are just reading it now ...
+
+
+@section sectestandebug Testing and Debugging
+
+As IcalSrv is still a young and experimental new service for
+Egroupware, that must mediate between a multitude of clients, each
+with their own peculiarities and various internal applications of Egw,
+it is very likely that a lot of problems, deficiencies and bugs will
+appear. 
+
+Thus to get error feedback for it is a healthy thing. You should best
+do this --as with any egw application-- using the sourcforge.net
+buglist and the dedicated egroupware forums or mailinglist (see the
+egroupware wiki for more instructions on this).
+
+What to report? Well you should realize that IcalSrv is --currently--
+on it self just a rather simple http interface script, that relies for
+it connection to the egw backends heavily on the new (re) written
+EgwIcal package. This means that problems with in and export of
+iCalendar data will mostly have their source in that (i.e. EgwIcal)
+package! So in case of errors allways report info on that package and
+when debugging try the debug tools for that package.
+
+@subsection subsecdebugtools Debugging of IcalSrv.
+
+IcalSrv does not generate webpages, so to see any error or debug
+information you there a jsut three other places to look at:
+
++ If you have a really problematic error, IcalSrv will answer your http
+ request with a 403 error and --hopefully-- a short message. In some
+ clients (like Korganize) this is reported back via a popup with a
+ silly message that "exporting went wrong or access denied" or so, instead of displaying
+ this message it got together with the 403 error. Note: Sunbird does
+ display the message. Unfortunately at the moment this will be mostly
+ "VEVENTS import ERROR" or so..
+
++ The httpd errorlog file/stream. Most problematic errors are reported
+ to this file of the egw server. So this is indeed the best source for
+ debug info. But to read it, you need access to the
+ server and to this log file. So only egw administrators are likely
+ the only ones for who this can be of help.
+ 
++ The ical.log files and ical.exportxxxx plus ical.importxxxx
+ files. If you did install the icalsrv.php file with the variable
+ $logdir set to folder where the httpd is allowed to write, you will
+ get a detailed log in file ical.log of all uploads and downloads via
+ IcalSrv furhtermore for each of these the associated iCalendar data
+ will be logged in ical.exportXXXXXX files with XXXX the utime of the
+ action. These files reside on the egw server, mostly in /tmp. So again
+ to read them you will need access to this server directory.
+ Off course this feature needs to be disabled in a production setting:
+ the file growth and the security issues of it demand it.
+
+
+@section secbugandtodo BuG and todo list
+
+  -see BUGs and TODOs in  @ref pageicalsrvbugandtodopage
+
+
+
+
+have fun
+
+
+JVL
+
+
+*/