From 65963f96e8fd1c43ec1b82dda8e6a7ed51b87794 Mon Sep 17 00:00:00 2001 From: Lukas Fleischer <calcurse@cryptocrack.de> Date: Sat, 7 Feb 2015 10:39:29 +0100 Subject: Document new options Document the query and grep modes, as well as the new filter interface, in the man page and in the user manual. Signed-off-by: Lukas Fleischer <calcurse@cryptocrack.de> --- doc/calcurse.1.txt | 127 +++++++++++++++++++++++++++++++++++++++++++++++ doc/manual.txt | 143 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 270 insertions(+) (limited to 'doc') diff --git a/doc/calcurse.1.txt b/doc/calcurse.1.txt index 4b10d80..86a2747 100644 --- a/doc/calcurse.1.txt +++ b/doc/calcurse.1.txt @@ -98,10 +98,60 @@ menu. Four formats are available: 'Note:' as for the *-a* flag, the calendar from which to read the appointments can be specified using the *-c* flag. +*--days* <num>:: + Specify the length of the range (in days) when used with *-Q*. Cannot be + combined with *--to*. + *-D* <dir>, *--directory* <dir>:: Specify the data directory to use. If not specified, the default directory is *~/.calcurse/*. +*--filter-type* <type>:: + Ignore any items that do not match the type mask. See 'FILTERS' for details. + +*--filter-pattern* <pattern>:: + Ignore any items with a description that does not match the pattern. See + 'FILTERS' for details. + +*--filter-start-from* <date>:: + Ignore any items that start before a given date. See 'FILTERS' for details. + +*--filter-start-to* <date>:: + Ignore any items that start after a given date. See 'FILTERS' for details. + +*--filter-start-after* <date>:: + Only include items that start after a given date. See 'FILTERS' for details. + +*--filter-start-before* <date>:: + Only include items that start before a given date. See 'FILTERS' for details. + +*--filter-start-range* <range>:: + Only include items within a given range. See 'FILTERS' for details. + +*--filter-end-from* <date>:: + Ignore any items that end before a given date. See 'FILTERS' for details. + +*--filter-end-to* <date>:: + Ignore any items that end after a given date. See 'FILTERS' for details. + +*--filter-end-after* <date>:: + Only include items that end after a given date. See 'FILTERS' for details. + +*--filter-end-before* <date>:: + Only include items that end before a given date. See 'FILTERS' for details. + +*--filter-end-range* <range>:: + Only include items within a given range. See 'FILTERS' for details. + +*--filter-priority* <priority>:: + Only include items with a given priority. See 'FILTERS' for details. + +*--filter-completed*:: + Only include completed TODO items. See 'FILTERS' for details. + +*--filter-uncompleted*:: + Only include uncompleted TODO items. See 'FILTERS' for details. + *--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 @@ -125,9 +175,17 @@ appointments can be specified using the *-c* flag. 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. +*--from* <date>:: + Specify the start date of the range when used with *-Q*. + *-g*, *--gc*:: Run the garbage collector for note files and exit. +*-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: + 'FILTERS'. + *-h*, *--help*:: Print a short help text describing the supported command-line options, and exit. @@ -145,6 +203,12 @@ appointments can be specified using the *-c* flag. 'Note:' the calendar from which to read the appointments can be specified using the *-c* flag. +*-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: 'FILTERS'. + *-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. @@ -175,6 +239,10 @@ in read-only mode, all changes from this session will be lost without warning! specify *0* for the priority, in which case only completed tasks will be shown. +*--to* <date>:: + Specify the end date of the range when used with *-Q*. Cannot be combined + with *--days*. + *-v*, *--version*:: Display *calcurse* version and exit. @@ -194,6 +262,65 @@ $ calcurse --export > my_data.dat '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. +Filters +------- + +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: + +*--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'. + +*--filter-pattern* <pattern>:: + Ignore any items with a description that does not match the pattern. The + pattern is interpreted as extended regular expression. + +*--filter-start-from* <date>:: + Ignore any items that start before a given date. + +*--filter-start-to* <date>:: + Ignore any items that start after a given date. + +*--filter-start-after* <date>:: + Only include items that start after a given date. + +*--filter-start-before* <date>:: + Only include items that start before a given date. + +*--filter-start-range* <range>:: + Only include items with a start date that falls within 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-to* <date>:: + Ignore any items that end after a given date. + +*--filter-end-after* <date>:: + Only include items that end after a given date. + +*--filter-end-before* <date>:: + Only 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 + consists of a start date and an end date, separated by a comma. + +*--filter-priority* <priority>:: + Only include items with a given priority. + +*--filter-completed*:: + Only include completed TODO items. + +*--filter-uncompleted*:: + Only include uncompleted TODO items. + Format strings -------------- diff --git a/doc/manual.txt b/doc/manual.txt index ffc0dd5..1a99f32 100644 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -200,10 +200,74 @@ menu (see <<options_general,General options>>), using the Note: as for the `-a` flag, the calendar from which to read the appointments can be specified using the `-c` flag. +`--days <num>`:: + Specify the length of the range (in days) when used with `-Q`. Cannot be + combined with `--to`. + `-D <dir>, --directory <dir>`:: Specify the data directory to use. If not specified, the default directory is `~/.calcurse/`. +`--filter-type <type>`:: + Ignore any items that do not match the type mask. See + <<basics_filters,Filters>> for details. + +`--filter-pattern <pattern>`:: + Ignore any items with a description that does not match the pattern. See + <<basics_filters,Filters>> for details. + +`--filter-start-from <date>`:: + Ignore any items that start before a given date. See + <<basics_filters,Filters>> for details. + +`--filter-start-to <date>`:: + Ignore any items that start after a given date. See + <<basics_filters,Filters>> for details. + +`--filter-start-after <date>`:: + Only include items that start after a given date. See + <<basics_filters,Filters>> for details. + +`--filter-start-before <date>`:: + Only include items that start before a given date. See + <<basics_filters,Filters>> for details. + +`--filter-start-range <range>`:: + Only include items within a given range. See <<basics_filters,Filters>> for + details. + +`--filter-end-from <date>`:: + Ignore any items that end before a given date. See <<basics_filters,Filters>> + for details. + +`--filter-end-to <date>`:: + Ignore any items that end after a given date. See <<basics_filters,Filters>> + for details. + +`--filter-end-after <date>`:: + Only include items that end after a given date. See + <<basics_filters,Filters>> for details. + +`--filter-end-before <date>`:: + Only include items that end before a given date. See + <<basics_filters,Filters>> for details. + +`--filter-end-range <range>`:: + Only include items within a given range. See <<basics_filters,Filters>> for + details. + +`--filter-priority <priority>`:: + Only include items with a given priority. See <<basics_filters,Filters>> for + details. + +`--filter-completed`:: + Only include completed TODO items. See <<basics_filters,Filters>> for + details. + +`--filter-uncompleted`:: + Only include uncompleted TODO items. See <<basics_filters,Filters>> for + details. + `--format-apt <format>`:: Specify a format to control the output of appointments in non-interactive mode. See the <<basics_format_strings,Format strings>> section for detailed @@ -229,9 +293,17 @@ can be specified using the `-c` flag. See the <<basics_format_strings,Format strings>> section for detailed information on format strings. +`--from <date>`:: + Specify the start date of the range when used with `-Q`. + `-g, --gc`:: Run the garbage collector for note files and exit. +`-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: + <<basics_filters,Filters>>. + `-h, --help`:: Print a short help text describing the supported command-line options, and exit. @@ -249,6 +321,13 @@ can be specified using the `-c` flag. Note: the calendar from which to read the appointments can be specified using the `-c` flag. +`-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: + <<basics_filters,Filters>>. + `-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. @@ -279,6 +358,10 @@ in read-only mode, all changes from this session will be lost without warning! specify `0` for the priority, in which case only completed tasks will be shown. +`--to <date>`:: + Specify the end date of the range when used with `-Q`. Cannot be combined + with `--days`. + `-v, --version`:: Display `calcurse` version and exit. @@ -299,6 +382,66 @@ NOTE: The `-N` option has been removed in calcurse 3.0.0. See the <<basics_format_strings,Format strings>> section on how to print note along with appointments and events. +[[basics_filters]] +Filters +^^^^^^^ + +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: + +`--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`. + +`--filter-pattern <pattern>`:: + Ignore any items with a description that does not match the pattern. The + pattern is interpreted as extended regular expression. + +`--filter-start-from <date>`:: + Ignore any items that start before a given date. + +`--filter-start-to <date>`:: + Ignore any items that start after a given date. + +`--filter-start-after <date>`:: + Only include items that start after a given date. + +`--filter-start-before <date>`:: + Only include items that start before a given date. + +`--filter-start-range <range>`:: + Only include items with a start date that falls within 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-to <date>`:: + Ignore any items that end after a given date. + +`--filter-end-after <date>`:: + Only include items that end after a given date. + +`--filter-end-before <date>`:: + Only 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 + consists of a start date and an end date, separated by a comma. + +`--filter-priority <priority>`:: + Only include items with a given priority. + +`--filter-completed`:: + Only include completed TODO items. + +`--filter-uncompleted`:: + Only include uncompleted TODO items. + [[basics_format_strings]] Format strings ^^^^^^^^^^^^^^ -- cgit v1.2.3-70-g09d2