path: root/doc/calcurse.1.txt

////
/*
 * Copyright (c) 2004-2017 calcurse Development Team <misc@calcurse.org>
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 *      - Redistributions of source code must retain the above
 *        copyright notice, this list of conditions and the
 *        following disclaimer.
 *
 *      - Redistributions in binary form must reproduce the above
 *        copyright notice, this list of conditions and the
 *        following disclaimer in the documentation and/or other
 *        materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
////

CALCURSE(1)
===========

NAME
----

calcurse - terminal-based organizer for interactive and command line use

SYNOPSIS
--------

--
*calcurse* [-D 'datadir'] [-C 'confdir'] [-c 'calendar-file']

*calcurse* -Q [*--from* 'date'] [*--to* 'date' | *--days* 'number']

*calcurse* -a | -d 'date' | -d 'number' | -n | -r['number'] | -s['date'] | -t['number']

*calcurse*  -G ['filter options'] ['format options'] | -P ['filter options'] ['format options']

*calcurse* -h | --status |  -g | -i 'file'  | -x['file'] | --daemon
--

The first form shows how to invoke calcurse interactively; the remainder is
command line forms.

The second form shows queries (as opposed to interactive use). For
convenience, common queries have abbriviated forms shown in the third line.
All queries may be combined with filter options as well as format options.

The fourth form shows operations on the calcurse data files, one for
display of entries, the other for removal of them.

The fifth form is miscellaneous help and support functions.

All details are in <<_options,OPTIONS>>.

DESCRIPTION
-----------

calcurse is a calendar and scheduling application for use in a terminal
session (terminal emulator). When invoked without options, calcurse enters
interactive mode; in most other cases, calcurse produces output on the
terminal and exits.  It helps keeping track of events, appointments and
everyday tasks. Interactive mode is used when data are entered or when already
existing entries are inspected or edited. All data are saved to disk as text
files. Command line mode is used for queries and administrative tasks and for
automating tasks in scripts.

The interactive interface is based on ncurses and can be customized to suit
user preferences. Customization includes program behaviour as well as visual
appearance and key bindings, and is performed interactively; the result is
automatically saved to disk and loaded on every invocation. Available actions
are documented in an online help system. A configurable notification system
issues reminders of upcoming deadlines.

When leaving the interactive program, a background daemon may continue running
and issue reminders; it stops automatically when the interactive mode is
reentered.

This man page mainly describes the command-line mode. The following two
subsections contain some general desriptions of command line options and usage.

Input and Output Date Format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Many options require a 'date' argument, and query results per day are set apart
by a leading 'date line'.

The input format of 'date' options and the output format of 'date lines' are
taken from the configuration file (see <<_files,FILES>>). The formats are set
in the "General Options" submenu in interactive mode.  Particularly in scripts
it may be desirable that formats are independent of the local user
configuration. For this purpose use the options *--input-datefmt* and
*--output-datefmt*.

An input date consists of 'date', 'month' and 'year'. Here 'day' must be in
the range 1-31 and 'month' in 1-12. Depending on the operating system 'year'
must be in the range 1902-2037 or 1902-?.  Additionally, some short forms are
allowed with the obvious meaning: +today+, +tomorrow+, +yesterday+, +now+ and
weekdays +mon+, ..., +sun+.

Optionally, a 'date' argument for a filter option (see
<<_filter_options,Filter Options>>) may be followed by a time-of-day
specification in hours and minutes (24-hour clock). The specification has the
fixed format hh:mm (example: +"2018-12-1 20:30"+ when the input date format is
the ISO standard format). Note that the entire date specification must be
quoted to create one argument.

Filter, format and day range options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These options do not accomplish anything in and of themselves. They influence
other options and are in a way opposites: filter options affect the input to,
format and day range options the output from calcurse. Specifically, filter
options limit what is loaded from the data files into calcurse, day range
options limit what is output (see <<_query,-Q>>), and
<<_format_options,format options>> describe how it is presented.

Filter options have effect on queries (*-Q* and query short-forms), grep
(*-G*), purge (*-P*) and export (*-x*). Format options have effect on queries,
grep and *--dump-imported*. Day range options have effect on queries only.

OPTIONS
-------

Most options imply command line mode. Options compatible with interactive mode
are marked "('also interactively')".

*-a*, *--appointment*::
  Print the appointments and events for the current day. Equivalent to *-Q
  --filter-type cal*.

*-c* 'file', *--calendar* 'file'::
  ('also interactively') Specify the calendar file to use. The default
  calendar is *$XDG_DATA_HOME/apts* (*\~/.local/share/calcurse/apts*) or
  *\~/.calcurse/apts* if *~/.calcurse* exists.  (see <<_files,FILES>>). If
  'file' is not an absolute path name, it is interpreted relative to the current
  working directory. The option has precedence over *-D*.

*-C* 'dir', *--confdir* 'dir'::
  ('also interactively') Specify the configuration directory to use. If not
  specified, the default directory is *$XDG_CONFIG_HOME/calcurse/*
  (*\~/.config/calcurse/*) or *~/.calcurse* if it exists.  See <<_files,FILES>>
  for the interaction with *-D*.

*-D* 'dir', *--datadir* 'dir'::
  ('also interactively') Specify the (data) directory to use. If not specified,
  the default directory is *$XDG_DATA_HOME/calcurse*
  (*\~/.local/share/calcurse/*) or *~/.calcurse* if it exists.  See section
  <<_files,FILES>> for the interaction with *-C*.

*-d* 'date|num', *--day* 'date|num'::
  Print appointments and events for the given date or given range of days,
  depending on the argument format:
+
--
  * a 'date'
  * a number 'num'
--
+
In the first case, appointments and events for 'date' are returned, while in
the second case those for 'num' days are returned.  Positive values of 'num'
means the future, negative the past; the range either starts or ends with the
current day. As an example +calcurse -d 3+ displays appointments and events
for today, tomorrow and the day after tomorrow, while +calcurse -d -2+
displays those for yesterday and today. The first form is equivalent to *-Q
--filter-type cal --from* 'date', the second to *-Q --filter-type cal --days*
'num'.

*--daemon*::
  Start calcurse in background mode; restart, if the daemon was already
  running. Usually done automatically by setting the configuration option
  +daemon.enable+ in the 'Notify' submenu in interactive mode.

*--days* 'num'::
  Specify the range of days when used with *-Q*. Can be combined with
  *--from*, but not with *--to*. Without *--from*, the first day of the range
  defaults to the current day. The number may be negative, see
  <<_query,-Q --query>>.

*--dump-imported*::
  When importing items, print each newly created object to stdout.  Format
  options can be used to specify which details are printed. See also
  <<_format_options,Format Options>>.

*--export-uid*::
  When exporting items, add the hash of each item to the exported object as an
  UID property.

*--from* 'date'::
  Specify the start date of the day range when used with *-Q*. When used
  without *-to* or *--days* the range is one day (the specified day), see
  <<_query,-Q --query>>.

*-F*, *--filter*::
  Deprecated, see <<_purge,-P, --purge>>. Note that this option is for
  backward compatibility and not the same as *-P* (it does not use the invert
  filter option).

*-g*, *--gc*::
  Run the garbage collector for note files. The garbage collector removes
  files from the +notes+ directory (see <<_files,FILES>>) that are no longer
  linked to an item. Ususally done automatically by setting the configuration
  option +general.autogc+ in the 'General Options' submenu in interactive mode.

*-G*, *--grep*::
  Print appointments, events and TODO items in calcurse data file format.

*-h*, *--help*::
  Print a short help text describing the supported command-line options.

*-i* 'file', *--import* 'file'::
  Import the icalendar data contained in 'file'.

*--input-datefmt* 'format'::
  For command line and script use only: override the configuration file
  setting of the option +format.inputdate+ ('General Options' submenu in
  interactive mode).  A valid 'format' is any of 1, 2, 3, or 4, with 1 =
  mm/dd/yyyy, 2 = dd/mm/yyyy, 3 = yyyy/mm/dd, 4 = yyyy-mm-dd.

*-l* 'num', *--limit* 'num'::
  Limit the number of results printed to 'num'.

*-n*, *--next*::
  Print the first appointment within the next 24 hours. The printed time is
  the number of hours and minutes left before this appointment.

*--output-datefmt* 'format'::
  For command line and script use only: override the configuration file
  setting of the option +format.outputdate+ ('General Options' submenu in
  interactive mode).  A valid 'format' is any strftime(3) format string.

*-P*, *--purge*[[_purge]]::
  Load items from the data files and save them back; the items are described
  by suitable filter options (see <<_filter_options,Filter Options>>). It may
  be used to drop specific items from the data files, see
  <<_examples,EXAMPLES>>.
+
The matching items are (silently) 'removed' from the data files. Any
combination of filter options, except +--filter-invert+, may be used in
describing the items to be removed. The invert filter is used internally by
the purge option, and its simultaneous use on the command line may result in
unpredictable behaviour.
+
'Warning:' Be careful with this option, specifying the wrong filter options
may result in data loss. It is highly recommended to test with *-G* first
and fine-tune the filters to show the items to be removed.  Then run the
same command with +-P+ instead of +-G+.  In any case, make a backup of the
data files in advance.

*-q*, *--quiet*::
  ('also interactively') Be quiet. Do not show system dialogs.

*-Q*, *--query*[[_query]]::
  Print all appointments and events in a given 'range of days' followed by all
  TODO items. The calendar part is displayed per day with a leading line
  containing the date and a trailing empty line (much like the calendar panel
  in interactive mode).
+
The 'day range' defaults to the current day and is changed with the options
*--from* and *--to*/*--days*.  The range +--from+ 'a' +--to+ 'z' includes both
'a' and 'z'. The range +--from+ 'a' +--days+ 'n', includes 'a' as the first
day, if 'n' is positive, or last day, if 'n' is negative.
+
Day range has an effect on queries only.

