fyb/calcurse-edge
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Change documentation to reflect the new file structure

Browse Source 
Signed-off-by: Lukas Fleischer <lfleischer@calcurse.org>
This commit is contained in:
Nitroretro 2019-12-17 17:24:48 +02:00 committed by Lukas Fleischer
parent 04162de6dd
commit 19d2d9229e
11 changed files with 109 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
contrib/caldav/README.md
View File

@ -17,10 +17,12 @@ Usage
----- -----
calcurse-caldav requires an up-to-date version of calcurse and a configuration 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 file located at $XDG_CONFIG_HOME/calcurse/caldav/config
found under contrib/caldav/config.sample in the calcurse source tree. You will (~/.local/share/calcurse/caldav/config) or ~/.calcurse/caldav/config if
also need to install *httplib2* for Python 3 using *pip* (e.g. `pip3 install ~/.calcurse exists. An example configuration file can be found under
--user httplib2`) or your distribution's package manager. 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` If you run calcurse-caldav for the first time, you need to provide the `--init`
argument. You can choose between the following initialization modes: argument. You can choose between the following initialization modes:
@ -43,9 +45,11 @@ CALCURSE_CALDAV_PASSWORD=$(pass show calcurse) calcurse-caldav
Hooks Hooks
----- -----
You can place scripts in `$HOME/.calcurse/caldav/hooks/` to trigger actions at You can place scripts in `$XDG_CONFIG_HOME/calcurse/caldav/hooks/`
certain events. To enable a hook, add a script with one of the following names (`~/.config/calcurse/caldav/hooks`) or `~/.calcurse/caldav/hooks` if
to this directory. Also make sure the scripts are executable. `~/.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*:: *pre-sync*::
Executed before the data files are synchronized. 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 creates a so-called synchronization database at
`~/.calcurse/caldav/sync.db` that always keeps a snapshot of the last time the `$XDG_DATA_HOME/calcurse/caldav/sync.db`
script was executed. When running the script, it compares the objects on the (`~/.local/share/calcurse/caldav/sync.db`) or `~/.calcurse/caldav/sync.db` if
server and the local objects with that snapshot to identify items that were `~/.calcurse` exists that always keeps a snapshot of the last time the script
added or deleted. It then 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, * downloads new objects from the server and imports them into calcurse,
* deletes local objects that no longer exist on the server, * deletes local objects that no longer exist on the server,

9
contrib/caldav/config.sample
View File

@ -1,6 +1,11 @@
# If you want to synchronize calcurse with a CalDAV server using # If you want to synchronize calcurse with a CalDAV server using
# calcurse-caldav, create a new directory ~/.calcurse/caldav/, copy this file # calcurse-caldav, create a new directory at $XDG_CONFIG_HOME/calcurse/caldav/
# to ~/.calcurse/caldav/config and adjust the configuration below. # (~/.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] [General]
# Path to the calcurse binary that is used for importing/exporting items. # Path to the calcurse binary that is used for importing/exporting items.

4
contrib/caldav/hooks/post-sync
View File

@ -4,7 +4,9 @@
# repository, it automatically makes a commit whenever synchronizing with a # repository, it automatically makes a commit whenever synchronizing with a
# CalDAV server. # 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/ cd "$HOME"/.calcurse/

4
contrib/hooks/post-save
View File

@ -5,7 +5,9 @@
# 1. Make a commit if the calcurse data directory contains a Git repository. # 1. Make a commit if the calcurse data directory contains a Git repository.
# 2. Synchronize with a CalDAV server if calcurse-caldav is configured. # 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/ cd "$HOME"/.calcurse/

4
contrib/hooks/pre-load
View File

@ -3,7 +3,9 @@
# This is an example hook. It synchronizes calcurse with a CalDAV server before # This is an example hook. It synchronizes calcurse with a CalDAV server before
# loading the data files. # 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/ cd "$HOME"/.calcurse/

3
contrib/vdir/README.md
View File

@ -39,7 +39,8 @@ destination, potentially deleting events in the destination that are no longer
present in the origin. present in the origin.
You can optionally specify an alternative directory for local calcurse data 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 Integration with vdirsyncer
--------------------------- ---------------------------

53
doc/calcurse.1.txt
View File

@ -143,19 +143,22 @@ are marked "('also interactively')".
*-c* 'file', *--calendar* 'file':: *-c* 'file', *--calendar* 'file'::
('also interactively') Specify the calendar file to use. The default ('also interactively') Specify the calendar file to use. The default
calendar is *~/.calcurse/apts* (see <<_files,FILES>>). If 'file' is not an calendar is *$XDG_DATA_HOME/apts* (*\~/.local/share/calcurse/apts*) or
absolute path name, it is interpreted relative to the current working *\~/.calcurse/apts* if *~/.calcurse* exists. (see <<_files,FILES>>). If
directory. The option has precedence over *-D*. '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':: *-C* 'dir', *--confdir* 'dir'::
('also interactively') Specify the configuration directory to use. If not ('also interactively') Specify the configuration directory to use. If not
specified, the default directory is *~/.calcurse/*. See <<_files,FILES>> for specified, the default directory is *$XDG_CONFIG_HOME/calcurse/*
the interaction with *-D*. (*\~/.config/calcurse/*) or *~/.calcurse* if it exists. See <<_files,FILES>>
for the interaction with *-D*.
*-D* 'dir', *--datadir* 'dir':: *-D* 'dir', *--datadir* 'dir'::
('also interactively') Specify the (data) directory to use. If not specified, ('also interactively') Specify the (data) directory to use. If not specified,
the default directory is *~/.calcurse/*. See section <<_files,FILES>> for the default directory is *$XDG_DATA_HOME/calcurse*
the interaction with *-C*. (*\~/.local/share/calcurse/*) or *~/.calcurse* if it exists. See section
<<_files,FILES>> for the interaction with *-C*.
*-d* 'date|num', *--day* 'date|num':: *-d* 'date|num', *--day* 'date|num'::
Print appointments and events for the given date or given range of days, 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: first time calcurse is run without any options:
---- ----
$HOME/.calcurse/ $XDG_DATA_HOME/calcurse/ $XDG_CONFIG_HOME/calcurse/
|___apts |___apts |___conf
|___conf |___notes/ |___hooks/
|___hooks/ |___todo |___keys
|___keys
|___notes/
|___todo
---- ----
+$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 The files are of two different kinds: data and configuration. The data files
constitute the calcurse database and are independent of the calcurse release constitute the calcurse database and are independent of the calcurse release
version; the configuration files depend on the calcurse version although version; the configuration files depend on the calcurse version although
@ -661,8 +664,9 @@ scripts, see <<_hooks,Hooks>>.
Directory configuration Directory configuration
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
An alternative directory to the default +$HOME/.calcurse+ may be specified An alternative directory to the defaults +$XDG_DATA_HOME/calcurse+
with the *-D* option. (+$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 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 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 *-C* are present, configuration files in the data directory, if any, are
ignored. ignored.
If +$HOME/.calcurse+ exists, then it will be used as the default for both the
data directory and the configuration directory.
---- ----
<datadir> <confdir> <datadir> <confdir>
| | | |
@ -677,7 +684,10 @@ ignored.
|__ todo |___ keys |__ todo |___ keys
|__ notes/ |___ hooks/ |__ 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 calcurse may switch between two configuration setups, but still access
@ -686,15 +696,16 @@ the same data files e.g. with:
---- ----
$ calcurse $ calcurse
$ calcurse -C "$HOME/.calcurse/config" $ calcurse -C "$HOME/.config/calcurse/config"
---- ----
Hooks Hooks
~~~~~ ~~~~~
Scripts placed in +$HOME/.calcurse/hooks/+ trigger actions at certain Scripts placed in +$XDG_CONFIG_HOME/calcurse/hooks/+
events. To enable a hook, add a script with one of the following names to this (+$HOME/.config/calcurse/hooks+) trigger actions at certain events. To enable a
directory. Also make sure the script is executable. hook, add a script with one of the following names to this directory. Also make
sure the script is executable.
*pre-load*:: *pre-load*::
Executed before the data files are loaded. Executed before the data files are loaded.

47
doc/manual.txt
View File

@ -176,9 +176,10 @@ long options are supported):
be specified using the `-c` flag. be specified using the `-c` flag.
`-c <file>, --calendar <file>`:: `-c <file>, --calendar <file>`::
Specify the calendar file to use. The default calendar is `~/.calcurse/apts` Specify the calendar file to use. The default calendar is
(see section <<basics_files,calcurse files>>). This option has precedence `$XDG_DATA_HOME/calcurse/apts` (`~/.local/share/calcurse/apts`) or
over `-D`. `~/.calcurse/apts` if `~/.calcurse` exists. (see section
<<basics_files,calcurse files>>). This option has precedence over `-D`.
`-d <date|num>, --day <date|num>`:: `-d <date|num>, --day <date|num>`::
Print the appointments for the given date or for the given number of 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>`:: `-D <dir>, --directory <dir>`::
Specify the data directory to use. If not specified, the default directory is 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>`:: `--filter-type <type>`::
Ignore any items that do not match the type mask. See 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 Hooks
~~~~~ ~~~~~
You can place scripts in `$HOME/.calcurse/hooks/` to trigger actions at certain You can place scripts in `$XDG_CONFIG_HOME/calcurse/hooks/`
events. To enable a hook, add a script with one of the following names to this (`$HOME/.config/calcurse/hooks/`) to trigger actions at certain events. To
directory. Also make sure the scripts are executable. enable a hook, add a script with one of the following names to this directory.
Also make sure the scripts are executable.
*pre-load*:: *pre-load*::
Executed before the data files are loaded. 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 calcurse files
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
The following structure is created in your `$HOME` directory (or in the The following structure is created in your `$XDG_CONFIG_HOME` (`$HOME/.config`)
directory you specified with the -D option) the first time `calcurse` is run 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/ $XDG_DATA_HOME/calcurse/ $XDG_CONFIG_HOME/calcurse/
|___notes/ |___notes/ |___conf
|___conf |___apts |___keys
|___keys |___todo
|___apts
|___todo
---- ----
`notes/`:: `notes/`::
this subdirectory contains descriptions of the notes which are attached to 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. 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) 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. 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`:: `apts`::
this file contains all of the events and user's appointments this file contains all of the events and user's appointments
`todo`:: `todo`::
this file contains the todo list 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 NOTE: If the logging of calcurse daemon activity was set in the notification
configuration menu, the extra file `daemon.log` will appear in calcurse configuration menu, the extra file `daemon.log` will appear in the
data directory. This file contains logs about calcurse activity when calcurse data directory. This file contains logs about calcurse activity
running in background. when running in background.
Import/Export capabilities Import/Export capabilities
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~

