Provided by: khal_0.9.10-1.1_all bug

NAME

       khal - khal Documentation

       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 vdirsyncer(1)  for
       CalDAV compatibility) standards.

USAGE

       Khal  offers  a  set  of  commands,  most  importantly  list,  calendar, interactive, new,
       printcalendars, printformats, and search. See  below  for  a  description  of  what  every
       command  does. Calling khal without any command will invoke the default command, which can
       be specified in the configuration file.

   Options
       khal (without any commands) has some options to print some information about khal:

       --version
              Prints khal's version number and exits

       -h, --help
              Prints a summary of khal's options and commands and then exits

       Several options are common to almost all of  khal's  commands  (exceptions  are  described
       below):

       -v     Be more verbose (e.g. print debugging information)

       -c CONFIGFILE
              Use an alternate configuration file

       -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.

       -d CALENDAR
              Specify a calendar which will be disregarded for this  run,  can  be  used  several
              times.

       --color/--no-color
              khal  will detect if standard output is not a tty, e.g., you redirect khal's output
              into a file, and if so  remove  all  highlighting/coloring  from  its  output.  Use
              --color  if  you  want  to  force  highlighting/coloring and --no-color if you want
              coloring always removed.

       --format FORMAT
              For all of khal's commands that print events, the formatting of that event  can  be
              specified  with  this  option.   FORMAT  is a template string, in which identifiers
              delimited by curly braces ({}) will be expanded to an event's  properties.   FORMAT
              supports    all    formatting    options    offered    by   python's   str.format()
              <https://docs.python.org/3/library/string.html#formatstrings>  (as   it   is   used
              internally).  The available template options are:

              title  The title of the event.

              description
                     The description of the event.

              start  The start datetime in datetimeformat.

              start-long
                     The start datetime in longdatetimeformat.

              start-date
                     The start date in dateformat.

              start-date-long
                     The start date in longdateformat.

              start-time
                     The start time in timeformat.

              end    The end datetime in datetimeformat.

              end-long
                     The end datetime in longdatetimeformat.

              end-date
                     The end date in dateformat.

              end-date-long
                     The end date in longdateformat.

              end-time
                     The end time in timeformat.

              repeat-symbol
                     A repeating symbol (loop arrow) if the event is repeating.

              description
                     The event description.

              description-separator
                     A separator: " :: " that appears when there is a description.

              location
                     The event location.

              calendar
                     The calendar name.

              calendar-color
                     Changes the output color to the calendar's color.

              start-style
                     The start time in timeformat OR an appropriate symbol.

              to-style
                     A  hyphen "-" or nothing such that it appropriately fits between start-style
                     and end-style.

              end-style
                     The end time in timeformat OR an appropriate symbol.

              start-end-time-style
                     A concatenation of start-style, to-style, and end-style  OR  an  appropriate
                     symbol.

              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.

              end-necessary-long
                     Same as end-necessary but uses datelong and datetimelong.

              status The status of the event (if this event has one), something like CONFIRMED or
                     CANCELLED.

              cancelled
                     The string CANCELLED (plus one blank) if the event's  status  is  cancelled,
                     otherwise nothing.

              By default, all-day events have no times. To see a start and end time anyway simply
              add -full to the end of  any  template  with  start/end,  for  instance  start-time
              becomes  start-time-full and will always show start and end times (instead of being
              empty for all-day events).

              In addition, there are colors: black, red,  green,  yellow,  blue,  magenta,  cyan,
              white  (and their bold versions: red-bold, etc.). There is also reset, which clears
              the styling, and bold, which is the normal bold.

              For example the below command with print the title and description  of  all  events
              today.

                 khal list --format "{title} {description}"

       --day-format DAYFORMAT
              works  similar  to  --format,  but  for day headings. It only has a few options (in
              addition to all the color options):

              date   The date in dateformat.

              date-long
                     The date in longdateformat.

              name   The date's name (Monday, Tuesday,…) or today or tomorrow.

              If the --day-format is passed an empty string  then  it  will  not  print  the  day
              headers (for an empty line pass in a whitespace character).

   dates
       Almost  everywhere  khal  accepts  dates,  khal  should recognize relative date names like
       today, tomorrow 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 next week (i.e. seven
       days from now).

   Commands
   list
       shows all events scheduled for a given date (or datetime) range, with custom formatting:

          khal list [-a CALENDAR ... | -d CALENDAR ...] [--format FORMAT]
          [--day-format DAYFORMAT] [--once] [--notstarted] [START [END | DELTA] ]

       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 I{m,h,d}, where I is  an
       integer  and m means minutes, h means hours, and d means days, is given, END is assumed to
       be START + DELTA.  A value of eod is also accepted as DELTA and means the end  of  day  of
       the  start  date.  In  addition,  the DELTA week may be used to specify that the daterange
       should actually be the week containing the START.

       The --once option only allows events to appear once even if they  are  on  multiple  days.
       With the --notstarted option only events are shown that start after START.

   at
       shows  all  events  scheduled for a given datetime. khal at should be supplied with a date
       and time, a time (the date is then assumed to be today) or the string now. at defaults  to
       now.  The  at command works just like the list command, except it has an implicit end time
       of zero minutes after the start.

          khal at [-a CALENDAR ... | -d CALENDAR ...] [--format FORMAT]
          [--notstarted] [[START DATE] TIME | now]

   calendar
       shows a calendar (similar to  cal(1))  and  list.  khal  calendar  should  understand  the
       following syntax:

          khal calendar [-a CALENDAR ... | -d CALENDAR ...] [START DATETIME]
          [END DATETIME]

       Date  selection  works  exactly  as  for  khal list. 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 khal list for a description of the
       options.

   configure
       will help users creating an initial configuration file. configure will refuse  to  run  if
       there already is a configuration file.

   import
       lets the user import .ics files with the following syntax:

          khal import [-a CALENDAR] [--batch] [--random-uid|-r] ICSFILE

       If  an  event  with  the same UID is already present in the (implicitly) selected calendar
       khal import 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 --random-uid flag to generate a new,  random  UID.   If  no  calendar  is
       specified  (and not --batch), you will be asked to choose a calendar. You can either enter
       the number printed behind each calendar's name or any unique prefix of a calendar's name.

   interactive
       invokes the interactive version of khal, can also be invoked by calling ikhal. While ikhal
       can  be  used entirely with the keyboard, some elements respond if clicked on with a mouse
       (mostly by being selected).

       When the calendar on the left is in focus, you can

          · move through the  calendar  (default  keybindings  are  the  arrow  keys,  space  and
            backspace, those keybindings are configurable in the config file)

          · focus on the right column by pressing tab or enter

          · re-focus on the current date, default keybinding t as in today

          · marking  a  date range, default keybinding v, as in visual, think visual mode in Vim,
            pressing esc escape this visual mode

          · if in visual mode, you can select the  other  end  of  the  currently  marked  range,
            default keybinding o as in other (again as in Vim)

          · create  a  new  event  on  the  currently  focused  day  (or date range if a range is
            selected), default keybinding n as in new

          · search for events, default keybinding /, a pop-up will ask for your search term

       When an event list is in focus, you can

          · view an event's details with pressing enter (or tab) and edit it with pressing  enter
            (or  tab)  again (if [default] event_view_always_visible is set to True, the event in
            focus will always be shown in detail)

          · toggle an event's deletion status, default keybinding d as in delete,  events  marked
            for deletion will appear with a D in front and will be deleted when khal exits.

          · duplicate  the  selected  event,  default keybinding p as in duplicate (d was already
            taken)

          · export the selected event, default keybinding e

       In the event editor, you can

       · jump to the next (previous) selectable element with pressing tab (shift+tab)

       · quick save, default keybinding meta+enter (meta will probably be alt)

       · use some common editing short cuts in most  text  fields  (ctrl+w  deletes  word  before
         cursor,  ctrl+u  (ctrl+k)  deletes till the beginning (end) of the line, ctrl+a (ctrl+e)
         will jump to the beginning (end) of the line

       · in the date and time field you can increment and decrement the number under  the  cursor
         with ctrl+a and ctrl+x (time in 15 minute steps)

       · activate  actions  by pressing enter on text enclosed by angled brackets, e.g.  < Save >
         (sometimes this might open a pop up)

       Pressing esc 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 esc again.

   new
       allows for adding new events. khal new should understand the following syntax:

          khal new [-a CALENDAR] [OPTIONS] [START [END | DELTA] [TIMEZONE] SUMMARY
          [:: DESCRIPTION]]

       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 -a, the default calendar
       is used. new does not support -d and also -a may only be used once.

       new accepts these combinations for start  and  endtimes  (specifying  the  end  is  always
       optional):

          · datetime [datetime|time] [timezone]

          · time [time] [timezone]

          · date [date]

       where the formats for datetime and time are as follows:

          · datetime = (longdatetimeformat|datetimeformat|keyword-date timeformat)

          · time = timeformat

          · date = (longdateformat|dateformat)

       and timezone, which describes the timezone the events start and end time are in, should be
       a valid Olson DB identifier (like Europe/Berlin or America/New_York.  If  no  timezone  is
       given, the defaulttimezone as configured in the configuration file is used instead.

       The  exact  format  of  longdatetimeformat, datetimeformat, timeformat, longdateformat and
       dateformat can be configured in the configuration file.   Valid  keywords  for  dates  are
       today,  tomorrow,  the  English  name  of  all  seven  weekdays  and  their  three  letter
       abbreviations (their next occurrence is used).

       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

       If a 24:00 time is configured (timeformat = %H:%M) an end time of 24:00 is accepted as the
       end of a given date.

       If  the summary contains the string ::, everything after :: is taken as the description of
       the new event, i.e., the "body" of the event (and :: will be removed).

       Passing the option --interactive (-i)  makes  all  arguments  optional  and  interactively
       prompts  for  required  fields,  then the event may be edited, the same way as in the edit
       command.

   Options
       · -l, --location=LOCATION specify where this event will be held.

       · -g, --categories=CATEGORIES specify which  categories  this  event  belongs  to.   Comma
         separated  list  of categories. Beware: some servers (e.g. SOGo) do not support multiple
         categories.

       · -r, --repeat=RRULE specify if and how this event should be recurring.  Valid values  for
         RRULE are daily, weekly, monthly and yearly

       · -u, --until=UNTIL specify until when a recurring event should run

       · --alarm  DURATION  will  add  an  alarm DURATION before the start of the event, DURATION
         should look like 1day 10minutes or 1d3H10m, negative DURATIONs will set alarm after  the
         start of the event.

   Examples
          khal new 18:00 Awesome Event

       adds  a  new  event  starting today at 18:00 with summary 'awesome event' (lasting for the
       default time of one hour) to the default calendar

          khal new tomorrow 16:30 Coffee Break

       adds a new event tomorrow at 16:30

          khal new 25.10. 18:00 24:00 Another Event :: with Alice and Bob

       adds a new event on 25th of October  lasting  from  18:00  to  24:00  with  an  additional
       description

          khal new -a work 26.07. Great Event -g meeting -r weekly

       adds a new all day event on 26th of July to the calendar work which recurs every week.

   edit
       an interactive command for editing and deleting events using a search string

          khal edit [--show-past] event_search_string

       the  command will loop through all events that match the search string, prompting the user
       to delete, or change attributes.

   printcalendars
       prints a list of all configured calendars.

   printformats
       prints a fixed date (2013-12-21 10:09) in all  configured  date(time)  formats.   This  is
       supposed to help check if those formats are configured as intended.

   search
       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.

       The command

          khal search party

       prints all events matching party.

CONFIGURATION

       khal reads configuration files in the ini syntax, meaning it  understands  keys  separated
       from  values  by  a =, while section and subsection names are enclosed by single or double
       square brackets (like [sectionname] and [[subsectionname]]).

   Help with initial configuration
       If you do not have a configuration file yet, running khal configure will launch  a  small,
       interactive tool that should help you with initial configuration of khal.

   Location of configuration file
       khal   is   looking   for   configuration   files  in  the  following  places  and  order:
       $XDG_CONFIG_HOME/khal/config   (on   most   systems   this   is    ~/.config/khal/config),
       ~/.khal/khal.conf  (deprecated)  and  a  file  called  khal.conf  in the current directory
       (deprecated).  Alternatively you can specify which  configuration  file  to  use  with  -c
       path/to/config at runtime.

   The [calendars] section
       The  [calendars]  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 path setting, everything else is optional.  Here is a small example:

          [calendars]

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

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

       color  khal  will  use this color for coloring this calendar's event.  The following color
              names are supported: black, white, brown, yellow, dark gray, dark green, dark blue,
              light  gray,  light  green,  light  blue,  dark magenta, dark cyan, dark red, light
              magenta, light cyan, light red.  Depending on your  terminal  emulator's  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 ' or "!  If  the
              color  is  set  to  auto (the default), khal tries to read the file color from this
              calendar's vdir, if this fails the default_color (see below) is used. If  color  is
              set to '', the default_color is always used.

                 type   color

                 default
                        auto

       path   The  path  to  an  existing  directory where this calendar is saved as a vdir.  The
              directory is searched for events or birthdays (see type).  The  path  also  accepts
              glob expansion via * or ? when type is set to discover.  This allows for paths such
              as  ~/accounts/*/calendars/*,  where  the   calendars   directory   contains   vdir
              directories.  In addition, ~/calendars/* and ~/calendars/default are valid paths if
              there exists a vdir in the default directory. (The previous behavior of recursively
              searching directories has been replaced with globbing).

                 type   string

                 default
                        None

       readonly
              setting this to True, will keep khal from making any changes to this calendar

                 type   boolean

                 default
                        False

       type   Setting the type of this collection (default calendar).

              If  set  to  calendar  (the  default),  this  collection will be used as a standard
              calendar, that is, only files with the .ics extension will be considered, all other
              files are ignored (except for a possible color file).

              If  set to birthdays khal will expect a VCARD collection and extract birthdays from
              those VCARDS, that is only files with .ics extension will be considered, all  other
              files will be ignored.  birthdays also implies readonly=True.

              If       set       to       discover,       khal       will       use      globbing
              <https://en.wikipedia.org/wiki/Glob_(programming)> to expand this  calendar's  path
              to  (possibly)  several paths and use those as individual calendars (this cannot be
              used with birthday collections`). See Exemplary discover usage for an example.

              If an individual calendar vdir has a color file, the calendar's color will  be  set
              to  the  one  specified  in  the color file, otherwise the color from the calendars
              subsection will be used.

                 type   option, allowed values are calendar, birthdays and discover

                 default
                        calendar

   The [default] section
       Some default values and behaviors are set here.

       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.

                 type   string

                 default
                        None

       default_command
              Command to be executed if no command is given when executing khal.

                 type   option,  allowed  values  are  calendar, list, interactive, printformats,
                        printcalendars, printics and **

                 default
                        calendar

       highlight_event_days
              If true, khal will highlight days with events.  Options  for  highlighting  are  in
              [highlight_days] section.

                 type   boolean

                 default
                        False

       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?

                 type   option, allowed values are event, path and False

                 default
                        False

       show_all_days
              By default, khal displays only dates with events in list or calendar view.  Setting
              this to True will show all days, even when there is no event scheduled on that day.

                 type   boolean

                 default
                        False

       timedelta
              Controls  for  how  many  days into the future we show events (for example, in khal
              list) by default.

                 type   timedelta

                 default
                        2d

   The [highlight_days] section
       When highlight_event_days is enabled, this section specifies how the highlighting/coloring
       of days is handled.

       color  What  color  to  use when highlighting -- explicit color or use calendar color when
              set to ''

                 type   color

                 default

       default_color
              Default color for calendars without color -- when set to ''  it  actually  disables
              highlighting for events that should use the default color.

                 type   color

                 default

       method Highlighting method to use -- foreground or background

                 type   option, allowed values are foreground, fg, background and bg

                 default
                        fg

       multiple
              How  to  color days with events from multiple calendars -- either explicit color or
              use calendars' colors when set to ''

                 type   color

                 default

   The [keybindings] section
       Keybindings for ikhal 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. ctrl n.

       delete delete the currently selected event

                 type   list

                 default
                        d

       down   move the cursor down (in the calendar browser)

                 type   list

                 default
                        down, j

       duplicate
              duplicate the currently selected event

                 type   list

                 default
                        p

       export export event as a .ics file

                 type   list

                 default
                        e

       external_edit
              edit the currently selected events' raw .ics file with $EDITOR Only  use  this,  if
              you  know  what  you  are  doing,  the icalendar library we use doesn't do a lot of
              validation, it silently disregards most invalid data.

                 type   list

                 default
                        meta E

       left   move the cursor left (in the calendar browser)

                 type   list

                 default
                        left, h, backspace

       mark   go into highlight (visual) mode to choose a date range

                 type   list

                 default
                        v

       new    create a new event on the selected date

                 type   list

                 default
                        n

       other  in highlight mode go to the other end of the highlighted date range

                 type   list

                 default
                        o

       quit   quit

                 type   list

                 default
                        q, Q

       right  move the cursor right (in the calendar browser)

                 type   list

                 default
                        right, l, space

       save   save the currently edited event and leave the event editor

                 type   list

                 default
                        meta enter

       search open a text field to start a search for events

                 type   list

                 default
                        /

       today  focus the calendar browser on today

                 type   list

                 default
                        t

       up     move the cursor up (in the calendar browser)

                 type   list

                 default
                        up, k

       view   show details or edit (if details are already shown) the currently selected event

                 type   list

                 default
                        enter

   The [locale] section
       It is mandatory to set (long)date-, time-, and datetimeformat options, all others  options
       in the [locale] section are optional and have (sensible) defaults.

       dateformat
              khal  will  display and understand all dates in this format, see timeformat for the
              format

                 type   string

                 default
                        %d.%m.

       datetimeformat
              khal will display and understand all datetimes in this format, see  timeformat  for
              the format.

                 type   string

                 default
                        %d.%m. %H:%M

       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.

                 type   timezone

                 default
                        None

       firstweekday
              the first day of the week, were Monday is 0 and Sunday is 6

                 type   integer, allowed values are between 0 and 6

                 default
                        0

       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.

                 type   timezone

                 default
                        None

       longdateformat
              khal will display and understand all dates in this format, it should contain a year
              (e.g. %Y) see timeformat for the format.

                 type   string

                 default
                        %d.%m.%Y

       longdatetimeformat
              khal  will display and understand all datetimes in this format, it should contain a
              year (e.g. %Y) see timeformat for the format.

                 type   string

                 default
                        %d.%m.%Y %H:%M

       timeformat
              khal will display and understand all times in this format.

              The  formatting  string  is   interpreted   as   defined   by   Python's   strftime
              <https://docs.python.org/2/library/time.html#time.strftime>,  which  is  similar to
              the format specified in man strftime.

                 type   string

                 default
                        %H:%M

       unicode_symbols
              by default khal uses some unicode symbols (as in  'non-ascii')  as  indicators  for
              things  like  repeating  events, if your font, encoding etc. does not support those
              symbols, set this to False (this will enable ascii based replacements).

                 type   boolean

                 default
                        True

       weeknumbers
              Enable weeknumbers in calendar and interactive  (ikhal)  mode.  As  those  are  iso
              weeknumbers, they only work properly if firstweekday is set to 0

                 type   weeknumbers

                 default
                        off

   The [sqlite] section
       path   khal  stores  its  internal  caching  database here, by default this will be in the
              $XDG_DATA_HOME/khal/khal.db (this will most likely be ~/.local/share/khal/khal.db).

                 type   string

                 default
                        None

   The [view] section
       The view section contains configuration options that effect  the  visual  appearance  when
       using khal and ikhal.

       agenda_day_format
              Specifies how each day header is formatted.

                 type   string

                 default
                        {bold}{name}, {date-long}{reset}

       agenda_event_format
              Default  formatting  for  events  used when the user asks for all events in a given
              time range, used for list, calendar and in interactive (ikhal). Please  note,  that
              any  color  styling  will be ignored in ikhal, where events will always be shown in
              the color of the calendar they belong to.  The syntax is the same as for --format.

                 type   string

                 default
                        {calendar-color}{cancelled}{start-end-time-style}
                        {title}{repeat-symbol}{description-separator}{description}{reset}

       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.

                 type   boolean

                 default
                        True

       dynamic_days
              Defines the behaviour of ikhal's right column. If True, 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  False,  only  a  fixed
              ([default]  timedelta)  amount of days' events will be shown, moving through events
              will not change the focus in the left column.

                 type   boolean

                 default
                        True

       event_format
              Default formatting for events used when the  start-  and  end-date  are  not  clear
              through  context, e.g. for search, used almost everywhere but list and calendar. It
              is therefore probably a sensible choice to include the start-  and  end-date.   The
              syntax is the same as for --format.

                 type   string

                 default
                        {calendar-color}{cancelled}{start}-{end}
                        {title}{repeat-symbol}{description-separator}{description}{reset}

       event_view_always_visible
              Set to true to always show the event view window when looking at the event list

                 type   boolean

                 default
                        False

       event_view_weighting
              weighting that is applied to the event view window

                 type   integer

                 default
                        1

       frame  Whether to show a visible frame (with box drawing 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).

                 type   option, allowed values are False, width, color and top

                 default
                        False

       theme  Choose a color theme for khal.

              This  is  very  much  work  in  progress. Help is really welcome! The two currently
              available color schemes (dark and light) are defined in khal/ui/colors.py, you  can
              either  help  improve  those  or create a new one (see below). As ikhal uses urwid,
              have          a          look          at           urwid's           documentation
              <http://urwid.org/manual/displayattributes.html>  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 github.

              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
              khal/settings/khal.spec in the section [default] of the property theme.

                 type   option, allowed values are dark and light

                 default
                        dark

       A minimal sample configuration could look like this:

   Example
          [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

   Exemplary discover usage
       If you have the following directory layout:

          ~/calendars
          ├- work/
          ├- home/
          └─ family/

       where  work,  home  and  family  are  all different vdirs, each containing one calendar, a
       matching calendar section could look like this:

          [[calendars]]
          path = ~/calendars/*
          type = discover
          color = dark green

   Syncing
       To  get  khal  working  with  CalDAV   you   will   first   need   to   setup   vdirsyncer
       <https://github.com/untitaker/vdirsyncer>.  After each start khal 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 khal automatically after syncing with vdirsyncer (e.g. via cron).

STANDARDS

       khal   tries   to   follow   standards   and   RFCs    (most    importantly    RFC    5545
       <https://tools.ietf.org/html/rfc5545.html> iCalendar) wherever possible. Known intentional
       and unintentional deviations are listed below.

   RDATE;VALUE=PERIOD
       RDATE   s   with   PERIOD   values   are   currently   not   supported,    as    icalendar
       <https://github.com/collective/icalendar>  does not support it yet. Please submit any real
       world examples of events with RDATE;VALUE=PERIOD you  might  encounter  (khal  will  print
       warnings if you have any in your calendars).

   RANGE=THISANDPRIOR
       Recurrent events with the RANGE=THISANDPRIOR are and will not be [1] supported by khal, as
       applications supporting the latest standard <http://tools.ietf.org/html/rfc5546> MUST  NOT
       create   those.   khal  will  print  a  warning  if  it  encounters  an  event  containing
       RANGE=THISANDPRIOR.

       [1]  unless a lot of users request this feature

   Events with neither END nor DURATION
       While the RFC states:

          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.

       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.

       NOTE:
          While the main rationale for this behaviour was laziness on part of khal's main author,
          other calendar software shows the same behaviour (e.g. Google Calendar and Evolution).

   Timezones
       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'll briefly
       describe here, how khal tries to handle timezone information,  which  information  it  can
       handle and which it can't.

       In general, there are two different type of events. Localized events (with localized start
       and end datetimes) which have  timezone  information  attached  to  their  start  and  end
       datetimes,  and  floating  events  (with  floating 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  UTC
       <https://en.wikipedia.org/wiki/Coordinated_Universal_Time> (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.

       In khal all localized datetimes are saved to the local database as  UTC.   Datetimes  that
       are  already  UTC,  e.g.  19980119T070000Z, are saved as such, others are converted to UTC
       (but don't worry, the timezone information does not get lost). Floating events  get  saved
       in floating time, independently of the localized events.

       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  local  datetime.  Therefore,
       the (local) datetime you asked for gets converted to UTC, the appropriate localized events
       get selected and presented with their start and end  datetimes  converted  to  your  local
       datetime. For floating events no conversion is necessary.

       Khal   (i.e.   icalendar  <https://github.com/collective/icalendar>)  can  understand  all
       timezone identifiers as used in the Olson  DB  <https://en.wikipedia.org/wiki/Tz_database>
       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 default timezone (which can be configured in the configuration file as well).

       khal expects you always want all start and end datetimes displayed in  local  time  (which
       can be set in the configuration file as well, otherwise your computer's timezone is used).

FAQ

       Frequently asked questions:

       ·

         start up of khal and ikhal is very slow
                In  some case the pytz (python timezone) is only available as a zip file, as pytz
                accesses several parts during initialization this takes some time. If time python
                -c  "import  pytz;  pytz.timezone('Europe/Berlin')"  takes nearly as much time as
                running khal, uncompressing that file via pytz via (sudo) pip  unzip  pytz  might
                help.

       ·

         ikhal   raises   an   Exception:   AttributeError:  'module'  object  has  no  attribute
         'SimpleFocusListWalker'
                You probably need to upgrade urwid to version 1.1.0, if your OS does come with an
                older  version  of urwid you can install the latest version to userspace (without
                messing up your default installation) with pip install --upgrade urwid --user.

       ·

         Installation stops with an error: source/str_util.c:25:20:  fatal  error:  Python.h:  No
         such file or directory
                You  do  not  have  the  Python  development  headers  installed, on Debian based
                Distributions you can install them via aptitude install python-dev.

LICENSE

       khal is released under the Expat/MIT License:

          Copyright (c) 2013-2017 Christian Geier et al.

          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.

AUTHOR

       Christan Geier et al.

COPYRIGHT

       2014-2019, Christan Geier et al.