*-r*['num'], *--range*[='num']::
  Print appointments and events for 'num' number of days starting with the
  current day. If 'num' is left out, a range of 1 day is used. The number may
  be negative in which case the range is in the past, ending with the current
  day. Equivalent to *-Q --filter-type cal --days* 'num'.

*--read-only*::
  ('also interactively') Do not save configuration nor appointments and todos.
+
'Warning:' If you run calcurse interactively in read-only mode, all changes
from that session will be lost without warning!

*-s*['date'], *--startday*[='date']::
  Print events and appointments from the optional 'date'; default is the
  current day. Equivalent to *-Q --filter-type cal --from* 'date'.

*-S* 'regex', *--search* 'regex'::
  When used with any of *-a*, *-d*, *-r*, *-s*, or *-t* print only the
  items having a description that matches the given regular expression.
  Equivalent to *-Q --filter-pattern* 'regex'.

*--status*::
  Display the status of running instances of calcurse, interactive or
  background mode. The process pid is also printed.

*-t*['num'], *--todo*[='num']::
  Print the *todo* list. If the optional number 'num' is given, then only
  uncompleted (open) todos having a priority equal to 'num' will be returned.
  The priority number must be between +1+ (highest) and +9+ (lowest). It is
  also possible to specify +0+ for the priority, in which case only completed
  (closed)  tasks will be shown. Equivalent to *-Q --filter-type todo*,
  combined with *--filter-priority* and *--filter-completed* or
  *--filter-uncompleted*.

