.\" Man page generated from reStructuredText.
.
.TH "KHAL" "1" "May 11, 2021" "0.10.3" "khal"
.SH NAME
khal \- khal Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
Khal is a calendar program for the terminal for viewing, adding and editing
events and calendars. Khal is build on the iCalendar and vdir (allowing the
use of \fBvdirsyncer(1)\fP for CalDAV compatibility) standards.
.SH USAGE
.sp
Khal offers a set of commands, most importantly \fBlist\fP,
\fBcalendar\fP, \fBinteractive\fP, \fBnew\fP,
\fBprintcalendars\fP, \fBprintformats\fP, and \fBsearch\fP\&. See
below for a description of what every command does. \fBkhal\fP does
currently not support any default command, i.e., run a command, even though none
has been specified. This is intentional.
.SS Options
.sp
\fBkhal\fP (without any commands) has some options to print some
information about \fBkhal\fP:
.INDENT 0.0
.TP
.B \-\-version
Prints khal\(aqs version number and exits
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Prints a summary of khal\(aqs options and commands and then exits
.UNINDENT
.sp
Several options are common to almost all of \fBkhal\fP\(aqs commands
(exceptions are described below):
.INDENT 0.0
.TP
.B \-v, \-\-verbosity LVL
Configure verbosity (e.g. print debugging information), \fILVL\fP needs to
be one of CRITICAL, ERROR, WARNING, INFO, or DEBUG.
.UNINDENT
.INDENT 0.0
.TP
.B \-l, \-\-logfile LOFILE
Use logfile \fILOGFILE\fP for logging, default is logging to stdout.
.UNINDENT
.INDENT 0.0
.TP
.B \-c CONFIGFILE
Use an alternate configuration file.
.UNINDENT
.INDENT 0.0
.TP
.B \-a CALENDAR
Specify a calendar to use (which must be configured in the configuration
file), can be used several times. Calendars not specified will be
disregarded for this run.
.UNINDENT
.INDENT 0.0
.TP
.B \-d CALENDAR
Specify a calendar which will be disregarded for this run, can be used
several times.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-color/\-\-no\-color
\fBkhal\fP will detect if standard output is not a tty, e.g., you
redirect khal\(aqs output into a file, and if so remove all
highlighting/coloring from its output. Use \fB\-\-color\fP if you want
to force highlighting/coloring and \fB\-\-no\-color\fP if you want
coloring always removed.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-format FORMAT
For all of khal\(aqs commands that print events, the formatting of that event
can be specified with this option.  \fBFORMAT\fP is a template
string, in which identifiers delimited by curly braces (\fI{}\fP) will be
expanded to an event\(aqs properties.  \fBFORMAT\fP supports all formatting
options offered by python\(aqs \fI\%str.format()\fP <\fBhttps://docs.python.org/3/library/string.html#formatstrings\fP> (as it is used internally).
The available template options are:
.INDENT 7.0
.TP
.B title
The title of the event.
.TP
.B description
The description of the event.
.TP
.B description\-separator
A separator: " :: " that appears when there is a description.
.TP
.B uid
The UID of the event.
.TP
.B start
The start datetime in datetimeformat.
.TP
.B start\-long
The start datetime in longdatetimeformat.
.TP
.B start\-date
The start date in dateformat.
.TP
.B start\-date\-long
The start date in longdateformat.
.TP
.B start\-time
The start time in timeformat.
.TP
.B end
The end datetime in datetimeformat.
.TP
.B end\-long
The end datetime in longdatetimeformat.
.TP
.B end\-date
The end date in dateformat.
.TP
.B end\-date\-long
The end date in longdateformat.
.TP
.B end\-time
The end time in timeformat.
.TP
.B repeat\-symbol
A repeating symbol (loop arrow) if the event is repeating.
.TP
.B location
The event location.
.TP
.B calendar
The calendar name.
.TP
.B calendar\-color
Changes the output color to the calendar\(aqs color.
.TP
.B start\-style
The start time in timeformat OR an appropriate symbol.
.TP
.B to\-style
A hyphen "\-" or nothing such that it appropriately fits between
start\-style and end\-style.
.TP
.B end\-style
The end time in timeformat OR an appropriate symbol.
.TP
.B start\-end\-time\-style
A concatenation of start\-style, to\-style, and end\-style OR an
appropriate symbol.
.TP
.B end\-necessary
For an allday event this is an empty string unless the end date and
start date are different. For a non\-allday event this will show the
time or the datetime if the event start and end date are different.
.TP
.B end\-necessary\-long
Same as end\-necessary but uses datelong and datetimelong.
.TP
.B status
The status of the event (if this event has one), something like
\fICONFIRMED\fP or \fICANCELLED\fP\&.
.TP
.B cancelled
The string \fICANCELLED\fP (plus one blank) if the event\(aqs status is
cancelled, otherwise nothing.
.TP
.B organizer
The organizer of the event. If the format has CN then it returns "CN (email)"
if CN does not exist it returns just the email string. Example:
ORGANIZER;CN=Name Surname:mailto:name@mail.com
returns
Name Surname (name@mail.com)
and if it has no CN attribute it returns the last element after the colon:
ORGANIZER;SENT\-BY="mailto:toemail@mail.com":mailto:name@mail.com
returns
name@mail.com
.TP
.B url
The URL embedded in the event, otherwise nothing.
.UNINDENT
.sp
By default, all\-day events have no times. To see a start and end time anyway simply
add \fI\-full\fP to the end of any template with start/end, for instance
\fIstart\-time\fP becomes \fIstart\-time\-full\fP and will always show start and end times (instead
of being empty for all\-day events).
.sp
In addition, there are colors: \fIblack\fP, \fIred\fP, \fIgreen\fP, \fIyellow\fP, \fIblue\fP,
\fImagenta\fP, \fIcyan\fP, \fIwhite\fP (and their bold versions: \fIred\-bold\fP, etc.). There
is also \fIreset\fP, which clears the styling, and \fIbold\fP, which is the normal
bold.
.sp
A few control codes are exposed.  You can access newline (\fInl\fP), \(aqtab\(aq, and \(aqbell\(aq.
Control codes, such as \fInl\fP, are best used with \fI\-\-list\fP mode.
.sp
Below is an example command which prints the title and description of all events today.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
khal list \-\-format "{title} {description}"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-day\-format DAYFORMAT
works similar to \fI\%\-\-format\fP, but for day headings. It only has a few
options (in addition to all the color options):
.INDENT 7.0
.TP
.B date
The date in dateformat.
.TP
.B date\-long
The date in longdateformat.
.TP
.B name
The date\(aqs name (\fIMonday\fP, \fITuesday\fP,…) or \fItoday\fP or \fItomorrow\fP\&.
.UNINDENT
.sp
If the \fI\-\-day\-format\fP is passed an empty string then it will not print the
day headers (for an empty line pass in a whitespace character).
.UNINDENT
.SS dates
.sp
Almost everywhere khal accepts dates, khal should recognize relative date names
like \fItoday\fP, \fItomorrow\fP and the names of the days of the week (also in
three letters abbreviated form). Week day names get interpreted as the date of
the next occurrence of a day with that name. The name of the current day gets
interpreted as that date \fInext\fP week (i.e. seven days from now).
.sp
If a short datetime format is used (no year is given), khal will interpret the
date to be in the future. The inferred it might be in the next year if the given
date has already passed in the current year.
.SS Commands
.SS list
.sp
shows all events scheduled for a given date (or datetime) range, with custom
formatting:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
khal list [\-a CALENDAR ... | \-d CALENDAR ...] [\-\-format FORMAT]
[\-\-day\-format DAYFORMAT] [\-\-once] [\-\-notstarted] [START [END | DELTA] ]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
START and END can both be given as dates, datetimes or times (it is assumed
today is meant in the case of only a given time) in the formats configured in
the configuration file.  If END is not given, midnight of the start date is
assumed. Today is used for START if it is not explicitly given.  If DELTA, a
(date)time range in the format \fII{m,h,d}\fP, where \fII\fP is an integer and \fIm\fP means
minutes, \fIh\fP means hours, and \fId\fP means days, is given, END is assumed to be
START + DELTA.  A value of \fIeod\fP is also accepted as DELTA and means the end of
day of the start date. In addition, the DELTA \fIweek\fP may be used to specify that
the daterange should actually be the week containing the START.
.sp
The \fI\-\-once\fP option only allows events to appear once even if they are on
multiple days. With the \fI\-\-notstarted\fP option only events are shown that start
after \fISTART\fP\&.
.SS at
.sp
shows all events scheduled for a given datetime. \fBkhal at\fP should be supplied
with a date and time, a time (the date is then assumed to be today) or the
string \fInow\fP\&. \fBat\fP defaults to \fInow\fP\&. The \fBat\fP command works just like the
\fBlist\fP command, except it has an implicit end time of zero minutes after the
start.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
khal at [\-a CALENDAR ... | \-d CALENDAR ...] [\-\-format FORMAT]
[\-\-notstarted] [[START DATE] TIME | now]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS calendar
.sp
shows a calendar (similar to \fBcal(1)\fP) and list. \fBkhal calendar\fP
should understand the following syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
khal calendar [\-a CALENDAR ... | \-d CALENDAR ...] [START DATETIME]
[END DATETIME]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Date selection works exactly as for \fBkhal list\fP\&. The displayed calendar
contains three consecutive months, where the first month is the month
containing the first given date. If today is included, it is highlighted.
Have a look at \fBkhal list\fP for a description of the options.
.SS configure
.sp
will help users creating an initial configuration file. \fBconfigure\fP will
refuse to run if there already is a configuration file.
.SS import
.sp
lets the user import \fB\&.ics\fP files with the following syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
khal import [\-a CALENDAR] [\-\-batch] [\-\-random\-uid|\-r] ICSFILE
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If an event with the same UID is already present in the (implicitly)
selected calendar \fBkhal import\fP will ask before updating (i.e. overwriting)
that old event with the imported one, unless \-\-batch is given, than it will
always update. If this behaviour is not desired, use the \fI\-\-random\-uid\fP flag to
generate a new, random UID.  If no calendar is specified (and not \fI\-\-batch\fP),
you will be asked to choose a calendar. You can either enter the number printed
behind each calendar\(aqs name or any unique prefix of a calendar\(aqs name.
.SS interactive
.sp
invokes the interactive version of khal, can also be invoked by calling
\fBikhal\fP\&. While ikhal can be used entirely with the keyboard, some
elements respond if clicked on with a mouse (mostly by being selected).
.sp
When the calendar on the left is in focus, you can
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
move through the calendar (default keybindings are the arrow keys, \fBspace\fP and
\fBbackspace\fP, those keybindings are configurable in the config file)
.IP \(bu 2
focus on the right column by pressing \fBtab\fP or \fBenter\fP
.IP \(bu 2
re\-focus on the current date, default keybinding \fBt\fP as in today
.IP \(bu 2
marking a date range, default keybinding \fBv\fP, as in visual, think visual
mode in Vim, pressing \fBesc\fP escapes this visual mode
.IP \(bu 2
if in visual mode, you can select the other end of the currently marked
range, default keybinding \fBo\fP as in other (again as in Vim)
.IP \(bu 2
create a new event on the currently focused day (or date range if a range is
selected), default keybinding \fBn\fP as in new
.IP \(bu 2
search for events, default keybinding \fB/\fP, a pop\-up will ask for your
search term
.UNINDENT
.UNINDENT
.UNINDENT
.sp
When an event list is in focus, you can
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
view an event\(aqs details with pressing \fBenter\fP (or \fBtab\fP) and edit it with pressing
\fBenter\fP (or \fBtab\fP) again (if \fB[default] event_view_always_visible\fP is set to
True, the event in focus will always be shown in detail)
.IP \(bu 2
toggle an event\(aqs deletion status, default keybinding \fBd\fP as in delete,
events marked for deletion will appear with a \fBD\fP in front and will be
deleted when khal exits.
.IP \(bu 2
duplicate the selected event, default keybinding \fBp\fP as in duplicate
(d was already taken)
.IP \(bu 2
export the selected event, default keybinding \fBe\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
In the event editor, you can
.INDENT 0.0
.IP \(bu 2
jump to the next (previous) selectable element with pressing \fBtab\fP
(\fBshift+tab\fP)
.IP \(bu 2
quick save, default keybinding \fBmeta+enter\fP (\fBmeta\fP will probably be \fBalt\fP)
.IP \(bu 2
use some common editing short cuts in most text fields (\fBctrl+w\fP deletes word
before cursor, \fBctrl+u\fP (\fBctrl+k\fP) deletes till the beginning (end) of the
line, \fBctrl+a\fP (\fBctrl+e\fP) will jump to the beginning (end) of the line
.IP \(bu 2
in the date and time fields you can increment and decrement the number under
the cursor with \fBctrl+a\fP and \fBctrl+x\fP (time in 15 minute steps)
.IP \(bu 2
in the date fields you can access a miniature calendar by pressing \fIenter\fP
.IP \(bu 2
activate actions by pressing \fBenter\fP on text enclosed by angled brackets, e.g.
<\ Save\ > (sometimes this might open a pop up)
.UNINDENT
.sp
Pressing \fBesc\fP will cancel the current action and/or take you back to the
previously shown pane (i.e. what you see when you open ikhal), if you are at the
start pane, ikhal will quit on pressing \fBesc\fP again.
.SS new
.sp
allows for adding new events. \fBkhal new\fP should understand the following syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
khal new [\-a CALENDAR] [OPTIONS] [START [END | DELTA] [TIMEZONE] SUMMARY
[:: DESCRIPTION]]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
where start\- and enddatetime are either datetimes, times, or keywords and times
in the formats defined in the config file. If no calendar is given via
\fI\%\-a\fP, the default calendar is used. \fBnew\fP does not support
\fI\%\-d\fP and also \fI\%\-a\fP may only be used once.
.sp
\fBnew\fP accepts these combinations for start and endtimes (specifying
the end is always optional):
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fIdatetime [datetime|time] [timezone]\fP
.IP \(bu 2
\fItime [time] [timezone]\fP
.IP \(bu 2
\fIdate [date]\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
where the formats for datetime and time are as follows:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fIdatetime = (longdatetimeformat|datetimeformat|keyword\-date timeformat)\fP
.IP \(bu 2
\fItime = timeformat\fP
.IP \(bu 2
\fIdate = (longdateformat|dateformat)\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
and \fItimezone\fP, which describes the timezone the events start and end time are
in, should be a valid Olson DB identifier (like \fIEurope/Berlin\fP or
\fIAmerica/New_York\fP\&. If no timezone is given, the \fIdefaulttimezone\fP as
configured in the configuration file is used instead.
.sp
The exact format of longdatetimeformat, datetimeformat, timeformat,
longdateformat and dateformat can be configured in the configuration file.
Valid keywords for dates are \fItoday\fP, \fItomorrow\fP, the English name of all seven
weekdays and their three letter abbreviations (their next occurrence is used).
.sp
If no end is given, the default length of one hour or one day (for all\-day
events) is used. If only a start time is given the new event is assumed to be
starting today. If only a time is given for the event to end on, the event ends
on the same day it starts on, unless that would make the event end before it has
started, then the next day is used as end date
.sp
If a 24:00 time is configured (timeformat = %H:%M) an end time of \fI24:00\fP is
accepted as the end of a given date.
.sp
If the \fBsummary\fP contains the string \fI::\fP, everything after \fI::\fP is taken as
the \fBdescription\fP of the new event, i.e., the "body" of the event (and \fI::\fP
will be removed).
.sp
Passing the option \fB\-\-interactive\fP (\fI\%\-i\fP) makes all arguments
optional and interactively prompts for required fields, then the event may be
edited, the same way as in the \fIedit\fP command.
.SS Options
.INDENT 0.0
.IP \(bu 2
\fB\-l, \-\-location=LOCATION\fP specify where this event will be held.
.IP \(bu 2
\fB\-g, \-\-categories=CATEGORIES\fP specify which categories this event belongs to.
Comma separated list of categories. Beware: some servers (e.g. SOGo) do not support multiple categories.
.IP \(bu 2
\fB\-r, \-\-repeat=RRULE\fP specify if and how this event should be recurring.
Valid values for \fIRRULE\fP are \fIdaily\fP, \fIweekly\fP, \fImonthly\fP
and \fIyearly\fP
.IP \(bu 2
\fB\-u, \-\-until=UNTIL\fP specify until when a recurring event should run
.IP \(bu 2
\fB\-\-url\fP specify the URL element of the event
.IP \(bu 2
\fB\-\-alarms DURATION,...\fP will add alarm times as DELTAs comma separated for this event,
\fIDURATION\fP should look like \fI1day 10minutes\fP or \fI1d3H10m\fP, negative
\fIDURATIONs\fP will set alarm after the start of the event.
.UNINDENT
.SS Examples
.sp
These may need to be adapted for your configuration and/or locale (START and END
need to match the format configured). See \fBprintformats\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
khal new 18:00 Awesome Event
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
adds a new event starting today at 18:00 with summary \(aqawesome event\(aq (lasting
for the default time of one hour) to the default calendar
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
khal new tomorrow 16:30 Coffee Break
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
adds a new event tomorrow at 16:30
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
khal new 25.10. 18:00 24:00 Another Event :: with Alice and Bob
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
adds a new event on 25th of October lasting from 18:00 to 24:00 with an
additional description
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
khal new \-a work 26.07. Great Event \-g meeting \-r weekly
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
adds a new all day event on 26th of July to the calendar \fIwork\fP in the \fImeeting\fP
category, which recurs every week.
.SS edit
.sp
an interactive command for editing and deleting events using a search string
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
khal edit [\-\-show\-past] event_search_string
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
the command will loop through all events that match the search string,
prompting the user to delete, or change attributes.
.SS printcalendars
.sp
prints a list of all configured calendars.
.SS printformats
.sp
prints a fixed date (\fI2013\-12\-21 21:45\fP) in all configured date(time) formats.
This is supposed to help check if those formats are configured as intended.
.SS search
.sp
search for events matching a search string and print them.  Currently, search
will print one line for every different event in a recurrence set, that is one
line for the master event, and one line for every different overwritten event.
No advanced search features are currently supported.
.sp
The command
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
khal search party
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
prints all events matching \fIparty\fP\&.
.SH CONFIGURATION
.sp
\fBkhal\fP reads configuration files in the \fIini\fP syntax, meaning it understands
keys separated from values by a \fB=\fP, while section and subsection names are
enclosed by single or double square brackets (like \fB[sectionname]\fP and
\fB[[subsectionname]]\fP). Any line beginning with a \fB#\fP will be treated as a
comment.
.SS Help with initial configuration
.sp
If you do not have a configuration file yet, running \fBkhal configure\fP
will launch a small, interactive tool that should help you with initial
configuration of \fBkhal\fP\&.
.SS Location of configuration file
.sp
\fBkhal\fP is looking for configuration files in the following places and
order: \fB$XDG_CONFIG_HOME/khal/config\fP (on most systems this is
\fB~/.config/khal/config\fP), \fB~/.khal/khal.conf\fP (deprecated) and a
file called \fBkhal.conf\fP in the current directory (deprecated).
Alternatively you can specify which configuration file to use with \fB\-c
path/to/config\fP at runtime.
.SS The [calendars] section
.sp
The \fI[calendars]\fP section is mandatory and must contain at least one subsection.
Every subsection must have a unique name (enclosed by two square brackets).
Each subsection needs exactly one \fIpath\fP setting, everything else is optional.
Here is a small example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[calendars]

  [[home]]
    path = ~/.calendars/home/
    color = dark green
    priority = 20

  [[work]]
    path = ~/.calendars/work/
    readonly = True

.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B color
khal will use this color for coloring this calendar\(aqs event.
The following color names are supported: \fIblack\fP, \fIwhite\fP, \fIbrown\fP, \fIyellow\fP,
\fIdark gray\fP, \fIdark green\fP, \fIdark blue\fP, \fIlight gray\fP, \fIlight green\fP, \fIlight
blue\fP, \fIdark magenta\fP, \fIdark cyan\fP, \fIdark red\fP, \fIlight magenta\fP, \fIlight
cyan\fP, \fIlight red\fP\&.
Depending on your terminal emulator\(aqs settings, they might look different
than what their name implies.
In addition to the 16 named colors an index from the 256\-color palette or a
24\-bit color code can be used, if your terminal supports this.
The 256\-color palette index is simply a number between 0 and 255.
The 24\-bit color must be given as #RRGGBB, where RR, GG, BB is the
hexadecimal value of the red, green and blue component, respectively.
When using a 24\-bit color, make sure to enclose the color value in \(aq or "!
If \fIcolor\fP is set to \fIauto\fP (the default), khal looks for a color value in a
\fIcolor\fP file in this calendar\(aqs vdir. If the \fIcolor\fP file does not exist, the
default_color (see below) is used. If color is set to \(aq\(aq, the default_color is
always used. Note that you can use \fIvdirsyncer metasync\fP to synchronize colors
with your caldav server.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
color
.TP
.B default
auto
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B path
The path to an existing directory where this calendar is saved as a \fIvdir\fP\&.
The directory is searched for events or birthdays (see \fBtype\fP). The path
also accepts glob expansion via \fI*\fP or \fI?\fP when type is set to discover.
This allows for paths such as \fI~/accounts/*/calendars/*\fP, where the
calendars directory contains vdir directories. In addition, \fI~/calendars/*\fP
and \fI~/calendars/default\fP are valid paths if there exists a vdir in the
\fIdefault\fP directory. (The previous behavior of recursively searching
directories has been replaced with globbing).
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
string
.TP
.B default
None
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B priority
When coloring days, the color will be determined based on the calendar with
the highest priority. If the priorities are equal, then the "multiple" color
will be used.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
integer
.TP
.B default
10
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B readonly
setting this to \fITrue\fP, will keep khal from making any changes to this
calendar
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
boolean
.TP
.B default
False
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B type
Setting the type of this collection (default \fBcalendar\fP).
.sp
If set to \fBcalendar\fP (the default), this collection will be used as a
standard calendar, that is, only files with the \fB\&.ics\fP extension will be
considered, all other files are ignored (except for a possible \fIcolor\fP file).
.sp
If set to \fBbirthdays\fP khal will expect a VCARD collection and extract
birthdays from those VCARDS, that is only files with \fB\&.vcf\fP extension will
be considered, all other files will be ignored.  \fBbirthdays\fP also implies
\fBreadonly=True\fP\&.
.sp
If set to \fBdiscover\fP, khal will use
\fI\%globbing\fP <\fBhttps://en.wikipedia.org/wiki/Glob_(programming)\fP> to expand this
calendar\(aqs \fIpath\fP to (possibly) several paths and use those as individual
calendars (this cannot be used with \fIbirthday\fP collections\(ga). See \fI\%Exemplary
discover usage\fP for an example.
.sp
If an individual calendar vdir has a \fIcolor\fP file, the calendar\(aqs color will
be set to the one specified in the \fIcolor\fP file, otherwise the color from the
\fIcalendars\fP subsection will be used.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
option, allowed values are \fIcalendar\fP, \fIbirthdays\fP and \fIdiscover\fP
.TP
.B default
calendar
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS The [default] section
.sp
Some default values and behaviors are set here.
.INDENT 0.0
.TP
.B default_calendar
The calendar to use if none is specified for some operation (e.g. if adding a
new event). If this is not set, such operations require an explicit value.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
string
.TP
.B default
None
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B default_dayevent_duration
Define the default duration for an event (\(aqkhal new\(aq only)
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
timedelta
.TP
.B default
1h
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B default_event_duration
Define the defaut duration for a day\-long event (\(aqkhal new\(aq only)
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
timedelta
.TP
.B default
1d
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B highlight_event_days
If true, khal will highlight days with events. Options for
highlighting are in [highlight_days] section.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
boolean
.TP
.B default
False
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B print_new
After adding a new event, what should be printed to standard out? The whole
event in text form, the path to where the event is now saved or nothing?
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
option, allowed values are \fIevent\fP, \fIpath\fP and \fIFalse\fP
.TP
.B default
False
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B show_all_days
By default, khal displays only dates with events in \fIlist\fP or \fIcalendar\fP
view.  Setting this to \fITrue\fP will show all days, even when there is no event
scheduled on that day.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
boolean
.TP
.B default
False
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B timedelta
Controls for how many days into the future we show events (for example, in
\fIkhal list\fP) by default.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
timedelta
.TP
.B default
2d
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS The [highlight_days] section
.sp
When highlight_event_days is enabled, this section specifies how
the highlighting/coloring of days is handled.
.INDENT 0.0
.TP
.B color
What color to use when highlighting \-\- explicit color or use calendar
color when set to \(aq\(aq
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
color
.TP
.B default
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B default_color
Default color for calendars without color \-\- when set to \(aq\(aq it
actually disables highlighting for events that should use the
default color.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
color
.TP
.B default
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B method
Highlighting method to use \-\- foreground or background
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
option, allowed values are \fIforeground\fP, \fIfg\fP, \fIbackground\fP and \fIbg\fP
.TP
.B default
fg
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B multiple
How to color days with events from multiple calendars \-\- either
explicit color or use calendars\(aq colors when set to \(aq\(aq
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
color
.TP
.B default
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS The [keybindings] section
.sp
Keybindings for \fBikhal\fP are set here. You can bind more then one key
(combination) to a command by supplying a comma\-separated list of keys.
For binding key combinations concatenate them keys (with a space in
between), e.g. \fBctrl n\fP\&.
.INDENT 0.0
.TP
.B delete
delete the currently selected event
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
list
.TP
.B default
d
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B down
move the cursor down (in the calendar browser)
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
list
.TP
.B default
down, j
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B duplicate
duplicate the currently selected event
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
list
.TP
.B default
p
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B export
export event as a .ics file
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
list
.TP
.B default
e
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B external_edit
edit the currently selected events\(aq raw .ics file with $EDITOR
Only use this, if you know what you are doing, the icalendar library we use
doesn\(aqt do a lot of validation, it silently disregards most invalid data.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
list
.TP
.B default
meta E
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B left
move the cursor left (in the calendar browser)
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
list
.TP
.B default
left, h, backspace
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B log
show logged messages
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
list
.TP
.B default
L
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mark
go into highlight (visual) mode to choose a date range
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
list
.TP
.B default
v
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B new
create a new event on the selected date
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
list
.TP
.B default
n
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B other
in highlight mode go to the other end of the highlighted date range
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
list
.TP
.B default
o
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B quit
quit
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
list
.TP
.B default
q, Q
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B right
move the cursor right (in the calendar browser)
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
list
.TP
.B default
right, l, space
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B save
save the currently edited event and leave the event editor
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
list
.TP
.B default
meta enter
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B search
open a text field to start a search for events
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
list
.TP
.B default
/
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B today
focus the calendar browser on today
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
list
.TP
.B default
t
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B up
move the cursor up (in the calendar browser)
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
list
.TP
.B default
up, k
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B view
show details or edit (if details are already shown) the currently selected event
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
list
.TP
.B default
enter
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS The [locale] section
.sp
It is mandatory to set (long)date\-, time\-, and datetimeformat options, all others options in the \fB[locale]\fP section are optional and have (sensible) defaults.
.INDENT 0.0
.TP
.B dateformat
khal will display and understand all dates in this format, see \fI\%timeformat\fP for the format
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
string
.TP
.B default
%x
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B datetimeformat
khal will display and understand all datetimes in this format, see
\fI\%timeformat\fP for the format.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
string
.TP
.B default
%c
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B default_timezone
this timezone will be used for new events (when no timezone is specified) and
when khal does not understand the timezone specified in the icalendar file.
If no timezone is set, the timezone your computer is set to will be used.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
timezone
.TP
.B default
None
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B firstweekday
the first day of the week, where Monday is 0 and Sunday is 6
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
integer, allowed values are between 0 and 6
.TP
.B default
0
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B local_timezone
khal will show all times in this timezone
If no timezone is set, the timezone your computer is set to will be used.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
timezone
.TP
.B default
None
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B longdateformat
khal will display and understand all dates in this format, it should
contain a year (e.g. \fI%Y\fP) see \fI\%timeformat\fP for the format.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
string
.TP
.B default
%x
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B longdatetimeformat
khal will display and understand all datetimes in this format, it should
contain a year (e.g. \fI%Y\fP) see \fI\%timeformat\fP for the format.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
string
.TP
.B default
%c
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B timeformat
khal will display and understand all times in this format.
.sp
The formatting string is interpreted as defined by Python\(aqs \fI\%strftime\fP <\fBhttps://docs.python.org/3/library/time.html#time.strftime\fP>, which is
similar to the format specified in \fBman strftime\fP\&.
.sp
In the configuration file it may be necessary to enclose the format in
quotation marks to force it to be loaded as a string.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
string
.TP
.B default
%X
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B unicode_symbols
by default khal uses some unicode symbols (as in \(aqnon\-ascii\(aq) as indicators for things like repeating events,
if your font, encoding etc. does not support those symbols, set this to \fIFalse\fP (this will enable ascii based replacements).
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
boolean
.TP
.B default
True
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B weeknumbers
Enable weeknumbers in \fIcalendar\fP and \fIinteractive\fP (ikhal) mode by specifying
whether they should be displayed on the \(aqleft\(aq or \(aqright\(aq. These are iso
weeknumbers, so will only work properly if \fIfirstweekday\fP is set to 0
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
weeknumbers
.TP
.B default
off
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS The [sqlite] section
.INDENT 0.0
.TP
.B path
khal stores its internal caching database here, by default this will be in the \fI$XDG_DATA_HOME/khal/khal.db\fP (this will most likely be \fI~/.local/share/khal/khal.db\fP).
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
string
.TP
.B default
None
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS The [view] section
.sp
The view section contains configuration options that effect the visual appearance
when using khal and ikhal.
.INDENT 0.0
.TP
.B agenda_day_format
Specifies how each \fIday header\fP is formatted.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
string
.TP
.B default
{bold}{name}, {date\-long}{reset}
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B agenda_event_format
Default formatting for events used when the user asks for all events in a
given time range, used for \fBlist\fP, \fBcalendar\fP and in
\fBinteractive\fP (ikhal). Please note, that any color styling will be
ignored in \fIikhal\fP, where events will always be shown in the color of the
calendar they belong to.
The syntax is the same as for \fB\-\-format\fP\&.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
string
.TP
.B default
{calendar\-color}{cancelled}{start\-end\-time\-style} {title}{repeat\-symbol}{description\-separator}{description}{reset}
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B blank_line_before_day
Add a blank line before the name of the day (khal only)
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
boolean
.TP
.B default
False
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B bold_for_light_color
Whether to use bold text for light colors or not. Non\-bold light colors may
not work on all terminals but allow using light background colors.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
boolean
.TP
.B default
True
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B dynamic_days
Defines the behaviour of ikhal\(aqs right column. If \fITrue\fP, the right column
will show events for as many days as fit, moving the cursor through the list
will also select the appropriate day in the calendar column on the left. If
\fIFalse\fP, only a fixed ([default] timedelta) amount of days\(aq events will be
shown, moving through events will not change the focus in the left column.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
boolean
.TP
.B default
True
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B event_format
Default formatting for events used when the start\- and end\-date are not
clear through context, e.g. for \fBsearch\fP, used almost everywhere
but \fBlist\fP and \fBcalendar\fP\&. It is therefore probably a
sensible choice to include the start\- and end\-date.
The syntax is the same as for \fB\-\-format\fP\&.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
string
.TP
.B default
{calendar\-color}{cancelled}{start}\-{end} {title}{repeat\-symbol}{description\-separator}{description}{reset}
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B event_view_always_visible
Set to true to always show the event view window when looking at the event list
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
boolean
.TP
.B default
False
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B event_view_weighting
weighting that is applied to the event view window
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
integer
.TP
.B default
1
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B frame
Whether to show a visible frame (with \fIbox drawing\fP characters) around some
(groups of) elements or not. There are currently several different frame
options available, that should visually differentiate whether an element is
in focus or not. Some of them will probably be removed in future releases of
khal, so please try them out and give feedback on which style you prefer
(the color of all variants can be defined in the color themes).
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
option, allowed values are \fIFalse\fP, \fIwidth\fP, \fIcolor\fP and \fItop\fP
.TP
.B default
False
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B monthdisplay
Display month name on row when the week contains the first day of
of the month (\(aqfirstday\(aq) or when the first day of the week is in the
month (\(aqfirstfullweek\(aq)
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
monthdisplay
.TP
.B default
firstday
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B theme
Choose a color theme for khal.
.sp
This is very much work in progress. Help is really welcome! The two currently
available color schemes (\fIdark\fP and \fIlight\fP) are defined in
\fIkhal/ui/colors.py\fP, you can either help improve those or create a new one
(see below). As ikhal uses urwid, have a look at \fI\%urwid\(aqs documentation\fP <\fBhttp://urwid.org/manual/displayattributes.html\fP>
for how to set colors and/or at the existing schemes. If you cannot change
the color of an element (or have any other problems) please open an issue on
\fI\%github\fP\&.
.sp
If you want to create your own color scheme, copy the structure of the
existing ones, give it a new and unique name and also add it as an option in
\fIkhal/settings/khal.spec\fP in the section \fI[default]\fP of the property \fItheme\fP\&.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B type
option, allowed values are \fIdark\fP and \fIlight\fP
.TP
.B default
dark
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
A minimal sample configuration could look like this:
.SS Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[calendars]
[[home]]
path = ~/.calendars/home/

[[work]]
path = ~/.calendars/work/

[locale]
local_timezone= Europe/Berlin
default_timezone= Europe/Berlin
timeformat= %H:%M
dateformat= %d.%m.
longdateformat= %d.%m.%Y
datetimeformat= %d.%m. %H:%M
longdatetimeformat= %d.%m.%Y %H:%M

.ft P
.fi
.UNINDENT
.UNINDENT
.SS Exemplary discover usage
.sp
If you have the following directory layout:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
~/calendars
├\- work/
├\- home/
└─ family/
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
where \fIwork\fP, \fIhome\fP and \fIfamily\fP are all different vdirs, each containing one
calendar, a matching calendar section could look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[[calendars]]
path = ~/calendars/*
type = discover
color = dark green
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Syncing
.sp
To get \fBkhal\fP working with CalDAV you will first need to setup
\fI\%vdirsyncer\fP <\fBhttps://github.com/pimutils/vdirsyncer\fP>\&.  After each start \fBkhal\fP will automatically check if
anything has changed and automatically update its caching db (this may take some
time after the initial sync, especially for large calendar collections).
Therefore, you might want to execute \fBkhal\fP automatically after syncing
with \fBvdirsyncer\fP (e.g. via \fBcron\fP).
.SH STANDARDS
.sp
\fIkhal\fP tries to follow standards and RFCs (most importantly \fI\%RFC 5545\fP <\fBhttps://tools.ietf.org/html/rfc5545.html\fP>
\fIiCalendar\fP) wherever possible. Known intentional and unintentional deviations
are listed below.
.SS RDATE;VALUE=PERIOD
.sp
\fIRDATE\fP s with \fIPERIOD\fP values are currently not supported, as \fI\%icalendar\fP <\fBhttps://github.com/collective/icalendar\fP> does
not support it yet. Please submit any real world examples of events with
\fIRDATE;VALUE=PERIOD\fP you might encounter (khal will print warnings if you have
any in your calendars).
.SS RANGE=THISANDPRIOR
.sp
Recurrent events with the \fIRANGE=THISANDPRIOR\fP are and will not be [1]
supported by khal, as applications supporting the latest \fI\%standard\fP <\fBhttp://tools.ietf.org/html/rfc5546\fP> MUST NOT
create those. khal will print a warning if it encounters an event containing
\fIRANGE=THISANDPRIOR\fP\&.
.IP [1] 5
unless a lot of users request this feature
.SS Events with neither END nor DURATION
.sp
While the RFC states:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
A calendar entry with a "DTSTART" property but no "DTEND"
property does not take up any time. It is intended to represent
an event that is associated with a given calendar date and time
of day, such as an anniversary. Since the event does not take up
any time, it MUST NOT be used to record busy time no matter what
the value for the "TRANSP" property.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
khal transforms those events into all\-day events lasting for one day (the start
date). As long a those events do not get edited, these changes will not be
written to the vdir (and with that to the CalDAV server). Any timezone
information that was associated with the start date gets discarded.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
While the main rationale for this behaviour was laziness on part of khal\(aqs
main author, other calendar software shows the same behaviour (e.g. Google
Calendar and Evolution).
.UNINDENT
.UNINDENT
.SS Timezones
.sp
Getting localized time right, seems to be the most difficult part about
calendaring (and messing it up ends in missing the one important meeting of the
week). So I\(aqll briefly describe here, how khal tries to handle timezone
information, which information it can handle and which it can\(aqt.
.sp
In general, there are two different type of events. \fILocalized events\fP (with
\fIlocalized\fP start and end datetimes) which have timezone information attached to
their start and end datetimes, and \fIfloating\fP events (with \fIfloating\fP start and end
datetimes), which have no timezone information attached (all\-day events, events that
last for complete days are floating as well). Localized events are always
observed at the same \fI\%UTC\fP <\fBhttps://en.wikipedia.org/wiki/Coordinated_Universal_Time\fP> (no matter what time zone the observer is in), but
different local times. On the other hand, floating events are always observed at
the same local time, which might be different in UTC.
.sp
In khal all localized datetimes are saved to the local database as UTC.
Datetimes that are already UTC, e.g. \fB19980119T070000Z\fP, are saved as such,
others are converted to UTC (but don\(aqt worry, the timezone information does not
get lost). Floating events get saved in floating time, independently of the
localized events.
.sp
If you want to look up which events take place at a specified datetime, khal
always expects that you want to know what events take place at that \fIlocal\fP
datetime. Therefore, the (local) datetime you asked for gets converted to UTC, the
appropriate \fIlocalized\fP events get selected and presented with their start and
end datetimes \fIconverted\fP to \fIyour local datetime\fP\&. For floating events no
conversion is necessary.
.sp
Khal (i.e. \fI\%icalendar\fP <\fBhttps://github.com/collective/icalendar\fP>) can understand all timezone identifiers as used in the
\fI\%Olson DB\fP <\fBhttps://en.wikipedia.org/wiki/Tz_database\fP> and custom timezone definitions, if those VTIMEZONE components are
placed before the VEVENTS that make use of them (as most calendar programs seem
to do). In case an unknown (or unsupported) timezone is found, khal will assume
you want that event to be placed in the \fIdefault timezone\fP (which can be
configured in the configuration file as well).
.sp
khal expects you \fIalways\fP want \fIall\fP start and end datetimes displayed in
\fIlocal time\fP (which can be set in the configuration file as well, otherwise
your computer\(aqs timezone is used).
.SH FAQ
.sp
Frequently asked questions:
.INDENT 0.0
.IP \(bu 2
.INDENT 2.0
.TP
\fBInstallation stops with an error: source/str_util.c:25:20: fatal error: Python.h: No such file or directory\fP
You do not have the Python development headers installed, on Debian based
Distributions you can install them via \fIaptitude install python\-dev\fP\&.
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
\fBunknown key "default_command"\fP
This key was deprecated by f8d9135.
See \fI\%https://github.com/pimutils/khal/issues/648\fP for the rationale behind this removal.
.UNINDENT
.UNINDENT
.SH LICENSE
.sp
khal is released under the Expat/MIT License:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Copyright (c) 2013\-2021 khal contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
.ft P
.fi
.UNINDENT
.UNINDENT
.SH AUTHOR
Christan Geier et al.
.SH COPYRIGHT
Copyright (c) 2013-2021 khal contributors
.\" Generated by docutils manpage writer.
.