Updated public website with much enhanced areas on configuration of clients.

docs/website/clients.php

@@ -1,96 +1,64 @@
 <?php
- $title = "Client Configuration";
- include("inc/page-header.php");
-?>
-<h1>Evolution</h1>
-<p>Novell Evolution is available in most Linux distributions.  The CalDAV support was supposedly written
-in a frenzy of hacking one day when the draft specification was at around revision 8.  As a result there
-was little in the way of a repository available to test against until recently.</p>
-<ol>
-<li><span class="prompt">Type:</span>CalDAV</li>
-<li><span class="prompt">Name:</span>Give the calendar a local name</li>
-<li><span class="prompt">URL:</span>caldav://server.domain.name/caldav.php/$username/</li>
-<li><span class="prompt">Use SSL:</span>if your server is using SSL you should check this, but there may be bugs in Evolution's handling of SSL.</li>
-<li><span class="prompt">Username:</span>$username</li>
-</ol>
-<p>If you have problems with Evolution, you will need to quit evolution, remove the cache file which will be in ~/.evolution/cache/calendar/ and
-restart.  If you still have problems try doing that, but killing evolution-data-server in addition.
-</p>
-<p>Sometimes evolution writes error messages into the cache file, so if you have ongoing problems you may want to
-take a look inside that.</p>
-<p>There are some quirks with Evolution's handling of CalDAV too, so perhaps take a look at the following
-bugs:</p>
-<ul>
-<li><a href="http://bugzilla.gnome.org/show_bug.cgi?id=355659">New appointments disappear for 1 minute, and then reappear</a></li>
-<li><a href="http://bugzilla.gnome.org/show_bug.cgi?id=354855">Support Response with Relative URLs</a></li>
-</ul>
-<p>Hopefully those will be fixed before too long...</p>
+  $title = "Client Configuration";
+  $two_panes = true;
+  include("inc/page-header.php");
 
-<h1>Sunbird / Lightning (Mozilla Calendar)</h1>
-<p>The Mozilla calendar project offers their calendar under two different names: <em>Sunbird</em> is a standalone calendar
-application, and <em>Lightning</em> is a Thunderbird extension.  The two are essentially the same, as far as RSCDS is
-concerned, and these instructions should work for either of them.</p>
-<ol>
-<li>Select "New Calendar" from the "File" menu.</li>
-<li>Choose "On the Network" (click "Next")</li>
-<li>Choose a format of "CalDAV" and enter a URL like: "http://calendar.example.net/caldav.php/username/" (click "Next")</li>
-<li>Give the calendar an appropriate display name, and choose a colour for events on this calendar. (click "Next")</li>
-<li>click "Finish"</li>
-</ol>
-<p>At version 0.3 the Mozilla calendar does not automatically refresh the calendar view, so if someone else has
-added a meeting you will have to manually refresh the view to see that.</p>
-<p>It is early days yet for the Mozilla calendar in it's current incarnation so no doubt there are other quirks
-with Mozilla's handling of CalDAV too, so perhaps take a look at their bugzilla.</p>
-<p>As at version 0.3, you should be aware of this <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=360076">bug with empty CalDAV calendars</a> which can be
-confusing.  Add your calendar, create an event and then re-start the program before saying that things
-are not working!</p>
+  $dir = "clients";
+  $clients = array();
+  $screenshots = array();
+  $icons = array();
+  $details = array();
+  if ( is_dir($dir)) {
+    if ( $dh = opendir($dir) ) {
+      while (($file = readdir($dh)) !== false ) {
+        if ( preg_match( '#^([^/]+)-([^/-]+)\.([^/.-]+[^~])$#', $file, $matches ) ) {
+          switch ( $matches[2] ) {
+            case 'details':
+              $details[$matches[1]] = $file;
+              $clients[] = $matches[1];
+              break;
 
-<h1>Mulberry</h1>
-<p>Mulberry is the most well-behaved of the applications I have been able to use.  It does have some
-bugs, however, and a particular annoyance around it's use of non-standard names for time zones.  Mulberry
-is the only client I have used so far which can issue a MKCALENDAR command or which will display a
-hierarchy of calendars from one configured URL.</p>
-<ol>
-<li>Select "Preferences" from the "File" menu.</li>
-<li>Choose the "Accounts" tab</li>
-<li>Select "New" from the "Account" drop-down and a "Create New Account" dialog will appear.</li>
-<li>Enter a name for the account, choose "CalDAV Calendar" for the type and click "OK"</li>
-<li>In the "Server" field enter the domain name of your CalDAV server, such as "calendar.example.net"</li>
-<li>In the "Authentication" pane of the "Accounts" tab, enter your username.</li>
-<li>In the "Options" pane of the "Accounts" tab, enter the path, which should be "/caldav.php/"</li>
-<li>"OK" the preferences dialog</li>
-<li>A list of the users and resources which you are allowed to access should appear. Some may contain calendars.</li>
-<li>If you don't already have a calendar for your own user, ensure your username is highlighted and choose "Create" from the "Calendar" menu.</li>
-<li>Once you have a calendar created, you need to <em>subscribe to it.  One way is to right-click on it and choose 'Subscribe'.</em></li>
-</ol>
+            case 'icon':          $icons[$matches[1]] = $file;            break;
+            case 'screenshot':    $screenshots[$matches[1]] = $file;      break;
 
-<p>Unfortunately Mulberry is not open-source, though it is free, so we must wait on the developer to fix
-the user interface niggles when he gets around to it.</p>
-<p>Note that Mulberry has a complex user interface.  When I wrote this I went back into Mulberry and initially thought that RSCDS had regressed
-somewhat and that these instructions didn't exactly work... :-)  It turned out that these instructions worked <em>just fine</em> when I followed
-them to the letter the next day.  Go figure.  I think I need to record some screenshots of this one...</p>
+            default:
+              break;
+          }
+        }
+      }
+      closedir($dh);
+    }
+  }
 