*--to* 'date'::
  Specify the end date of the day range when used with *-Q*. When used without
  *--from* the start day is the current day. Cannot be combined with *--days*,
  see <<_query,-Q --query>>.

*-v*, *--version*::
  Display *calcurse* version.

*-x*['format'], *--export*[='format']::
  Export user data in the specified format. Events, appointments and todos are
  converted and echoed to stdout. Two formats are available: +ical+ and
  +pcal+. The default 'format' is +ical+.

FILTER OPTIONS
--------------

Filter options have effect on queries (*-Q* and query short-forms), grep
(*-G*), purge (*-P*) and export (*-x*), see also options in the
<<_filter_format_and_day_range_options,DESCRIPTION>> section.

Several filter options may be given. For an item to be loaded into calcurse it
must match all filters. In other words, filters are logically "and"-ed.
The *--filter-type* option has a default value which matches any item.
All other filter options have no default value and only apply when explicitly
set.

The filter options fall into three groups: general, calendar, todo. The
'general filters' apply to all items, the 'calendar filters' concern start and end
times and apply to appointments and events only, and the 'todo filters' concern
priority and completeness and apply to TODOs only.

Outside the three groups is the invert filter.

*--filter-invert* ::
  Invert the combined effect of any other filters, i.e. load the items that
  do 'not' match them.

General filters
~~~~~~~~~~~~~~~

*--filter-type* 'type'::
  Include items that match 'type'. The type value is a comma-separated
  list of type descriptions selected from +event+, +apt+, +recur-event+,
  +recur-apt+ and +todo+. You can also use +recur+ as a shorthand for
  +recur-event,recur-apt+ and +cal+ as a shorthand for +event,apt,recur+.

*--filter-pattern* 'pattern'::
  Include items with a description that matches the pattern. The pattern is
  interpreted as an extended regular expression.

