diff options
Diffstat (limited to 'doc/manual.txt')
| -rw-r--r-- | doc/manual.txt | 100 |
1 files changed, 61 insertions, 39 deletions
diff --git a/doc/manual.txt b/doc/manual.txt index ff5131f..03a27ff 100644 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -1,6 +1,6 @@ //// /* - * Copyright (c) 2004-2017 calcurse Development Team <misc@calcurse.org> + * Copyright (c) 2004-2023 calcurse Development Team <misc@calcurse.org> * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -117,7 +117,7 @@ gettext library `gettext` utilities. This means `calcurse` can produce multi-lingual messages if compiled with native language support (i.e. *NLS*). -However, *NLS* is optionnal and if you do not want to have support for +However, *NLS* is optional and if you do not want to have support for multi-lingual messages, you can disable this feature. This is done by giving the `--disable-nls` option to `configure` (see section <<install_process,Install process>>). To check if the `gettext` utilities are @@ -143,7 +143,7 @@ Install process First you need to gunzip and untar the source archive: ---- -$ tar zxvf calcurse-4.5.1.tar.gz +$ tar zxvf calcurse-4.8.1.tar.gz ---- Once you meet the requirements and have extracted the archive, the install @@ -176,9 +176,14 @@ 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 located at + `<datadir>/apts` (see section <<basics_files,calcurse files>>). This option + has precedence over `-D`. + +`-C <dir>, --directory <dir>`:: + Specify the configuration directory to use. See + <<basics_files,calcurse files>> for the default directory and for the + interaction with `-D`. `-d <date|num>, --day <date|num>`:: Print the appointments for the given date or for the given number of @@ -209,8 +214,8 @@ can be specified using the `-c` flag. combined with `--to`. `-D <dir>, --directory <dir>`:: - Specify the data directory to use. If not specified, the default directory is - `~/.calcurse/`. + Specify the (data) directory to use. See <<basics_files,calcurse files>> for + the default directory and for the interaction with `-C`. `--filter-type <type>`:: Ignore any items that do not match the type mask. See @@ -298,7 +303,7 @@ can be specified using the `-c` flag. information on format strings. `--export-uid`:: - When exporting items, add the hash of each item to the exported object as an + When exporting items, add the hash of each item to the exported object as a UID property. `-F`, `--filter`:: @@ -591,7 +596,7 @@ Environment variable for i18n <<install_requirements_gettext,gettext library>>). Thus, if you wish to have messages displayed into your native language, first make sure it is available by looking at the `po/LINGUAS` file. This file indicates the set of available -languages by showing the two-letters corresponding code (for exemple, *fr* +languages by showing the two-letters corresponding code (for example, *fr* stands for french). If you do not find your language, it would be greatly appreciated if you could help translating `calcurse` (see the <<contribute,How to contribute?>> section). @@ -602,7 +607,7 @@ If your language is available, run `calcurse` with the following command: $ LC_ALL=fr_FR calcurse ---- -... where *fr_FR* is the locale name in this exemple, but should be replaced by +... where *fr_FR* is the locale name in this example, but should be replaced by the locale corresponding to the desired language. You should also specify the charset to be used, because in some cases the @@ -632,19 +637,22 @@ The following environment variables affect the way `calcurse` operates: Specifies the default viewer to be used for reading notes. If this variable is not set, then `/usr/bin/less` is used. +See also <<basics_files,calcurse files>>. + Hooks ~~~~~ -You can place scripts in `$HOME/.calcurse/hooks/` to trigger actions at certain +You can place scripts in `<confdir>/hooks/` +(see section <<basics_files,calcurse files>>) 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. *post-load*:: - Executed after the data files are saved. + Executed after the data files are loaded. *pre-save*:: - Executed before the data files are loaded. + Executed before the data files are saved. *post-save*:: Executed after the data files are saved. @@ -850,17 +858,28 @@ 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 -: +An alternative directory for 'both' the configuration files and the data +directory 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 +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. ---- -$HOME/.calcurse/ - |___notes/ - |___conf - |___keys - |___apts - |___todo +<datadir> <confdir> + | | + |__ apts |___ conf + |__ todo |___ keys + |__ notes/ |___ hooks/ + +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) ---- `notes/`:: this subdirectory contains descriptions of the notes which are attached to @@ -868,19 +887,22 @@ $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 +`hooks/`:: + this subdirectory contains scripts that you can use to trigger actions at + certain events (see <<_hooks,Hooks>>) 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -911,7 +933,7 @@ Here are the properties that are not implemented: * negative time durations are not taken into account (item is skipped) -* some recurence frequences are not recognize: "SECONDLY" / "MINUTELY" / +* some recurrence frequencies are not recognize: "SECONDLY" / "MINUTELY" / "HOURLY" * some recurrence keywords are not recognized (all those starting with `BY`): @@ -1074,7 +1096,7 @@ applied. It is possible to keep the terminal's default colors by selecting the corresponding choice in the list. The chosen color theme will then be applied to the panel borders, to the -titles, to the keystrokes, and to general informations displayed inside status +titles, to the keystrokes, and to general information displayed inside status bar. A black and white theme is also available, in order to support non-color terminals. @@ -1219,7 +1241,7 @@ native language, it would be appreciated if you could help translating it. To do so, just copy one of the existing manual file to `manual_XX.html`, where *XX* identifies your language. Then translate this newly created file and send -it to the author (see <<bugs,Reporting bugs and feeback>>), so that it can be +it to the author (see <<bugs,Reporting bugs and feedback>>), so that it can be included in the next `calcurse` release. calcurse i18n @@ -1229,10 +1251,10 @@ As already mentioned, `gettext` utilities are used by `calcurse` to produce multi-lingual messages. We are currently using http://www.transifex.net/[Transifex] to manage those translations. -This section provides informations about how to translate those messages into +This section provides information about how to translate those messages into your native language. However, this howto is deliberately incomplete, focusing on working with `gettext` for `calcurse` specifically. For more comprehensive -informations or to grasp the Big Picture of Native Language Support, you should +information or to grasp the Big Picture of Native Language Support, you should refer to the `GNU gettext` manual at: http://www.gnu.org/software/gettext/manual/ @@ -1357,19 +1379,19 @@ msgid "" You should also fill in the Last-Translator field, so that potential contributors can contact you if they want to join you in the translation team, or have remarks/typo fixes to give about the translations. You can either just -give your name/nick, or add an email address, for exemple: +give your name/nick, or add an email address, for example: + ---- "Last-Translator: Frederic Culot <frederic@culot.org>\n" ---- *Comments*:: - Adding comments (lines begining with the `#` character) can be a good way to + Adding comments (lines beginning with the `#` character) can be a good way to point out problems or translation difficulties to proofreaders or other members of your team. *Strings size*:: - `calcurse` is a curses/console program, thus it can be heavily dependant on + `calcurse` is a curses/console program, thus it can be heavily dependent on the terminal size (number of columns). You should think about this when translating. Often, a string must fit into a single line (standard length is 80 characters). Don't translate blindly, try to look where your string will @@ -1497,7 +1519,7 @@ Thanks Its time now to thank other people without whom this program would not exist! So here is a list of contributing persons I would like to thank: -* Alex for its patches, help and advices with `C` programming +* Alex for its patches, help and advice with `C` programming * Gwen for testing and general discussions about how to improve `calcurse` |