-<h1>Cross-client Interoperability Considerations</h1>
-<p>If you intend to have users accessing the Really Simple CalDAV Store with more than one client
-then you should attempt to structure the URLs which they use to access the system in the way
-that Mulberry does it.</p>
-<p>Basically, Mulberry breaks the URL into three parts:</p>
-<ul>
-<li>The host name</li>
-<li>The root path</li>
-<li>Calendar namespace</li>
-</ul>
-<p>The host name is, of course, up to you.  The 'root path' should be <code>/caldav.php/</code> and anything following that is the calendar namespace.</p>
-<p>Within the calendar namespace RSCDS uses the first element of the path as the user or resource name, so that a client connecting at the root path
-can see all of the (accessible) users and resources available to them (Mulberry displays this hierarchy) with any calendars below that.</p>
-<p>Effectively this means that in Evolution, Sunbird and Lightning you should really specify a calendar URL which is something like:</p>
-<pre>
-caldav://calendar.example.net/caldav.php/username/home/
-</pre>
-<p>Then, when more calendar client software sees it as useful to be able to browse that hierarchy, you won't be up for any heavy database manipulation.</p>
-<p>I may well enforce this standard in some way before release 1.0, as well as auto-creating the <code>collection</code> records when Evolution, Lightning
-or Sunbird attempt to store to a non-existent collection.</p>
+  $client_page = "Interoperability";
+  if ( isset( $_GET['client'] ) ) {
+    if ( isset( $details[$_GET['client']] ) ) {
+      $client_page = $_GET['client'];
+    }
+  }
 
-<?php
- include("inc/page-footer.php");
+  $style = ($client_page == "Interoperability" ? ' class="selected"' : '' );
+  printf( '<p%s><a href="clients.php?client=Interoperability">Interoperability</a></p>', $style );
+
+  sort($clients);
+  foreach( $clients AS $k => $v ) {
+    if ( $v == "Interoperability" ) continue;
+    $style = (strcmp($client_page,$v) == 0 ? ' class="selected"' : '' );
+    printf( '<p%s><a href="clients.php?client=%s">', $style, urlencode($v) );
+    if ( isset($icons[$v]) ) {
+      printf( '<img src="clients/%s"><br />', urlencode($icons[$v]) );
+    }
+    echo "$v</a></p>\n";
+  }
+
+  include("inc/page-middle.php");
+
+  include("clients/".$details[$client_page]);
+
+  if ( isset($screenshots[$client_page]) ) {
+    printf( '</div><p><img src="clients/%s"></p>', urlencode($screenshots[$client_page]) );
+    $tags_to_be_closed = "</div>\n";
+  }
+
+  include("inc/page-footer.php");
 ?>