*--filter-hash* 'string'::
  Include items with a hash starting with 'string'. The filter can be negated
  by prepending an exclamation mark (+!+): include items with a hash string
  'not' starting with 'string'. For the (SHA1) hash of an item refer to
  <<_extended_format_specifiers,Extended format specifiers>>.

Calendar filters
~~~~~~~~~~~~~~~~

For filter options ending in *-from*, *-to*, *-after*, *-before* and *-range*,
start or end time is the filter criterion.

An event is an all-day appointment for which no times are displayed.  The
start time of an event is the beginning of the event day (midnight), the end
time is the end of the event day (one second before next midnight).

The *-start-* options ending in *-from*, *-after* and *-range* refer to the
same filter criterion and cannot be used together. The same is the case for
options ending in *-to*, *-before* and *-range*. Similar restrictions apply to
*-end-* options.

Start and end times of a recurrent item refer to the very first occurrence, not
to those of any of the repetitions. If a recurrent item meets the criterion,
all of the repetitions are displayed in queries, even though they may not meet the
criterion. If they are unwanted, they may be removed from the output with the
<<_query,day range>> options, although this will also remove other items in
that range.

*--filter-start-from* 'date'::
  Include items that start at or after a given date.

*--filter-start-to* 'date'::
  Include items that start at or before a given date.

*--filter-start-after* 'date'::
  Include items that start after a given date.

*--filter-start-before* 'date'::
  Include items that start before a given date.

*--filter-start-range* 'range'::
  Include items with a start date that belongs to a given range. A range
  consists of a start date and an end date, separated by a comma.

*--filter-end-from* 'date'::
  Include items that end at or after a given date.

*--filter-end-to* 'date'::
  Include items that end at or before a given date.

*--filter-end-after* 'date'::
  Include items that end after a given date.

*--filter-end-before* 'date'::
  Include items that end before a given date.

*--filter-end-range* 'range'::
  Include items with an end date that belongs to a given range. A range
  consists of a start date and an end date, separated by a comma.

Todo filters
~~~~~~~~~~~~

*--filter-priority* 'priority'::
  Include TODO items with a given priority.

*--filter-completed*::
  Include completed TODO items.

*--filter-uncompleted*::
  Include uncompleted TODO items.

FORMAT OPTIONS
--------------

Format options have effect on queries, grep and *--dump-imported*.

The options specify a format for appointments, recurring appointments, events,
recurring events or todo items, respectively.

*--format-apt* 'format'::

*--format-recur-apt* 'format'::

*--format-event* 'format'::

*--format-recur-event* 'format'::

*--format-todo* 'format'::
  The 'format' argument is a string composed of printf-style format
  specifiers, which are replaced as explained below, and ordinary characters,
  which are copied to stdout without modification. Each option has a default
  'format' string which is used when the option is not given. Default strings
  are described in <<_default_format_strings,Default Format Strings>>.
+
'Note': Use of a format option requires explicit formatting of field
separation and line spacing.

Default format strings
~~~~~~~~~~~~~~~~~~~~~~

Each specifier is introduced by a +%+ followed by a character which tells what to
print. The available specifiers depend on the item type. Times are printed as
hours and minutes (+hh:mm+) unless otherwise noted; time formats can be
changed with <<_extended_format_specifiers,extended specifiers>>.

For each format option there is a default format string which is used when the option
is not given. In query results the default format options are:

  --format-apt " - %S -> %E\n\t%m\n"
  --format-recur-apt " - %S -> %E\n\t%m\n"
  --format-event " * %m\n"
  --format-recur-event " * %m\n"
  --format-todo "%p. %m\n"

In all other cases (grep and dump-imported) the default format string is +"%(raw)"+.

Appointments
~~~~~~~~~~~~

*%d*::
  Print the duration of the appointment in seconds
*%e*::
  Print the end time of the appointment as the Unix time in seconds
*%E*::
  Print the end time of the appointment or the marker +..:..+ if
  it ends after midnight
*%m*::
  Print the description of the item
*%n*::
  Print the name of the note file belonging to the item
*%N*::
  Print the note belonging to the item
*%r*::
  Print the remaining time before the appointment
*%s*::
  Print the start time of the appointment as the Unix time in seconds
*%S*::
  Print the start time of the appointment or the marker +..:..+ if it begins
  before midnight

Events
~~~~~~

*%m*::
  Print the description of the item
*%n*::
  Print the name of the note file belonging to the item
