| TDcal(7) | FreeBSD Miscellaneous Information Manual | TDcal(7) |
TDcal —
TDcal is a personal calendar management system.
TDcal supports the following features:
TDcal uses RFC5545-compliant iCalendar
calendar and event files for maximum interoperability with other calendar
tools. There is a command-line client, td(1), a graphical
user interface (GUI) client, tdg(1), a systray icon,
tdt(1), and a daemon, tdd(1), that
provides forthcoming-event notifications and that periodically synchronizes
local calendars with remote servers.
TDcal supports multiple calendars which
can each be one of several types:
All calendar data is downloaded and stored locally so that you have full access to your calendars while offline; changes are saved and synced back to servers when you are next online.
Operational parameters can be configured in the configuration file, see td(5), which is also used to configure calendars.
The TDcal tools have been designed with a
global audience in mind. Calendars can be displayed with any week start day
and with the weekend either at the end of the week or wrapped around the
week. Dates and times are formatted according to locale settings although
the use of 24-hour time can be forced if desired. Events are stored
internally in UTC so that, when travelling to other time zones, the event
times always show at the correct local time. Full NLS support is included so
that GUI messages as well as pop-up event reminders are displayed in the
user's preferred language.
All configuration information as well as all calendar data and internal caching data are stored in text files and can easily be examined and/or edited by the user.
TDcal is lightweight in that it is not
integrated as part of a larger productivity suite or desktop environment. It
is implemented as a set of Perl scripts and libraries. It can be installed
and used without the overhead of large numbers of external libraries or
other tools. Nevertheless, TDcal is very powerful
and integrates well with tools such as email by virtue of its calenadar
import and export features which allow calendar appointments shared by email
from other users to be added to your calendar.
TDcal has been designed to be fast and
efficient. Even with large calendars containing decades worth (many
thousands) of appointment events, listings for what's coming next are
generated very quickly with negligible CPU load or performance impact.
TDcal minimizes network transfers by means of limits
on synchronization frequency and by use of calendar and event change tags to
avoid re-transferring things that have not changed.
Institutions that publish a calendar very often make use of this. Examples are services providing national holiday listings and also those providing sports, theatre and opera schedules and local meeting groups.
TDcal makes an initial copy of such
calendars and then periodically checks back to see if the calendar has been
updated and, if so, fetches a new copy. This ensures that your local view is
up-to-date even when schedules change.
Calendars read from a file or fetched from a remote server are read-only and events cannot be edited nor new events added.
A user's remote CalDAV account may store multiple calendars.
TDcal automatically discovers calendars on the
server and synchronizes all calendars to the local device.
TDcal also automatically detects when calendars are
deleted from a server and deletes them locally too. Some CalDAV servers
include calendars created from external data such as calendars of contacts'
birthdays created from address books also stored on the server.
TDcal detects these and includes them as read-only
calendars.
CalDAV allows a calendar to be accessed from multiple devices.
Events added to the calendar on any device are synchronized with the server
and then synchronized with other devices sharing the same calendar. Each
device has its own copy of the entire calendar so that it can operate
normally while offline. Events added in TDcal to a
calendar while offline are stored and synchronized with the server later
when the device is online again.
If the same event is changed on multiple devices while all are offline, the first device to come online will synchronize its change with the server. This change will then be synchronized with other devices as they come online, and may override any local change made to the same event on those devices.
TDcal supports the use of the OAuth
authorization framework for use with services that require it.
TDcal is tested and works with many CalDAV
servers. Configuration examples for popular ones are given in the
td(5) configuration file manual page.
TDcal has a system tray icon provided by the
tdt(1) program. It displays an icon for today's calendar
date as well as a summary of forthcoming calendar events. When clicked, the
tdg(1) graphical user interface is opened.
TDcal has an alert and synchronization daemon,
tdd(1). Event alerts are displayed in pop-up windows on the
screen or as command-line messages if no pop-ups are possible.
Note that TDcal maintains but does not use
the so-called ‘alarm’ information that
may be configured in an iCalendar event. Any such information in events is
ignored by tdd(1) but the information is retained and will
be included if the event is exported and it will be resent to the server
when the event is updated. TDcal instead allows the
user to configure an alert schedule that suits the user's own needs. By
default, alerts are displayed at 60, 30, 15, 5 and 0 minutes before an
event. This default schedule can be overridden in the configuration file
either for all calendars or on a per-calendar basis.
Events created by TDcal will contain
iCalendar alarms corresponding to the configured alert schedule. Changes to
an event summary text are reflected into stored alarm information.
TDcal supports RFC5545 event repetition using
‘RRULE’,
‘RDATE’ and
‘EXDATE’. specifiers. It should be noted
that the deprecated ‘EXRULE’ exclusion
rule is also recognised in existing events but cannot be added to new events.
Simple repetition can be specified with a basic repetition rule such as
‘FREQ:WEEKLY’ or
‘FREQ:MONTHLY;BYDAY=2WE’ which means
monthly on the 2nd Wednesday of the month. More complex repetitions can be
created by combining BYxyz repetition specifiers, adding specific repetition
and exclusion dates, and set position specifiers.
The repetition syntax is the same as specified in RFC5545.
Repetition details can be entered directly using the td(1)
command-line interface and they can be edited into events using the
‘Alt-R’ repetition editor of the
tdg(1) graphical user interface.
It should be noted that TDcal supports the
full RFC5545 repetition syntax. Many other calendar applications and mobile
apps, however, do not support the full syntax. It is therefore possible to
write complex repetition rules that display as intended in
TDcal but that do not display correctly (or even at
all) in other apps.
TDcal uses the following files:
TDcal tools.
TDcal. Note
that event start and end times in this .cache file
are in the UTC timezone.
TDcal synchronizes with the
server so that latest server values are available.
ctag’ of the last modification to
this calendar on the server. This is used to determine the time for the
next re-fetch of the calendar.
put’ or
‘delete’ possibly followed by the
event's ‘href’ which indicates how
the change is to be sent. These queue files are removed when
TDcal next synchronizes with the server.
TDcal stores all calendar event
data as text files in the directory hierarchy shown. The top-level directory
is created mode 0700 so that events are private. The use of text files in a
directory hierarchy is a deliberate design choice to allow for easy
manipulation of data by poking around under the hood.
If you end up doing this, be aware that for any change to calendar event data, several things must be done:
It is not recommended to make such changes by hand. Events can be changed, moved, deleted, etc using the td(1) command-line interface, which uses the TDcal(3) libraries to take care of all of these things while also doing appropriate locking to make sure that other running processes don't also make updates at the same time. If changes need to be made that are not easily done using td(1), better would be to write a new tool that uses the TDcal(3) library to do the job. Examples of some simple tools can be found in the src/tools directory in the source code.
TDcal was influenced by the design of Sanjay Ghemawat's
ical(1) calendar tool (not related to Apple's iCal tool).
The author of TDcal was a happy user of
ical(1) for several decades before eventually needing a tool
that supported network synchronization. The look and feel of the graphical
user-interface as well as the default alarm schedule and the "No more
alerts" button were all borrowed from ical(1). Thank
you Sanjay Ghemawat for a tool that lasted a good couple of decades.
The -x flag that eXplains each utility's
usage as well as the idea for the .olog,
.oolog etc extending file names for old logs and the
name of the internal upd() function that produces
them comes from David Tilbrook's
‘DTree’.
TDcal is compliant with the RFC5545 iCalendar
specification.
TDcal supports CalDAV synchronization
according to RFC4791.
TDcal supports access authorization using
both basic username/password and according to the RFC6749 OAuth 2.0
authorization framework.
| July 22, 2013 | FreeBSD 13.1-RELEASE-p3 |