NAME

td —

TDcal configuration file

DESCRIPTION

The ~/.td file contains the configuration for the TDcal(7) calendar system.

The configuration file contains directives that configure parameters of TDcal as well as configuration of calendars.

Blank lines as well as lines starting with ‘#’ are ignored.

Configuration variables shown as ‘B’ for boolean values may be given any of the values: ‘false’, ‘off’, ‘no’, ‘0’, ‘true’, ‘on’, ‘yes’, ‘1’.

Configuration directives are:

adalrts [+-]hh:mm|off ...

adalerts [+-]hh:mm|off ...

adealerts [+-]hh:mm|off ...

Space or comma separated list of times for pop-up alerts for all-day events. Times must be in 24-hour format. Times between 12:00 and 23:59 and any times preceded by a ‘+’ are taken as the day before the event. Times between 00:00 and 11:59 and any times preceded by a ‘-’ are taken as the day of the event. The default is ‘off’. This can be given either as a global configuration or following a ‘cal’ directive, in which case it applies just to that calendar.

alerts [+-]N|off ...

Space or comma separated list of times in minutes relative to an event's start for pop-up alerts for an in-day event. Positive numbers are before to the event's start; negative numbers are after the event's start. The word ‘off’ turns off alerts. The default is ‘60 30 15 5 0’. This can be given as either a global configuration or following a ‘cal’ directive, in which case it applies just to that calendar.

cal name

This names and configures a calendar. Names may contain any characters including spaces.

charset character_set

For calendars loaded from .ics files, this provides the file's encoding, e.g., ‘eucJP’, ‘iso8859-1’, ‘koi8-r’, ‘utf-8’, etc. Default is ‘utf-8’. This is ignored when calendars are loaded from a remote server which should provide the character set as part of the download.

cli_id yadda_yadda_yadda_yadda

This must appear following a ‘oaprv’ directive. Specifies an OAuth ‘client_id’ for use with a service that requres OAuth authorization.

cli_sec yadda_yadda

This must appear following a ‘oaprv’ directive. Specifies an OAuth ‘client_secret’ for use with a service that requres OAuth authorization.

color #808080

colour #808080

Specifies what color to use when displaying the calendar events and pop-up alerts. Will be overridden if the server provides a value.

dspname name

This must appear following a ‘cal’ directive. Sets the display name of the calendar. Will be overridden if the server provides a value.

dsync N

Defines the number of minutes between tdd(1) daemon synchronization checks. Default is 15 minutes. Minimum value is 1 minute.

gsync B

Boolean flag which controls whether tdg(1) is invoked with its -S immediate synchronization flag when the user clicks on the tdt(1) systray icon. Default is ‘false’.

logfile filename

The name of the log file for local event additions/deletions and for server synchronizations. Default is ~/.td.log. A value of ‘-’ disables logging.

logsize N

The maximum size of the logfile in bytes. Default is 1000000.

lperiod N

The period in days for which td(1) flags -l, -L and -m will display forthcoming events. Default is 14 days.

oaprv service

Specifies an OAuth provider. See tdoauth(1). The service must be one of the ones listed on the tdoauth(1) manual page.

pass password

This must appear following a ‘cal’ directive. The password for access authorization on the remote server.

rdonly B

This must appear following a ‘cal’ directive. Boolean to mark the calendar as being read-only. It is set automatically for calendars of type ‘ical’ and when a read-only calendar is detected in a CalDAV calendar collection otherwise it defaults to ‘false’.

tbar B

titlebar B

Boolean to indicate whether the desktop environment's window manager provides window decorations that include a titlebar. Specifically, whether a titlebar appears on a gxmessage(1) or xmessage(1) notification window. The titlebar is used to display the time-to-go until the event's appointment time. The default is ‘true’. If set to ‘false’, the time-to-go is prepended to the notification text.

tddir directory

The name of the td calendar storage directory. Default is ~/.tdcals.