*%N*::
  Print the note belonging to the item

Todo items
~~~~~~~~~~

*%m*::
  Print the description of the item
*%n*::
  Print the name of the note file belonging to the item
*%N*::
  Print the note belonging to the item
*%p*::
  Print the priority of the item

Extended format specifiers
~~~~~~~~~~~~~~~~~~~~~~~~~~

Extended format specifiers can be used to control the printing of times for
some of the single-letter specifiers. Additionally there are two specifiers
that do not have any corresponding short form and are intended for use in
scripting.

*%(duration*`[`*:*'format'`]`*)*::
  extended form of *%d*
*%(remaining*`[`*:*'format'`]`*)*::
  extended form of *%r*
+
'format' may contain any of the strftime(3) specifiers *%d*, *%H*, *%M* or
*%S* with the following modifications: 1) days are not limited to the
"calendar" values 0-31 (hours, minutes and seconds are "clock" values, but see
*E* in the following) 2) each number is by default padded with zeros to two
decimal places, 3) the *%* character may be followed by one or two optional
flags: *-*, which suppresses the zero-padding, *E*, which will suppress the
"clock" limits on *%H*, *%M* and *%S*; if both are used, *-* must precede *E*,
4) no other flags or width specifications are supported

*%(start*`[`*:*'format'`]`*)*::
  extended form of *%s*
*%(end*`[`*:*'format'`]`*)*::
  extended form of *%e*
+
'format' may be any strftime(3) format specifier or one of the strings *epoch*
or *default*; the former is equivalent to the (calcurse) specifiers *%s* and
*%e* (seconds since the Epoch); the latter is equivalent to the (calcurse)
specifiers *%S* and *%E* or the (strftime) format string *%H:%M*, except that
the continuation marker +..:..+ is printed if the start/end time belongs to
another day

*%(raw)*::
  the text file format of an item as saved on disk; the default format for
  the grep and dump-imported options; can be used with all format options

*%(hash)*::
  the (SHA1) hash of the above; can be used with all format options

EXAMPLES
--------

`calcurse -d tomorrow`::
  Display the calendar for tomorrow (same as `calcurse -Q --filter-type
  cal --from tomorrow`).

`calcurse -d friday`::
  Display the calendar for the upcoming friday.

`calcurse -d 7`::
  Display the calendar for the next seven days (same as `calcurse -Q
  -filter-type cal --days 7`).

`calcurse -r7 --format-apt " - %S -> %E\n\t%m\n%N"`::
  Print appointments and events for the next seven days. Also, print the notes
  attached to each regular appointment.

`calcurse -r7 --format-apt " - %m (%S to %E)\n" --format-recur-apt " - %m (%S to %E)\n"`::
  Print appointments and events for the next seven days and use a custom format
  for (recurrent) appointments:
+
`- Some appointment (18:30 to 21:30)`

`calcurse -t --format-todo "(%p) %m\n"`::
  List all todo items and put parentheses around the priority specifiers.

If the calcurse data files contain many entries which are no longer needed or
wanted, they can, of course, be removed interactively. If there are many, it
can be a tedious task and may be done better as in the following two examples.

`calcurse --input-datefmt 4 -G --filter-start-before 2015-1-1`::
  List event and appointment entries in the data files with a start time
  before 1 January 2015, and all TODO entries.
+
*Purge*. When +-G+ is replaced by +-P+, those entries are removed. This may
remove recurring items that have occurrences after 1 January 2015.

`calcurse --input-datefmt 1 -G --filter-start-from 11/1/2015 --filter-type event,apt`::
  List (ordinary) event and appointment entries with a start time of 1
  November 2015 or later.

`calcurse -G --filter-type apt --format-apt "%(hash) %m\n"`::
  For each appointment list the SHA1 hash of the data file entry followed by
  the description.

`calcurse -G --filter-type apt --format-apt "%(duration:%d/%EH/%EM)\t%m\n"`::
  For each appointment list the (total) duration as either days, hours or
  minutes followed by the description.

`calcurse -G --filter-type apt --format-apt "%(start:%c) %(duration:%d %H:%M)\t%m\n"`::
  For each appointment list the start time in a localized standard format,
  followed by the duration in days, hours and minutes, followed by the
  description.

FILES
-----

The following structure is created by default in your home directory the
first time calcurse is run without any options:

----
$XDG_DATA_HOME/calcurse/        $XDG_CONFIG_HOME/calcurse/
                  |___apts                          |___conf
                  |___notes/                        |___hooks/
                  |___todo                          |___keys