docs/website/clients/Chandler-details.php

@@ -0,0 +1,24 @@
+<h1>Chandler</h1>
+<p>The <a href="http://www.osafoundation.org/">Open Source Applications Foundation</a> are developing <a href="http://cosmo.osafoundation.org/">Cosmo</a>, which is a CalDAV server
+written in Java and <a href="http://chandler.osafoundation.org/">Chandler</a>, which is a CalDAV capable mail and calendaring application
+written in Python.</p>
+<p>Basic setup is as follows:</p>
+<ol>
+<li>Select "Subscribe" from the "Collection" menu.</li>
+<li>Enter a URL like: "http://calendar.example.net/caldav.php/username/home/" (click "Subscribe") <img src="clients/Chandler-dialog1.png" /> <br /> &nbsp;</li>
+<li>You will then be prompted for a username/password with in an expanded dialog.  Enter these and click "Subscribe" again. <img src="clients/Chandler-dialog2.png" /> <br /> &nbsp;</li>
+<li>You should now have a new calendar showing.</li>
+</ol>
+<h3>Caveats</h3>
+<p><img align="right" src="clients/Chandler-dialog3.png" />At version 0.7alpha3 the calendar is subscribed and displayed, but the 'displayname' property
+which the server sends is not used and the calendar is displayed with a blank name.  Double-click
+on your new calendar and enter a name in the space available. </p>
+
+<p>Chandler describes itself as 'an experimentally usable calendar', and it certainly feels that
+way.  It also will only synchronise to the CalDAV server either when you press the "Sync"
+button or with a default frequency of hourly.  This is quite different to the other clients I
+have used which all aggressively push new and changed items to the server as soon as possible,
+but which may be lazy about fetching updates.</p>
+
+<p>Operation with RSCDS is not yet perfect but basic operation is satisfactory.  I will be
+concentrating on making RSCDS interoperate with Chandler over coming releases.</p>

docs/website/clients/Evolution-details.php

@@ -0,0 +1,23 @@
+<h1>Evolution</h1>
+<p><a href="http://www.gnome.org/projects/evolution/">Evolution</a> is available in most Linux distributions.  The CalDAV support was supposedly written
+in a frenzy of hacking one day when the draft specification was at around revision 8.  As a result there
+was little in the way of a repository available to test against until recently.</p>
+
+<ol>
+<li>Select "File" then "New" then "Calendar" from the menus.</li>
+<li>Choose a type of "CalDAV", enter a name, and a URL such as <code>caldav://server.domain.name/caldav.php/username/home/</code>, enter your user name for RSCDS and click "OK".<img src="clients/Evolution-dialog1.png" /> <br />&nbsp;</li>
+<li>You should now be prompted for a password for that username.  Enter the password and your calendar should now show.</li>
+</ol>
+<p>If you have problems with Evolution, you will need to quit evolution, remove the cache file which will be in ~/.evolution/cache/calendar/ and
+restart.  If you still have problems try doing that, but killing evolution-data-server in addition.
+</p>
+<p>Sometimes evolution writes error messages into the cache file, so if you have ongoing problems you may want to
+take a look inside that.</p>
+<p>There are some quirks with Evolution's handling of CalDAV too, so perhaps take a look at the following
+bugs:</p>
+<ul>
+<li><a href="http://bugzilla.gnome.org/show_bug.cgi?id=355659">New appointments disappear for 1 minute, and then reappear</a></li>
+<li><a href="http://bugzilla.gnome.org/show_bug.cgi?id=354855">Support Response with Relative URLs</a></li>
+</ul>
+<p>There may also be bugs in Evolution's handling of SSL with CalDAV - I couldn't get it to work reliably.</p>
+<p>Hopefully those will be fixed before too long...</p>

docs/website/clients/Interoperability-details.php

