summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorNitroretro <nitroretro@protonmail.com>2019-12-17 17:24:48 +0200
committerLukas Fleischer <lfleischer@calcurse.org>2019-12-23 13:16:39 -0500
commit19d2d9229e62ea5e993b462f0cdedd868ec6c2d9 (patch)
tree8e17be1def6c0013831f17f261f031d08887f374
parent04162de6ddcdbc5c1b2410f4f5f7dbae72cc62d9 (diff)
downloadcalcurse-19d2d9229e62ea5e993b462f0cdedd868ec6c2d9.tar.gz
calcurse-19d2d9229e62ea5e993b462f0cdedd868ec6c2d9.zip
Change documentation to reflect the new file structure
Signed-off-by: Lukas Fleischer <lfleischer@calcurse.org>
-rw-r--r--contrib/caldav/README.md28
-rw-r--r--contrib/caldav/config.sample9
-rwxr-xr-xcontrib/caldav/hooks/post-sync4
-rwxr-xr-xcontrib/hooks/post-save4
-rwxr-xr-xcontrib/hooks/pre-load4
-rw-r--r--contrib/vdir/README.md3
-rw-r--r--doc/calcurse.1.txt55
-rw-r--r--doc/manual.txt47
-rw-r--r--doc/save.txt12
-rw-r--r--src/io.c11
-rw-r--r--test/README2
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.
+
----
<datadir> <confdir>
| |
@@ -677,7 +684,10 @@ ignored.
|__ todo |___ keys
|__ notes/ |___ hooks/
-default for both: $HOME/.calcurse/
+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
@@ -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 <file>, --calendar <file>`::
- Specify the calendar file to use. The default calendar is `~/.calcurse/apts`
- (see section <<basics_files,calcurse files>>). 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
+ <<basics_files,calcurse files>>). 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
@@ -210,7 +211,8 @@ can be specified using the `-c` flag.
`-D <dir>, --directory <dir>`::
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 <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:
*
- * <datadir> <configdir> (default for both: $HOME/.calcurse/)
+ * <datadir> <configdir>
* | |
* |__ 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