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 --- contrib/caldav/README.md | 28 ++++++++++++--------- contrib/caldav/config.sample | 9 +++++-- contrib/caldav/hooks/post-sync | 4 ++- contrib/hooks/post-save | 4 ++- contrib/hooks/pre-load | 4 ++- contrib/vdir/README.md | 3 ++- doc/calcurse.1.txt | 55 +++++++++++++++++++++++++----------------- doc/manual.txt | 47 ++++++++++++++++++------------------ doc/save.txt | 12 ++++++--- src/io.c | 11 ++++++--- test/README | 2 +- 11 files changed, 109 insertions(+), 70 deletions(-) diff --git a/contrib/caldav/README.md b/contrib/caldav/README.md index b6f6cbf..a842081 100644 --- a/contrib/caldav/README.md +++ b/contrib/caldav/README.md @@ -17,10 +17,12 @@ Usage ----- calcurse-caldav requires an up-to-date version of calcurse and a configuration -file located at ~/.calcurse/caldav/config. An example configuration file can be -found under contrib/caldav/config.sample in the calcurse source tree. You will -also need to install *httplib2* for Python 3 using *pip* (e.g. `pip3 install ---user httplib2`) or your distribution's package manager. +file located at $XDG_CONFIG_HOME/calcurse/caldav/config +(~/.local/share/calcurse/caldav/config) or ~/.calcurse/caldav/config if +~/.calcurse exists. An example configuration file can be found under +contrib/caldav/config.sample in the calcurse source tree. You will also need to +install *httplib2* for Python 3 using *pip* (e.g. `pip3 install --user +httplib2`) or your distribution's package manager. If you run calcurse-caldav for the first time, you need to provide the `--init` argument. You can choose between the following initialization modes: @@ -43,9 +45,11 @@ CALCURSE_CALDAV_PASSWORD=$(pass show calcurse) calcurse-caldav Hooks ----- -You can place scripts in `$HOME/.calcurse/caldav/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/caldav/hooks/` +(`~/.config/calcurse/caldav/hooks`) or `~/.calcurse/caldav/hooks` if +`~/.calcurse` exists in order 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-sync*:: Executed before the data files are synchronized. @@ -59,10 +63,12 @@ How It Works ------------ calcurse-caldav creates a so-called synchronization database at -`~/.calcurse/caldav/sync.db` that always keeps a snapshot of the last time the -script was executed. When running the script, it compares the objects on the -server and the local objects with that snapshot to identify items that were -added or deleted. It then +`$XDG_DATA_HOME/calcurse/caldav/sync.db` +(`~/.local/share/calcurse/caldav/sync.db`) or `~/.calcurse/caldav/sync.db` if +`~/.calcurse` exists that always keeps a snapshot of the last time the script +was executed. When running the script, it compares the objects on the server +and the local objects with that snapshot to identify items that were added or +deleted. It then * downloads new objects from the server and imports them into calcurse, * deletes local objects that no longer exist on the server, diff --git a/contrib/caldav/config.sample b/contrib/caldav/config.sample index 4d87681..c89cfb7 100644 --- a/contrib/caldav/config.sample +++ b/contrib/caldav/config.sample @@ -1,6 +1,11 @@ # If you want to synchronize calcurse with a CalDAV server using -# calcurse-caldav, create a new directory ~/.calcurse/caldav/, copy this file -# to ~/.calcurse/caldav/config and adjust the configuration below. +# calcurse-caldav, create a new directory at $XDG_CONFIG_HOME/calcurse/caldav/ +# (~/.config/calcurse/caldav/) and $XDG_DATA_HOME/calcurse/caldav/ +# (~/.local/share/calcurse/caldav/) and copy this file to +# $XDG_CONFIG_HOME/calcurse/caldav/config and adjust the configuration below. +# Alternatively, if using ~/.calcurse, create a new directory at +# ~/.calcurse/caldav/ and copy this file to ~/.calcurse/caldav/config and adjust +# the configuration file below. [General] # Path to the calcurse binary that is used for importing/exporting items. diff --git a/contrib/caldav/hooks/post-sync b/contrib/caldav/hooks/post-sync index 1ac028c..372d260 100755 --- a/contrib/caldav/hooks/post-sync +++ b/contrib/caldav/hooks/post-sync @@ -4,7 +4,9 @@ # repository, it automatically makes a commit whenever synchronizing with a # CalDAV server. # -# In order to install this hook, copy this file to ~/.calcurse/caldav/hooks/. +# In order to install this hook, copy this file to +# $XDG_CONFIG_HOME/calcurse/caldav/hooks/ (~/.config/calcurse/caldav/hooks/) or +# ~/.calcurse/caldav/hooks/ if using ~/.calcurse. cd "$HOME"/.calcurse/ diff --git a/contrib/hooks/post-save b/contrib/hooks/post-save index bb582e2..6113ce6 100755 --- a/contrib/hooks/post-save +++ b/contrib/hooks/post-save @@ -5,7 +5,9 @@ # 1. Make a commit if the calcurse data directory contains a Git repository. # 2. Synchronize with a CalDAV server if calcurse-caldav is configured. # -# In order to install this hook, copy this file to ~/.calcurse/hooks/. +# In order to install this hook, copy this file to +# $XDG_CONFIG_HOME/calcurse/hooks/ (~/.config/calcurse/hooks/) or +# ~/.calcurse/hooks/ if using ~/.calcurse. cd "$HOME"/.calcurse/ diff --git a/contrib/hooks/pre-load b/contrib/hooks/pre-load index c9ab62d..38edea0 100755 --- a/contrib/hooks/pre-load +++ b/contrib/hooks/pre-load @@ -3,7 +3,9 @@ # This is an example hook. It synchronizes calcurse with a CalDAV server before # loading the data files. # -# In order to install this hook, copy this file to ~/.calcurse/hooks/. +# In order to install this hook, copy this file to +# $XDG_CONFIG_HOME/calcurse/hooks/ (~/.config/calcurse/hooks/) or +# ~/.calcurse/hooks/ if using ~/.calcurse. cd "$HOME"/.calcurse/ diff --git a/contrib/vdir/README.md b/contrib/vdir/README.md index b040d04..676b94c 100644 --- a/contrib/vdir/README.md +++ b/contrib/vdir/README.md @@ -39,7 +39,8 @@ destination, potentially deleting events in the destination that are no longer present in the origin. You can optionally specify an alternative directory for local calcurse data -using the `-D` flag if it differs from the default `~/.calcurse`. +using the `-D` flag if it differs from the default `$XDG_DATA_HOME/calcurse` +(`~/.local/share/calcurse`) or `~/.calcurse`. Integration with vdirsyncer --------------------------- 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. diff --git a/src/io.c b/src/io.c index 5333d66..6488401 100644 --- a/src/io.c +++ b/src/io.c @@ -136,10 +136,11 @@ unsigned io_fprintln(const char *fname, const char *fmt, ...) /* * Initialization of data paths. The cfile argument is the variable * which contains the calendar file. If none is given, then the default - * one (~/.calcurse/apts) is taken. If the one given does not exist, it - * is created. + * one (~/.local/share/calcurse/apts) is taken. If the one given does not exist, + * it is created. * The datadir argument can be used to specify an alternative data root dir. * The confdir argument can be used to specify an alternative configuration dir. + * If ~/.calcurse exists, it will be used instead for backward compatibility. */ void io_init(const char *cfile, const char *datadir, const char *confdir) { @@ -1163,11 +1164,15 @@ int io_check_file(const char *file) * Checks if data files exist. If not, create them. * The following structure has to be created: * - * (default for both: $HOME/.calcurse/) + * * | | * |__ apts |___ conf * |__ todo |___ keys * |__ notes/ |___ hooks/ + * + * Defaults: + * - datadir: $XDG_DATA_HOME/calcurse (~/.local/share/calcurse) + * - configdir: $XDG_CONFIG_HOME/calcurse (~/.config/calcurse) */ int io_check_data_files(void) { diff --git a/test/README b/test/README index f45fd0b..c405382 100644 --- a/test/README +++ b/test/README @@ -22,7 +22,7 @@ alternative calcurse binary and data directory. Passing another data directory might cause some failures since many tests are adapted for the `test/` directory provided by the test suite: - $ CALCURSE=../src/calcurse DATA_DIR="$HOME/.calcurse/" ./next-001.sh + $ CALCURSE=../src/calcurse DATA_DIR="$HOME/.local/share/calcurse/" ./next-001.sh Running ./next-001.sh... FAIL Writing tests -- cgit v1.2.3-54-g00ecf