@@ -0,0 +1,20 @@
+<h1>Cross-client Interoperability Considerations</h1>
+<p>If you intend to have users accessing the Really Simple CalDAV Store with more than one client
+then you should attempt to structure the URLs which they use to access the system in the way
+that Mulberry does it.</p>
+<p>Basically, Mulberry breaks the URL into three parts:</p>
+<ul>
+<li>The host name</li>
+<li>The root path</li>
+<li>Calendar namespace</li>
+</ul>
+<p>The host name is, of course, up to you.  The 'root path' should be <code>/caldav.php/</code> and anything following that is the calendar namespace.</p>
+<p>Within the calendar namespace RSCDS uses the first element of the path as the user or resource name, so that a client connecting at the root path
+can see all of the (accessible) users and resources available to them (Mulberry displays this hierarchy) with any calendars below that.</p>
+<p>Effectively this means that in Evolution, Sunbird and Lightning you should really specify a calendar URL which is something like:</p>
+<pre>
+caldav://calendar.example.net/caldav.php/username/home/
+</pre>
+<p>Then, when more calendar client software sees it as useful to be able to browse that hierarchy, you won't be up for any heavy database manipulation.</p>
+<p>I may well enforce this standard in some way before release 1.0, as well as auto-creating the <code>collection</code> records when Evolution, Lightning
+or Sunbird attempt to store to a non-existent collection.</p>

docs/website/clients/Mozilla-details.php

@@ -0,0 +1,21 @@
+<h1>Sunbird / Lightning (Mozilla Calendar)</h1>
+<p>The <a href="http://www.mozilla.org/projects/calendar/">Mozilla Calendar</a> project offers their calendar under two different names:
+ <em><a href="http://www.mozilla.org/projects/calendar/sunbird/">Sunbird</a></em> is a standalone calendar
+ application, and <em><a href="http://www.mozilla.org/projects/calendar/lightning/">Lightning</a></em> is a Thunderbird extension.
+ The two are essentially the same, as far as RSCDS is
+ concerned, and these instructions should work for either of them.</p>
+<ol>
+<li>Select "New Calendar" from the "File" menu.</li>
+<li>Choose "On the Network" (click "Next")<img src="clients/Mozilla-dialog1.png" /> <br /> &nbsp;</li>
+<li>Choose a format of "CalDAV" and enter a URL like: "http://calendar.example.net/caldav.php/username/" (click "Next")<img src="clients/Mozilla-dialog2.png" /> <br /> &nbsp;</li>
+<li>Give the calendar an appropriate display name, and choose a colour for events on this calendar. (click "Next")<img src="clients/Mozilla-dialog3.png" /> <br /> &nbsp;</li>
+<li>click "Finish"</li>
+</ol>
+<h2>Caveats</h2>
+<p>At version 0.3 the Mozilla calendar does not automatically refresh the calendar view, so if someone else has
+added a meeting you will have to manually refresh the view to see that.</p>
+<p>It is early days yet for the Mozilla calendar in it's current incarnation so no doubt there are other quirks
+with Mozilla's handling of CalDAV too, so perhaps take a look at their bugzilla.</p>
+<p>As at version 0.3, you should be aware of this <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=360076">bug with empty CalDAV calendars</a> which can be
+confusing.  Add your calendar, create an event and then re-start the program before saying that things
+are not working!</p>

docs/website/clients/Mulberry-details.php

@@ -0,0 +1,29 @@
+<h1>Mulberry</h1>
+<p><a href="http://www.mulberrymail.com/">Mulberry</a> is the most well-behaved of the applications I have been
+able to use.  It does have some bugs, however, and a particular annoyance around it's use of non-standard names
+for time zones.  Mulberry is the only client I have used so far which can issue a MKCALENDAR command or which
+will display a hierarchy of calendars from a single configured URL, dicovering the calendars through recursive
+PROPFIND requests.</p>
+
+<ol>
+<li>Select "Preferences" from the "File" menu.</li>
+<li>Choose the "Accounts" tab</li>
+<li>Select "New" from the "Account" drop-down and a "Create New Account" dialog will appear.</li>
+<li>Enter a name for the account, choose "CalDAV Calendar" for the type and click "OK"</li>
+<li>In the "Server" field enter the domain name of your CalDAV server, such as "calendar.example.net"</li>
+<li>In the "Authentication" pane of the "Accounts" tab, enter your username.<img src="clients/Mulberry-dialog1.png" /> <br /> &nbsp;</li>
+<li>In the "Options" pane of the "Accounts" tab, enter the path, which should be "/caldav.php/"<img src="clients/Mulberry-dialog2.png" /> <br /> &nbsp;</li>
+<li>"OK" the preferences dialog</li>
+<li>A list of the users and resources which you are allowed to access should appear. Some may contain calendars.</li>
+<li>If you don't already have a calendar for your own user, ensure your username is highlighted and choose "Create" from the "Calendar" menu.</li>
+<li>Once you have a calendar created, you need to <em>subscribe to it.  One way is to right-click on it and choose 'Subscribe'.</em></li>
+</ol>
+
+<h3>Caveats</h3>
+<p>Unfortunately Mulberry is not (yet) open-source, though it is free, so we must wait on the developer to fix
+the user interface niggles when he gets around to it.</p>
+<p>Note that Mulberry has a complex user interface.  When I wrote this I went back into Mulberry and initially
+thought that RSCDS had regressed somewhat and that these instructions didn't exactly work... :-)  It turned out
+that these instructions worked <em>just fine</em> when I followed them to the letter the next day.  Go figure.
+I think I need to record some screenshots of this one...</p>
+