12
doc/save.txt
View File

@ -5,11 +5,15 @@ Save calcurse data.
Data are split into four different files which contain : Data are split into four different files which contain :
/ ~/.calcurse/conf -> user configuration / $XDG_CONFIG_HOME/calcurse/conf -> user configuration
| (layout, color, general options) | (layout, color, general options)
| ~/.calcurse/apts -> data related to the appointments | $XDG_DATA_HOME/calcurse/apts -> data related to the appointments
| ~/.calcurse/todo -> data related to the todo list | $XDG_DATA_HOME/calcurse/todo -> data related to the todo list
\ ~/.calcurse/keys -> user-defined key bindings \ $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 In the config menu, you can choose to save the calcurse data automatically
before quitting. before quitting.

11
src/io.c
View File

@ -136,10 +136,11 @@ unsigned io_fprintln(const char *fname, const char *fmt, ...)
/* /*
* Initialization of data paths. The cfile argument is the variable * Initialization of data paths. The cfile argument is the variable
* which contains the calendar file. If none is given, then the default * 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 * one (~/.local/share/calcurse/apts) is taken. If the one given does not exist,
* is created. * it is created.
* The datadir argument can be used to specify an alternative data root dir. * 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. * 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) 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. * Checks if data files exist. If not, create them.
* The following structure has to be created: * The following structure has to be created:
* *
* <datadir> <configdir> (default for both: $HOME/.calcurse/) * <datadir> <configdir>
* | | * | |
* |__ apts |___ conf * |__ apts |___ conf
* |__ todo |___ keys * |__ todo |___ keys
* |__ notes/ |___ hooks/ * |__ notes/ |___ hooks/
*
* Defaults:
* - datadir: $XDG_DATA_HOME/calcurse (~/.local/share/calcurse)
* - configdir: $XDG_CONFIG_HOME/calcurse (~/.config/calcurse)
*/ */
int io_check_data_files(void) int io_check_data_files(void)
{ {

2
test/README
View File

@ -22,7 +22,7 @@ alternative calcurse binary and data directory.
Passing another data directory might cause some failures since many tests are Passing another data directory might cause some failures since many tests are
adapted for the `test/` directory provided by the test suite: 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 Running ./next-001.sh... FAIL
Writing tests Writing tests