|TDcal(7)||FreeBSD Miscellaneous Information Manual||TDcal(7)|
TDcalis 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.
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
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.
TDcalhas 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.
TDcalhas 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.
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.
TDcalsupports RFC5545 event repetition using ‘
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.
TDcaluses the following files:
TDcal. Note that event start and end times in this .cache file are in the UTC timezone.
TDcalsynchronizes 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
TDcalnext synchronizes with the server.
TDcalstores 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.
TDcalwas influenced by the design of Sanjay Ghemawat's ical(1) calendar tool (not related to Apple's iCal tool). The author of
TDcalwas 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 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
TDcalis 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
|July 22, 2013||FreeBSD 13.1-RELEASE|