docs/website/inc/page-footer.php

@@ -1,4 +1,8 @@
-</div>
+<?php
+
+echo $tags_to_be_closed;
+
+?>
 
 <div id="footer">
 <br />

docs/website/inc/page-header.php

@@ -31,4 +31,11 @@ else {
 </div>
 </div>
 <div id="pageContent">
+<?php
+  $tags_to_be_closed = "</div>\n";
+  if ( $two_panes ) {
+    $tags_to_be_closed .= $tags_to_be_closed;
+    echo '<div id="leftSide">';
+  }
+?>
 <hr />

docs/website/inc/page-middle.php

@@ -0,0 +1,3 @@
+</div>
+<div id="rightSide">
+<hr />

docs/website/style.css

@@ -42,6 +42,7 @@ hr {
   font-size: 80%;
   padding-top: 64px;
   padding-right: 5px;
+  display:block;
   }
 
 .hlink:link {
@@ -122,6 +123,7 @@ li {
   margin-left: 2em;
   font-family: helvetica, arial, sans-serif;
   font-size: 90%;
+  margin-bottom: 5px;
   }
 
 code {
@@ -150,10 +152,9 @@ pre {
   float: left;
   color: #FFFFFF;
   padding-left: 100px;
-  margin-top: 10px;
+  margin-top: 1px;
   font-family: helvetica, arial, sans-serif;
-  font-size: 24pt;
-  font-size: 200%;
+  font-size: 190%;
   }
 
 #subTitle {
@@ -163,8 +164,8 @@ pre {
   padding-left: 102px;
   font-family: helvetica, arial, sans-serif;
   font-size: 8pt;
-  font-size: 80%;
-  }
+  font-size: 75%;
+}
 
 .right {
   float: right;
@@ -217,3 +218,35 @@ pre {
   width: 4em;
   }
 
+#leftSide {
+  width: 170px;
+  float: left;
+}
+
+#leftSide p {
+  text-align: center;
+  margin-bottom: 1em;
+  padding:0.3em 0;
+  font-weight: bold;
+  background-color: #d2d2d2;
+}
+
+#leftSide p.selected {
+  background-color: #bb1f1f;
+  color: white;
+}
+
+#leftSide img {
+  border: none;
+}
+
+#leftSide a {
+  text-decoration: none;
+  color: inherit;
+}
+
+#rightSide {
+  width: 530px;
+  float: right;
+}
+

rscds.webprj

@@ -147,5 +147,12 @@
     <item url="po/fr_FR.po" uploadstatus="1" />
     <item url="inc/other_translated_strings.php" uploadstatus="1" />
     <item url="docs/website/administration.php" uploadstatus="1" />
+    <item url="docs/website/inc/page-middle.php" />
+    <item url="docs/website/clients/" />
+    <item url="docs/website/clients/Evolution-details.php" />
+    <item url="docs/website/clients/Mozilla-details.php" />
+    <item url="docs/website/clients/Mulberry-details.php" />
+    <item url="docs/website/clients/Interoperability-details.php" />
+    <item url="docs/website/clients/Chandler-details.php" />
   </project>
 </webproject>