Change documentation to reflect the new file structure
Signed-off-by: Lukas Fleischer <lfleischer@calcurse.org>
This commit is contained in:
Nitroretro
Lukas Fleischer
parent
04162de6dd
commit
19d2d9229e
@ -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,
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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/
|
||||
|
||||
|
||||
@ -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/
|
||||
|
||||
|
||||
@ -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/
|
||||
|
||||
|
||||
@ -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
|
||||
---------------------------
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
12
doc/save.txt
12
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.
|
||||
|
||||
11
src/io.c
11
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)
|
||||
{
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user