From 19d2d9229e62ea5e993b462f0cdedd868ec6c2d9 Mon Sep 17 00:00:00 2001 From: Nitroretro Date: Tue, 17 Dec 2019 17:24:48 +0200 Subject: Change documentation to reflect the new file structure Signed-off-by: Lukas Fleischer --- doc/calcurse.1.txt | 55 ++++++++++++++++++++++++++++++++---------------------- doc/manual.txt | 47 +++++++++++++++++++++++----------------------- doc/save.txt | 12 ++++++++---- 3 files changed, 65 insertions(+), 49 deletions(-) (limited to 'doc') diff --git a/doc/calcurse.1.txt b/doc/calcurse.1.txt index 13297cf..2493357 100644 --- a/doc/calcurse.1.txt +++ b/doc/calcurse.1.txt @@ -95,7 +95,7 @@ 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 +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 @@ -143,19 +143,22 @@ are marked "('also interactively')". *-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*. + 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 *~/.calcurse/*. See <<_files,FILES>> for - the interaction with *-D*. + 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 *~/.calcurse/*. See section <<_files,FILES>> for - the interaction with *-C*. + 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, @@ -622,15 +625,15 @@ The following structure is created by default in your home directory the first time calcurse is run without any options: ---- -$HOME/.calcurse/ - |___apts - |___conf - |___hooks/ - |___keys - |___notes/ - |___todo +$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 @@ -661,8 +664,9 @@ scripts, see <<_hooks,Hooks>>. Directory configuration ~~~~~~~~~~~~~~~~~~~~~~~ -An alternative directory to the default +$HOME/.calcurse+ may be specified -with the *-D* option. +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 @@ -670,6 +674,9 @@ 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. + ---- | | @@ -677,7 +684,10 @@ ignored. |__ todo |___ keys |__ notes/ |___ hooks/ -default for both: $HOME/.calcurse/ +defaults: + : $XDG_DATA_HOME/calcurse ($HOME/.local/share/calcurse) + : $XDG_CONFIG_HOME/calcurse ($HOME/.config/calcurse) + both: $HOME/.calcurse (only if it exists) ---- calcurse may switch between two configuration setups, but still access @@ -686,15 +696,16 @@ the same data files e.g. with: ---- $ calcurse -$ calcurse -C "$HOME/.calcurse/config" +$ calcurse -C "$HOME/.config/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. +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. diff --git a/doc/manual.txt b/doc/manual.txt index ff5131f..5091e73 100644 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -176,9 +176,10 @@ long options are supported): be specified using the `-c` flag. `-c , --calendar `:: - Specify the calendar file to use. The default calendar is `~/.calcurse/apts` - (see section <>). This option has precedence - over `-D`. + Specify the calendar file to use. The default calendar is + `$XDG_DATA_HOME/calcurse/apts` (`~/.local/share/calcurse/apts`) or + `~/.calcurse/apts` if `~/.calcurse` exists. (see section + <>). This option has precedence over `-D`. `-d , --day `:: Print the appointments for the given date or for the given number of @@ -210,7 +211,8 @@ can be specified using the `-c` flag. `-D , --directory `:: Specify the data directory to use. If not specified, the default directory is - `~/.calcurse/`. + `$XDG_DATA_HOME/calcurse/` (`~/.local/share/calcurse/`) or `~/.calcurse` if + it exists. `--filter-type `:: Ignore any items that do not match the type mask. See @@ -635,9 +637,10 @@ The following environment variables affect the way `calcurse` operates: Hooks ~~~~~ -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. +You can place scripts in `$XDG_CONFIG_HOME/calcurse/hooks/` +(`$HOME/.config/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. *pre-load*:: Executed before the data files are loaded. @@ -850,17 +853,15 @@ NOTE: To stop the daemon, just send the `TERM` signal to it, using a command calcurse 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 in your `$XDG_CONFIG_HOME` (`$HOME/.config`) +and in your `$XDG_DATA_HOME` (`$HOME/.local/share`) directories (or in the +directory you specified with the -D option) the first time calcurse is run: ---- -$HOME/.calcurse/ - |___notes/ - |___conf - |___keys - |___apts - |___todo +$XDG_DATA_HOME/calcurse/ $XDG_CONFIG_HOME/calcurse/ + |___notes/ |___conf + |___apts |___keys + |___todo ---- `notes/`:: this subdirectory contains descriptions of the notes which are attached to @@ -868,19 +869,19 @@ $HOME/.calcurse/ SHA1 hash of the note itself, multiple items can share the same note file. calcurse provides a garbage collector (see the `-g` command line parameter) that can be used to remove note files which are no longer linked to any item. -`conf`:: - this file contains the user configuration -`keys`:: - this file contains the user-defined key bindings `apts`:: this file contains all of the events and user's appointments `todo`:: this file contains the todo list +`conf`:: + this file contains the user configuration +`keys`:: + this file contains the user-defined key bindings 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. + configuration menu, the extra file `daemon.log` will appear in the + calcurse data directory. This file contains logs about calcurse activity + when running in background. Import/Export capabilities ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/save.txt b/doc/save.txt index 9c453ba..780df9b 100644 --- a/doc/save.txt +++ b/doc/save.txt @@ -5,11 +5,15 @@ Save calcurse data. Data are split into four different files which contain : - / ~/.calcurse/conf -> user configuration + / $XDG_CONFIG_HOME/calcurse/conf -> user configuration | (layout, color, general options) - | ~/.calcurse/apts -> data related to the appointments - | ~/.calcurse/todo -> data related to the todo list - \ ~/.calcurse/keys -> user-defined key bindings + | $XDG_DATA_HOME/calcurse/apts -> data related to the appointments + | $XDG_DATA_HOME/calcurse/todo -> data related to the todo list + \ $XDG_CONFIG_HOME/calcurse/keys -> user-defined key bindings + +Defaults: +- datadir: $XDG_DATA_HOME/calcurse (~/.local/share/calcurse) +- configdir: $XDG_CONFIG_HOME/calcurse (~/.config/calcurse) In the config menu, you can choose to save the calcurse data automatically before quitting. -- cgit v1.2.3-70-g09d2