aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/calcurse.1.txt938
1 files changed, 576 insertions, 362 deletions
diff --git a/doc/calcurse.1.txt b/doc/calcurse.1.txt
index 08505e9..b690e2d 100644
--- a/doc/calcurse.1.txt
+++ b/doc/calcurse.1.txt
@@ -30,519 +30,733 @@
*/
////
-calcurse(1)
+CALCURSE(1)
===========
-Name
+NAME
----
-calcurse - text-based organizer
+calcurse - terminal-based organizer for interactive and command line use
-Synopsis
+SYNOPSIS
--------
-[verse]
-'calcurse' *-Q* [options] [*--from* <date>] [*--to* <date>|*--days* <num>]
-'calcurse' *-G* [options]
-'calcurse' *-i*<file>
-'calcurse' *-x*<format>
-'calcurse' *--gc*
-'calcurse' *--status*
-'calcurse' *--version*
-'calcurse' *--help*
-
-Description
------------
+--
+*calcurse* [-D 'directory'] [-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.
-Calcurse is a text-based calendar and scheduling application. It helps keeping
-track of events, appointments and everyday tasks. A configurable notification
-system reminds user of upcoming deadlines, and the curses based interface can
-be customized to suit user needs. All of the commands are documented within an
-online help system.
+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.
-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
+subsectiions 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
-------
-The following options are supported:
+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 and exit. Equivalent to
- *-Q --filter-type cal*. 'Note:' The calendar from which to read the
- appointments can be specified using the *-c* flag.
-
-*-c* <file>, *--calendar* <file>::
- Specify the calendar file to use. The default calendar is *~/.calcurse/apts*
- (see section 'FILES' below). This option has precedence over *-D*.
-
-*-d* <date|num>, *--day* <date|num>::
- Print the appointments for the given date or for the given number of
- upcoming days, depending on the argument format. Two possible formats are
- supported:
+ 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 *~/.calcurse/apts* (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', *--conf* 'dir'::
+ ('also interactively') Specify the configuration directory to use. If not
+ specified, the default directory is *~/.calcurse/*. See <<_files,FILES>> for
+ the interaction with *-D*.
+
+*-D* 'dir', *--directory* 'dir'::
+ ('also interactively') Specify the (data) directory to use. If not specified,
+ the default directory is *~/.calcurse/*. 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 (possible formats described below).
- * a number *n*.
+ * a 'date'
+ * a number 'num'
--
+
-In the first case, the appointment list for the specified date will be
-returned, while in the second case the appointment list for the *n* upcoming
-days will be returned.
-+
-As an example, typing *calcurse -d 3* will display your appointments for
-today, tomorrow, and the day after tomorrow. The first form is equivalent to
-*-Q --filter-type cal --from <date>*, the second form is equivalent to *-Q
---filter-type cal --days <num>*.
-+
-'Note:' as for the *-a* flag, the calendar from which to read the
-appointments can be specified using the *-c* flag.
+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.
+ 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>>.
-*--days* <num>::
- Specify the length of the range (in days) when used with *-Q*. Cannot be
- combined with *--to*.
+*--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.
-*-D* <dir>, *--directory* <dir>::
- Specify the data directory to use. If not specified, the default directory is
- *~/.calcurse/*.
+*--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*::
- Read items from the data files and write them back. The filter interface can
- be used to drop specific items. Be careful with this option, specifying a
- wrong filter might result it data loss! It is highly recommended to test the
- effect of filters with -G first. See also: 'Filter Options'.
-
-*--from* <date>::
- Specify the start date of the range when used with *-Q*.
+ 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 and exit.
+ 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 and TODO items using the calcurse data file format. The
- filter interface can be used to further restrict the output. See also:
- 'Filter Options'.
+ Print appointments, events and TODO items in calcurse data file format.
*-h*, *--help*::
- Print a short help text describing the supported command-line options,
- and exit.
+ Print a short help text describing the supported command-line options.
-*-i* <file>, *--import* <file>::
+*-i* 'file', *--import* 'file'::
Import the icalendar data contained in 'file'.
-*-l* <num>, *--limit* <num>::
- Limit the number of results printed to 'num'.
+*--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.
-*--dump-imported*::
- When importing items, print each newly created object to stdout. Format
- strings can be used to specify which details are printed. See also:
- 'Formatting Options'.
+*-l* 'num', *--limit* 'num'::
+ Limit the number of results printed to 'num'.
*-n*, *--next*::
- Print the next appointment within upcoming 24 hours and exit. The indicated
- time is the number of hours and minutes left before this appointment.
+ 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.
+
-'Note:' the calendar from which to read the appointments can be specified using
-the *-c* flag.
+'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*::
- Be quiet. Do not show system dialogs.
+ ('also interactively') Be quiet. Do not show system dialogs.
-*-Q*, *--query*::
- Print all appointments inside a given query range, followed by all TODO
- items. The query range defaults to the current day and can be changed by
- using the *--from* and *--to* (or *--days*) parameters. The filter interface
- can be used to further restrict the output. See also: 'Filter Options',
- 'Formatting Options'.
+*-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 events and appointments for the 'num' number of days and exit. If no
- 'num' is given, a range of 1 day is considered. Equivalent to *-Q
- --filter-type cal --days <num>*.
+*-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*::
- Don't save configuration nor appointments/todos.
+ ('also interactively') Do not save configuration nor appointments and todos.
+
-'Warning:' Use this this with care! If you run an interactive calcurse instance
-in read-only mode, all changes from this session will be lost without warning!
+'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 'date' and exit. If no 'date' is given,
- the current day is considered. Equivalent to *-Q --filter-type cal --from
- <date>*.
+*-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 the *-a*, *-d*, *-r*, *-s*, or *-t* flag, print only the items
- having a description that matches the given regular expression. Equivalent to
- *-Q --filter-pattern <regex>*.
+*-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. If calcurse is
- running, this will tell if the interactive mode was launched or if
- calcurse is running in background. The process pid will also be indicated.
-
-*-t*[num], *--todo*[=num]::
- Print the *todo* list and exit. If the optional number 'num' is given, then
- only uncompleted 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 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 range when used with *-Q*. Cannot be combined
- with *--days*.
+ 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 and exit.
+ Display *calcurse* version.
-*-x*[format], *--export*[=format]::
- Export user data to specified format. Events, appointments and todos are
- converted and echoed to stdout. Two possible formats are available: 'ical'
- and 'pcal'. If the optional argument 'format' is not given, ical format is
- selected by default.
-+
-'Note:' redirect standard output to export data to a file, by issuing a command
-such as:
-+
-----
-$ calcurse --export > my_data.dat
-----
+*-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+.
-'Note:' The *-N* option has been removed in calcurse 3.0.0. See the 'FORMAT
-STRINGS' section on how to print note along with appointments and events.
+*--filter-pattern* 'pattern'::
+ Include items with a description that matches the pattern. The pattern is
+ interpreted as an extended regular expression.
-Filter Options
-~~~~~~~~~~~~~~
+*--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>>.
-Filters can be used to restrict the set of items which are loaded from the
-appointments file when using calcurse in non-interactive mode. The following
-filters are currently supported:
+Calendar filters
+~~~~~~~~~~~~~~~~
-*--filter-hash <pattern>*::
- Only include items with a hash starting with the specified pattern. The
- pattern can be inverted by prepending an exclamation mark ('!').
+For filter options ending in *-from*, *-to*, *-after*, *-before* and *-range*,
+start or end time is the filter criterion.
-*--filter-type* <type>::
- Ignore any items that do not match the type mask. The type mask is a
- comma-separated list of valid type descriptions which include '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'.
+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).
-*--filter-pattern* <pattern>::
- Ignore any items with a description that does not match the pattern. The
- pattern is interpreted as extended regular expression.
+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.
-*--filter-start-from* <date>::
- Ignore any items that start before a given date.
+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-to* <date>::
- Ignore any items that start after a given date.
+*--filter-start-from* 'date'::
+ Include items that start at or after a given date.
-*--filter-start-after* <date>::
- Only include items that start after a given date.
+*--filter-start-to* 'date'::
+ Include items that start at or before a given date.
-*--filter-start-before* <date>::
- Only include items that start before a given date.
+*--filter-start-after* 'date'::
+ Include items that start after a given date.
-*--filter-start-range* <range>::
- Only include items with a start date that falls within a given range. A range
+*--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>::
- Ignore any items that end before a given date.
+*--filter-end-from* 'date'::
+ Include items that end at or after a given date.
-*--filter-end-to* <date>::
- Ignore any items that end after a given date.
+*--filter-end-to* 'date'::
+ Include items that end at or before a given date.
-*--filter-end-after* <date>::
- Only include items that end after a given date.
+*--filter-end-after* 'date'::
+ Include items that end after a given date.
-*--filter-end-before* <date>::
- Only include items that end before a given date.
+*--filter-end-before* 'date'::
+ Include items that end before a given date.
-*--filter-end-range* <range>::
- Only include items with an end date that falls within a given range. A range
+*--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.
-*--filter-priority* <priority>::
- Only include items with a given priority.
+Todo filters
+~~~~~~~~~~~~
+
+*--filter-priority* 'priority'::
+ Include TODO items with a given priority.
*--filter-completed*::
- Only include completed TODO items.
+ Include completed TODO items.
*--filter-uncompleted*::
- Only include uncompleted TODO items.
+ Include uncompleted TODO items.
-Formatting Options
-~~~~~~~~~~~~~~~~~~
+FORMAT OPTIONS
+--------------
-*--format-apt* <format>::
- Specify a format to control the output of appointments in non-interactive
- mode. See the 'FORMAT STRINGS' section for detailed information on format
- strings.
+Format options have effect on queries, grep and *--dump-imported*.
-*--format-recur-apt* <format>::
- Specify a format to control the output of recurrent appointments in
- non-interactive mode. See the 'FORMAT STRINGS' section for detailed
- information on format strings.
+The options specify a format for appointments, recurring appointments, events,
+recurring events or todo items, respectively.
-*--format-event* <format>::
- Specify a format to control the output of events in non-interactive mode. See
- the 'FORMAT STRINGS' section for detailed information on format strings.
+*--format-apt* 'format'::
-*--format-recur-event* <format>::
- Specify a format to control the output of recurrent events in non-interactive
- mode. See the 'FORMAT STRINGS' section for detailed information on format
- strings.
+*--format-recur-apt* 'format'::
-*--format-todo* <format>::
- Specify a format to control the output of todo items in non-interactive mode.
- See the 'FORMAT STRINGS' section for detailed information on format strings.
+*--format-event* 'format'::
-Format strings
---------------
+*--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
+~~~~~~~~~~~~~~~~~~~~~~
-Format strings are composed of printf()-style format specifiers -- ordinary
-characters are copied to stdout without modification. Each specifier is
-introduced by a *%* and is followed by a character which specifies the field to
-print. The set of available fields depends on the item type.
+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>>.
-Format specifiers for appointments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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:
-*s*::
- Print the start time of the appointment as UNIX time stamp
-*S*::
- Print the start time of the appointment using the *hh:mm* format
-*d*::
+ --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 UNIX time stamp
-*E*::
- Print the end time of the appointment using the *hh:mm* format
-*m*::
+*%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*::
+*%n*::
Print the name of the note file belonging to the item
-*N*::
+*%N*::
Print the note belonging to the item
-
-Format specifiers for events
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*m*::
+*%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*::
+*%n*::
Print the name of the note file belonging to the item
-*N*::
+*%N*::
Print the note belonging to the item
-Format specifiers for todo items
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Todo items
+~~~~~~~~~~
-*p*::
- Print the priority of the item
-*m*::
+*%m*::
Print the description of the item
-*n*::
+*%n*::
Print the name of the note file belonging to the item
-*N*::
+*%N*::
Print the note belonging to the item
+*%p*::
+ Print the priority of the item
-Examples
-~~~~~~~~
+Extended format specifiers
+~~~~~~~~~~~~~~~~~~~~~~~~~~
-*`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 (simulates *-N* for appointments).
+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.
-*`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)*.
+*%(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
-*`calcurse -t --format-todo '(%p) %m\n'`*::
- List all todo items and put parentheses around the priority specifiers.
+*%(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
-Extended format specifiers
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+*%(hash)*::
+ the (SHA1) hash of the above; can be used with all format options
-Extended format specifiers can be used if you want to specify advanced
-formatting options. Extended specifiers are introduced by *%(* and are
-terminated by a closing parenthesis (*)*). The following list includes all
-short specifiers and corresponding long options:
-
-* *s*: *(start)*
-* *S*: *(start:epoch)*
-* *e*: *(end)*
-* *E*: *(end:epoch)*
-* *d*: *(duration)*
-* *r*: *(remaining)*
-* *m*: *(message)*
-* *n*: *(noteid)*
-* *N*: *(note)*
-* *p*: *(priority)*
-
-The *(start)* and *(end)* specifiers support strftime()-style extended
-formatting options that can be used for fine-grained formatting. Additionally,
-the special formats *epoch* (which is equivalent to *(start:%s)* or *(end:%s)*)
-and *default* (which is mostly equivalent to *(start:%H:%M)* or *(end:%H:%M)*
-but displays *..:..* if the item doesn't start/end at the current day) are
-supported.
-
-The *(remaining)* and *(duration)* specifiers support a subset of the
-strftime()-style formatting options, along with two extra qualifiers.
-The supported options are *%d*, *%H*, *%M* and *%S*, and by default each
-of these is zero-padded to two decimal places. To avoid the
-zero-padding, add *-* in front of the formatting option (for example,
-*%-d*). Additionally, the *E* option will display the total number of
-time units until the appointment, rather than showing the remaining
-number of time units modulo the next larger time unit. For example, an
-appointment in 50 hours will show as 02:00 with the formatting string
-*%H:%M*, but will show 50:00 with the formatting string *%EH:%M*. Note
-that if you are combining the *-* and *E* options, the *-* must come
-first. The default format for the *(remaining)* specifier is *%EH:%M*.
-
-There are two additional long format specifiers that do not have any
-corresponding short options. They can be used to print an item's hash or its
-internal representation and were designed to be used for scripting:
-
-* *(hash)*
-* *(raw)*
+EXAMPLES
+--------
-Hooks
------
+`calcurse -d tomorrow`::
+ Display the calendar for tomorrow (same as `calcurse -Q --filter-type
+ cal --from tomorrow`).
-You can place scripts in `$HOME/.calcurse/hooks/` to 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 scripts are executable.
+`calcurse -d friday`::
+ Display the calendar for the upcoming friday.
-*pre-load*::
- Executed before the data files are loaded.
-*post-load*::
- Executed after the data files are saved.
-*pre-save*::
- Executed before the data files are loaded.
-*post-save*::
- Executed after the data files are saved.
+`calcurse -d 7`::
+ Display the calendar for the next seven days (same as `calcurse -Q
+ -filter-type cal --days 7`).
-Some examples can be found in the `contrib/hooks/` directory of the calcurse
-source tree.
+`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.
-Notes
------
+`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.
-Calcurse interface contains three different panels (calendar, appointment list,
-and todo list) on which you can perform different actions. All the possible
-actions, together with their associated keystrokes, are listed on the status
-bar. This status bar takes place at the bottom of the screen.
+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.
-At any time, the built-in help system can be invoked by pressing the '?' key.
-Once viewing the help screens, informations on a specific command can be
-accessed by pressing the keystroke corresponding to that command.
+`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.
-Configuration
--------------
+`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.
-The calcurse options can be changed from the configuration menu (shown when 'C'
-is hit). Five possible categories are to be chosen from : the color scheme, the
-layout (the location of the three panels on the screen), notification options,
-key bindings configuration menu, and more general options (such as automatic
-save before quitting). All of these options are detailed in the configuration
-menu.
+`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.
-Files
+`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 in your $HOME directory (or in the directory
-you specified with the *-D* option), the first time calcurse is run:
+The following structure is created by default in your home directory the
+first time calcurse is run without any options:
----
$HOME/.calcurse/
- |___notes/
- |___conf
+ |___apts
+ |___conf
+ |___hooks/
|___keys
- |___apts
+ |___notes/
|___todo
----
-The 'notes' subdirectory contains descriptions of 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 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>>.
-The 'conf' file contains the user configuration. The 'keys' file contains the
-user-defined key bindings. The 'apts' file contains all of the user's
-appointments and events, and the 'todo' file contains the todo list.
+Directory configuration
+~~~~~~~~~~~~~~~~~~~~~~~
-'Note:' if the logging of calcurse daemon activity was set in the notification
-configuration menu, the extra file 'daemon.log' will appear in calcurse data
-directory. This file contains logs about calcurse activity when running in
-background.
+An alternative directory to the default +$HOME/.calcurse+ may be specified
+with the *-D* option.
-Environment
+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.
+
+----
+<datadir> <confdir>
+ | |
+ |__ apts |___ conf
+ |__ todo |___ keys
+ |__ notes/ |___ hooks/
+
+default for both: $HOME/.calcurse/
+----
+
+calcurse may switch between two configuration setups, but still access
+the same data files e.g. with:
+
+----
+$ calcurse
+
+$ calcurse -C "$HOME/.calcurse/config"
+----
+
+Hooks
+~~~~~
+
+Scripts placed in +$HOME/.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
-----------
-This section describes the environment variables that affect how calcurse
-operates.
+A few environment variables affect how calcurse operates.
+*CALCURSE_EDITOR*::
*VISUAL*::
- Specifies the external editor to use for writing notes.
*EDITOR*::
- If the 'VISUAL' environment variable is not set, then 'EDITOR' will be used
- as the default external editor. If none of those variables are set, then
- '/usr/bin/vi' is used instead.
-*PAGER*::
- Specifies the default viewer to be used for reading notes. If this variable
- is not set, then '/usr/bin/less' is used.
+ 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.
-Bugs
-----
+*CALCURSE_PAGER*::
+*PAGER*::
+ Specifies - as for the editor - the default viewer to be used for reading
+ notes. Default is +less+.
-Incorrect highlighting of items appear when using calcurse black and white
-theme together with a *$TERM* variable set to 'xterm-color'. To fix this bug,
-and as advised by Thomas E. Dickey (xterm maintainer), 'xterm-xfree86' should
-be used instead of 'xterm-color' to set the *$TERM* variable:
+*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.
- "The xterm-color value for $TERM is a bad choice for
- XFree86 xterm because it is commonly used for a
- terminfo entry which happens to not support bce.
- Use the xterm-xfree86 entry which is distributed
- with XFree86 xterm (or the similar one distributed
- with ncurses)."
+BUGS
+----
-If you find other bugs, please send a report to bugs@calcurse.org or to one of
-the authors, below.
+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
+SEE ALSO
--------
-vi(1), less(1), ncurses(3), mkstemp(3)
-
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 home page: http://calcurse.org/
+
+calcurse at GitHub: https://github.com/lfos/calcurse
-Calcurse complete manual, translated in many languages and maintained in
-html format, can be found in the doc/ directory of the source package,
-or at: http://calcurse.org/files/manual.html
+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
+AUTHORS
-------
* *Frederic Culot* <frederic@culot.org>
* *Lukas Fleischer* <lfleischer@calcurse.org>
-Copyright
+COPYRIGHT
---------
-Copyright (c) 2004-2017 calcurse Development Team.
+Copyright (c) 2004-2018 calcurse Development Team.
This software is released under the BSD License.