----

+$XDG_DATA_HOME+ defaults to +\~/.local/share+ and +$XDG_CONFIG_HOME+ defaults to
+~/.config+.

The files are of two different kinds: data and configuration. The data files
constitute the calcurse database and are independent of the calcurse release
version; the configuration files depend on the calcurse version although
backwards compatibility is always aimed at.

Data files
~~~~~~~~~~

The calendar file +apts+ contains all of the user's appointments and events,
and the +todo+ file contains the todo list.  The +notes+ subdirectory contains
the notes which are attached to appointments, events or todos.  One text file
is created per note, whose name is the SHA1 message digest of the note itself.

The (hidden) lock files of the calcurse (+.calcurse.pid+) and daemon
(+.daemon.log+) programs are present when they are running.  If daemon log
activity has been enabled in the notification configuration menu, the file
+daemon.log+ is present.

An alternative calendar file may be specified with the *-c* option.

Configuration files
~~~~~~~~~~~~~~~~~~~

The +conf+ file contains the user configuration and the +keys+ file
the user-defined key bindings. The +hooks+ directory contains user-supplied
scripts, see <<_hooks,Hooks>>.

Directory configuration
~~~~~~~~~~~~~~~~~~~~~~~

An alternative directory to the defaults +$XDG_DATA_HOME/calcurse+
(+$HOME/.local/share/calcurse+) and +$XDG_CONFIG_HOME/calcurse+
(+$HOME/.config/calcurse+) may be specified with the *-D* option.

An alternative directory for the configuration files 'only' may be specified
with the *-C* option; in that case data files are either in the default
directory or in the directory specified by *-D*. If both *-D* and
*-C* are present, configuration files in the data directory, if any, are
ignored.

If +$HOME/.calcurse+ exists, then it will be used as the default for both the
data directory and the configuration directory.

----
<datadir>      <confdir>
     |             |
     |__ apts      |___ conf
     |__ todo      |___ keys
     |__ notes/    |___ hooks/

defaults:
     <datadir>: $XDG_DATA_HOME/calcurse ($HOME/.local/share/calcurse)
     <confdir>: $XDG_CONFIG_HOME/calcurse ($HOME/.config/calcurse)
     both: $HOME/.calcurse (only if it exists)
----

calcurse may switch between two configuration setups, but still access
the same data files e.g. with:

----
$ calcurse

$ calcurse -C "$HOME/.config/calcurse/config"
----

Hooks
~~~~~

Scripts placed in +$XDG_CONFIG_HOME/calcurse/hooks/+
(+$HOME/.config/calcurse/hooks+) trigger actions at certain events. To enable a
hook, add a script with one of the following names to this directory. Also make
sure the script is executable.

*pre-load*::
  Executed before the data files are loaded.
*post-load*::
  Executed after the data files are loaded.
*pre-save*::
  Executed before the data files are saved.
*post-save*::
  Executed after the data files are saved.

Some examples can be found in the +contrib/hooks/+ directory of the calcurse
source tree.

ENVIRONMENT
-----------

A few environment variables affect how calcurse operates.

*CALCURSE_EDITOR*::
*VISUAL*::
*EDITOR*::
  Specifies the external editor to use for writing notes. They are tried in
  the order listed until one is found. If none of them are set, +vi+ is used.

*CALCURSE_PAGER*::
*PAGER*::
  Specifies - as for the editor - the default viewer to be used for reading
  notes. Default is +less+.

*MERGETOOL*::
  Tool used to merge two files to solve a save conflict. Default is +vimdiff+.
  The program is called with two file names as the only arguments.

BUGS
----

If you find a bug, please send a report to bugs@calcurse.org, or, if you are a
Github user, raise an issue at https://github.com/lfos/calcurse.

SEE ALSO
--------

The ical specification (rfc2445) can be found at:
http://tools.ietf.org/html/rfc2445

The pcal project page: http://pcal.sourceforge.net/

calcurse home page: http://calcurse.org/

calcurse at GitHub: https://github.com/lfos/calcurse

The complete manual, maintained in html format, can be found in the doc/
directory of the source package, or at: http://calcurse.org/files/manual.html

AUTHORS
-------

* *Frederic Culot* <frederic@culot.org>
* *Lukas Fleischer* <lfleischer@calcurse.org>

COPYRIGHT
---------

Copyright (c) 2004-2018 calcurse Development Team.
This software is released under the BSD License.