time24h B

Boolean flag to force all times to be displayed in 24-hour format, overriding the locale-specific time format. This affects displays of forthcoming events, lists of events in searches, the format of times used in the detailed event editor in tdg(1), and the format of the times on the 15-minute grid on the main tdg(1) display. The default is ‘false’.

type local|ical|caldav|caldav_cal

This must appear following a ‘cal’ directive but note that it is generally not needed as the type is determined automatically. Specifies the type of this calendar. If not present, the type is inferred from the configuration as follows. If no URL is configured, the calendar is type ‘local’. If the URL is a ‘file://’ file, the calendar type is ‘ical’. If the URL contains the string ‘.ics[/?]’ or ‘.ical[/?]’ the calendar type is ‘ical’. Else the calendar is type ‘caldav’. The type ‘caldav_cal’ refers to a single calendar within a CalDAV collection. This is set automatically for calendars discovered from CalDAV servers but it might be used when configuring other parameters for one CalDAV calendar individually.

tzone America/New_York

This must appear following a ‘cal’ directive. Specifies the timezone of the calendar. Will be overridden if the server provides a value.

updfreq N

This must appear following a ‘cal’ directive. Specifies the time in minutes between checks of calendar type Fetch servers. If not specified, checks will be done at any/every synchronization run. A good value is 1440 (daily) for calendars from public sources or even 10080 (weekly) for calendars that are not expected to change, such as national holiday calendars.

url URL

This must appear following a ‘cal’ directive. Specifies the URL of the remote calendar server. URLs can be of type ‘file://’, ‘http://’ or ‘https://’. (I.e., not ‘webdav:’ or ‘caldav:’)

For ical-type calendars, this will be the path that fetches the iCalendar data and will often contain ".ics" or ".ical" in the path.

For CalDAV-type calenadrs, this must be the path of the main CalDAV calendar collection for that service and not the principal, home set or individual calenadar URL. Examples:

Baïkal: ‘https://yourserver.example.com/baikal/dav.php/’
Fruux †: ‘https://dav.fruux.com/’
Google ‡: ‘https://apidata.googleusercontent.com/caldav/v2/’
nextCloud †: ‘https://yourserver.example.com/nextcloud/remote.php/dav/’
ownCloud †: ‘https://yourserver.example.com/owncloud/remote.php/dav/’
Radicale: ‘https://yourserver.example.com/radicale/’
Yahoo! † ‡: ‘https://caldav.calendar.yahoo.com/’

Note that this is not the URL for the principal or for the home-set for a specific calendar; TDcal will determine those automatically. Use the top-level URL for the CalDAV calendar collection. And note that, generally, the URL should not contain your username or password.

For CalDAV calendars, the URL may contain an embedded username and password in the form: ‘https://username:password@yourserver.example.com/blah/blahdav/’ Using embedded passwords is not recommended, however, because it is insecure as URLs are visible in transit and may also be logged, so passwords given like this may be exposed. Use of separate ‘user’ and ‘pass’ directives is strongly recommended instead.

† Many calendar services require that you log on to create an application-specific password for access via the CalDAV protocol. If this is needed, create one for your TDcal access and then use that password in your calendar configuration.

‡ Google requires the use of the OAuth authorization framework in order to access your private information on their service. To use this, add a calendar configuration containing the URL and your username to ~/.td configuration file and then run the tdoauth(1) utility. This will open your browser and request that you log on and authorize TDcal to access your calendar. Once you have done so, your OAuth access credentials will be stored.

‡ Yahoo! Calendar's CalDAV implementation has some significant unusual aspects:

URL percent-encoding is incorrectly done twice resulting in a calendar called ‘My Calendar’ being sent as .../My%2520Calendar/... instead of simply .../My%20Calendar/.... TDcal has work-around code to detect and correct for this problem in both calendar and event URLs.
Yahoo! Calendar also rejects events with repetition frequencies of ‘FREQ=HOURLY’ or smaller, returning a ‘500 Server Error’ when such events are uploaded. Repeating events only work with ‘FREQ=DAILY’ or larger.
Yahoo! Calendar also adds several iCalendar records to all events uploaded to the server. These additions mean that an entity tag for the new event is not immediately available on upload. The event must be redownloaded in order to obtain the changed version and its entity tag. This happens automatically for you, but it is an additional use of network bandwidth.

user username

This must appear following a ‘cal’ directive. The username for access authorization on the remote server.

wesplit B

Boolean flag to cause the weekend to be displayed split around the week. I.e., for weeks starting on Monday, instead of displaying the calendar as Monday-Sunday, the display is Sunday-Saturday. The default is ‘false’.

wkstart N

The number of the day on which the week starts. Monday=1, Sunday=7. The value of 0 is also accepted for Sunday. Default is 1. Used by the tdg(1) graphical user-interface when displaying the calendar. Note that the week numbers are also affected by the week start day.

To define parameters for individual calendars in a CalDAV collection, specify the calendar name as the CalDAV collection then a "/" character then the calendar name. The collection must be defined before the specific calendar in the configuration file. See the example below where all-day alerts are set for the ‘contact_birthdays’ calendar.

Because the .td configuration file contains passwords, it should be mode 0600.

EXAMPLE

Several calendars with European display of the week Monday-Sunday:

    # .td - configuration file for TDcal

    alerts	60 40 20 10 5 0
    tddir	~/.local/share/tdcal
    lperiod	7

    cal		Local
    color	#ebc807

    cal		MyNextCloud
    url		https://my.example.com/nextcloud/remote.php/dav/
    user	foo
    pass	mypassword

    cal		MyNextCloud/contact_birthdays
    adalrts	17:00 10:00

    oaprv	google
    cli_id	123456789012-yaddayaddayadda.apps.googleusercontent.com
    cli_sec	123yadda456yadda789yadda

    cal		MyGoogleCalendar
    url		https://apidata.googleusercontent.com/caldav/v2/
    user	myname@gmail.com

    cal		My Meetup Group
    url		https://www.meetup.com/My-Club-Name/events/ical/123456789/0123456789abcdef0123456789abcdef01234567/My+Club+Longname/
    updfreq	1440

    cal		Red Sox 2013
    color	#bc2e34
    url		http://mlb.mlb.com/soa/ical/schedule.ics?team_id=111&season=2013
    updfreq	1440

    cal		US Holidays
    color	#00e000
    url		https://www.thunderbird.net/media/caldata/USHolidays.ics
    updfreq	10080

This gives a default display of weeks as Monday-Friday followed by Saturday-Sunday weekend.

To display the same with a week display of Sunday-Saturday, add to the top of the file:

    wesplit	true

To display with a Sunday-Thursday week and Friday-Saturday weekend, add to the top:

    wkstart	7

For the same Sunday-Thursday week and Friday-Saturday weekend displayed as Saturday-Friday, add to the top both:

    wkstart	7
    wesplit	true

To display all event listings and also the daily grid in tdg(1) in 24-hour time even when your locale uses 12-hour am/pm notation, add to the top:

    time24h	true

Note that the week numbers change based on the week's start day which is determined by the wkstart and wesplit settings. Week 1 is defined as the week containing the first Thursday starting from your chosen display start day.

The downloaded iCalendar data for the US Holidays example, above, has no timezone information. This is so that it installs all-day events no matter which US timezone you are in. However, it also means that if you move to another timezone after installing the calendar and update your system timezone configuration, the holidays will then appear to span two days. It will automatically fix itself after the next update, but that means at your next configured poll and only then if the maintainers of the calendar have modified any events in the calendar. To fix without waiting, you can export and re-import the data:

    td -c "US Holidays" -e | td -c "US Holidays" -i -

STANDARDS

See TDcal(7).