diff options
Diffstat (limited to 'doc/manual.txt')
| -rw-r--r-- | doc/manual.txt | 260 |
1 files changed, 197 insertions, 63 deletions
diff --git a/doc/manual.txt b/doc/manual.txt index c0a992d..80993cf 100644 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -1,6 +1,6 @@ //// /* - * Copyright (c) 2004-2011 calcurse Development Team <misc@calcurse.org> + * Copyright (c) 2004-2012 calcurse Development Team <misc@calcurse.org> * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -36,7 +36,7 @@ CALCURSE - text-based organizer Abstract -------- -This manual describes `calcurse` functionnalities, and how to use them. The +This manual describes `calcurse` functionalities, and how to use them. The installation from source is first described, together with the available command line arguments. The user interface is then presented, with all of the customizable options that change `calcurse` behavior. Last, bug reporting @@ -113,8 +113,7 @@ library already installed on your computer, but if not, you can find it at the following url: http://ftp.gnu.org/pub/gnu/ncurses/ NOTE: It is also possible to link `calcurse` against the `ncursesw` library - (ncurses with support for unicode). However, UTF-8 is not yet supported - by `calcurse`. + (ncurses with support for unicode). [[install_requirements_gettext]] gettext library @@ -201,7 +200,7 @@ days will be returned. As an example, typing `calcurse -d 3` will display your appointments for today, tomorrow, and the day after tomorrow. Possible formats for specifying the date are defined inside the general configuration menu (see <<options_general,General options>>), using the -`input_datefmt` variable. +`format.inputdate` variable. + Note: as for the `-a` flag, the calendar from which to read the appointments can be specified using the `-c` flag. @@ -210,6 +209,34 @@ can be specified using the `-c` flag. Specify the data directory to use. This option is incompatible with -c. If not specified, the default directory is `~/.calcurse/`. +`--format-apt <format>`:: + Specify a format to control the output of appointments in non-interactive + mode. See the <<basics_format_strings,Format strings>> section for detailed + information on format strings. + +`--format-recur-apt <format>`:: + Specify a format to control the output of recurrent appointments in + non-interactive mode. See the <<basics_format_strings,Format strings>> + section for detailed information on format strings. + +`--format-event <format>`:: + Specify a format to control the output of events in non-interactive mode. See + the <<basics_format_strings,Format strings>> section for detailed information + on format strings. + +`--format-recur-event <format>`:: + Specify a format to control the output of recurrent events in non-interactive + mode. See the <<basics_format_strings,Format strings>> section for detailed + information on format strings. + +`--format-todo <format>`:: + Specify a format to control the output of todo items in non-interactive mode. + See the <<basics_format_strings,Format strings>> section for detailed + information on format strings. + +`-g, --gc`:: + Run the garbage collector for note files and exit. + `-h, --help`:: Print a short help text describing the supported command-line options, and exit. @@ -224,14 +251,16 @@ can be specified using the `-c` flag. Note: the calendar from which to read the appointments can be specified using the `-c` flag. -`-N, --note`:: - When used with the `-a` or `-t` flag, also print note content if one is - associated with the displayed item. - `-r[num], --range[=num]`:: Print events and appointments for the num number of days and exit. If no num is given, a range of 1 day is considered. +`--read-only`:: + Don't save configuration nor appointments/todos. ++ +WARNING: Use this this with care! If you run an interactive calcurse instance +in read-only mode, all changes from this session will be lost without warning! + `-s[date], --startday[=date]`:: Print events and appointments from date and exit. If no date is given, the current day is considered. @@ -268,6 +297,100 @@ such as: $ calcurse --export > my_data.dat ---- +NOTE: The `-N` option has been removed in calcurse 3.0.0. See the +<<basics_format_strings,Format strings>> section on how to print note along +with appointments and events. + +[[basics_format_strings]] +Format strings +^^^^^^^^^^^^^^ + +Format strings are composed of printf()-style format specifiers -- ordinary +characters are copied to stdout without modification. Each specifier is +introduced by a `%` and is followed by a character which specifies the field to +print. The set of available fields depends on the item type. + +Format specifiers for appointments +++++++++++++++++++++++++++++++++++ + +`s`:: + Print the start time of the appointment as UNIX time stamp +`S`:: + Print the start time of the appointment using the `hh:mm` format +`d`:: + Print the duration of the appointment in seconds +`e`:: + Print the end time of the appointment as UNIX time stamp +`E`:: + Print the end time of the appointment using the `hh:mm` format +`m`:: + Print the description of the item +`n`:: + Print the name of the note file belonging to the item +`N`:: + Print the note belonging to the item + +Format specifiers for events +++++++++++++++++++++++++++++ + +`m`:: + Print the description of the item +`n`:: + Print the name of the note file belonging to the item +`N`:: + Print the note belonging to the item + +Format specifiers for todo items +++++++++++++++++++++++++++++++++ + +`p`:: + Print the priority of the item +`m`:: + Print the description of the item +`n`:: + Print the name of the note file belonging to the item +`N`:: + Print the note belonging to the item + +Examples +++++++++ + +`calcurse -r7 --format-apt='- %S -> %E\n\t%m\n%N'`:: + Print appointments and events for the next seven days. Also, print the notes + attached to each regular appointment (simulates `-N` for appointments). + +`calcurse -r7 --format-apt=' - %m (%S to %E)\n' --format-recur-apt=' - %m (%S to %E)\n'`:: + Print appointments and events for the next seven days and use a custom format + for (recurrent) appointments: ` - Some appointment (18:30 to 21:30)`. + +`calcurse -t --format-todo '(%p) %m\n'`:: + List all todo items and put parentheses around the priority specifiers. + +Extended format specifiers +++++++++++++++++++++++++++ + +Extended format specifiers can be used if you want to specify advanced +formatting options. Extended specifiers are introduced by `%(` and are +terminated by a closing parenthesis (`)`). The following list includes all +short specifiers and corresponding long options: + +* `s`: `(start)` +* `S`: `(start:epoch)` +* `d`: `(duration)` +* `e`: `(end)` +* `E`: `(end:epoch)` +* `m`: `(message)` +* `n`: `(noteid)` +* `N`: `(note)` +* `p`: `(priority)` + +The `(start)` and `(end)` specifiers support strftime()-style extended +formatting options that can be used for fine-grained formatting. Additionally, +the special formats `epoch` (which is equivalent to `(start:%s)` or `(end:%s)`) +and `default` (which is mostly equivalent to `(start:%H:%M)` or `(end:%H:%M)` +but displays `..:..` if the item doesn't start/end at the current day) are +supported. + [[basics_invocation_variable]] Environment variable for i18n ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -492,11 +615,11 @@ for upcoming appointments and runs the user-defined notification command when necessary. When the user interface is started again, the daemon automatically stops. -`calcurse` background activity can be logged (set the `notify-daemon_log` -variable in the notification configuration <<options_notify,menu>>), -and in that case, information about the daemon start and stop time, reminders' -command launch time, signals received... will be written in the `daemon.log` -file (see section <<basics_files,files>>). +`calcurse` background activity can be logged (set the `daemon.log` variable in +the notification configuration <<options_notify,menu>>), and in that case, +information about the daemon start and stop time, reminders' command launch +time, signals received... will be written in the `daemon.log` file (see section +<<basics_files,files>>). Using the `--status` command line option (see section <<basics_invocation_commandline,Command line arguments>>), one can know if @@ -530,9 +653,10 @@ $HOME/.calcurse/ ---- `notes/`:: this subdirectory contains descriptions of the notes which are attached to - appointments, events or todos. One text file is created per note, whose name - is built using mkstemp(3) and should be unique, but with no relation with the - corresponding item's description. + appointments, events or todos. Since the file name of each note file is a + 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`:: @@ -618,55 +742,57 @@ General options These options control `calcurse` general behavior, as described below: -`auto_save` (default: *yes*):: +`general.autosave` (default: *yes*):: This option allows to automatically save the user's data (if set to *yes*) when quitting. <p class="rq"><span class="valorise">warning:</span> No data - will be automatically saved if `auto_save` is set to *no*. This means the - user must press `S` (for saving) in order to retrieve its modifications. + will be automatically saved if `general.autosave` is set to *no*. This means + the user must press `S` (for saving) in order to retrieve its modifications. -`periodic_save` (default: *0*):: +`general.autogc` (default: *no*):: + Automatically run the garbage collector for note files when quitting. + +`general.periodicsave` (default: *0*):: If different from `0`, user's data will be automatically saved every - *periodic_save* minutes. When an automatic save is performed, two asterisks - (i.e. `**`) will appear on the top right-hand side of the screen). + *general.periodicsave* minutes. When an automatic save is performed, two + asterisks (i.e. `**`) will appear on the top right-hand side of the screen). -`confirm_quit` (default: *yes*):: +`general.confirmquit` (default: *yes*):: If set to *yes*, confirmation is required before quitting, otherwise pressing `Q` will cause `calcurse` to quit without prompting for user confirmation. -`confirm_delete` (default: *yes*):: +`general.confirmdelete` (default: *yes*):: If this option is set to *yes*, pressing `D` for deleting an item (either a *todo*, *appointment*, or *event*), will lead to a prompt asking for user confirmation before removing the selected item from the list. Otherwise, no confirmation will be needed before deleting the item. -`skip_system_dialogs` (default: *no*):: - Setting this option to *yes* will result in skipping the system dialogs +`general.systemdialogs` (default: *yes*):: + Setting this option to *no* will result in skipping the system dialogs related to the saving and loading of data. This can be useful to speed up the input/output processes. -`skip_progress_bar` (default: *no*):: - If set to *yes*, this will cause the disappearing of the progress bar which - is usually shown when saving data to file. If set to *no*, this bar will be +`general.progressbar` (default: *yes*):: + If set to *no*, this will cause the disappearing of the progress bar which is + usually shown when saving data to file. If set to *yes*, this bar will be displayed, together with the name of the file being saved (see section <<basics_files,calcurse files>>). -`calendar_default_view` (default: *0*):: +`appearance.calendarview` (default: *0*):: If set to `0`, the monthly calendar view will be displayed by default otherwise it is the weekly view that will be displayed. -`week_begins_on_monday` (default: *yes*):: - One can choose between Monday and Sunday as the first day of the week. If the - option `week_begins_on_monday` is set to *yes*, Monday will be first in the - calendar view. Else if the option is set to *no*, then Sunday will be the - first day of the week. +`general.firstdayofweek` (default: *monday*):: + One can choose between Monday and Sunday as the first day of the week. If + `general.firstdayofweek` is set to *monday*, Monday will be first in the + calendar view. Otherwise, Sunday will be the first day of the week. -`output_datefmt` (default: *%D*):: +`format.outputdate` (default: *%D*):: This option indicates the format to be used when displaying dates in non-interactive mode. Using the default values, dates are displayed the following way: *mm/dd/aa*. You can see all of the possible formats by typing `man 3 strftime` inside a terminal. -`input_datefmt` (default: *1*):: +`format.inputdate` (default: *1*):: This option indicates the format that will be used to enter dates in *calcurse*. Four choices are available: + @@ -679,12 +805,12 @@ These options control `calcurse` general behavior, as described below: Key bindings ~~~~~~~~~~~~ -One can define it's own keybindings within the `Keys` configuration menu. The +One can define ones own key bindings within the `Keys` configuration menu. The default keys look like the one used by the `vim` editor, especially the displacement keys. Anyway, within this configuration menu, users can redefine all of the keys available from within calcurse's user interface. -To define new keybindings, first highlight the action to which it will apply. +To define new key bindings, first highlight the action to which it will apply. Then, delete the actual key binding if necessary, and add a new one. You will then be asked to press the key corresponding to the new binding. It is possible to define more than one key binding for a single action. @@ -710,6 +836,10 @@ While inside the key configuration menu, an online help is available for each one of the available actions. This help briefly describes what the highlighted action is used for. +NOTE: As of calcurse 3.0.0, displacement commands can be preceded by an + optional number to repeat the command. For example, `10k` will move the + cursor ten weeks forwards if you use default key bindings. + Color themes ~~~~~~~~~~~~ @@ -726,7 +856,7 @@ bar. A black and white theme is also available, in order to support non-color terminals. NOTE: Depending on your terminal type and on the value of the `$TERM` - environnement variable, color could or could not be supported. An error + environment variable, color could or could not be supported. An error message will appear if you try to change colors whereas your terminal does not support this feature. If you do know your terminal supports colors but could not get `calcurse` to display them, try to set your @@ -740,13 +870,13 @@ The default layout makes the calendar panel to be displayed on the top-right corner of the terminal, the todo panel on the bottom-right corner, while the appointment panel is displayed on the left hand-side of the screen (see the figure in section <<basics_interface_interactive,Interactive mode>> for an -exemple of the default layout). By choosing another layout in the -configuration screen, user can customize `calcurse` appearence to best suit his +example of the default layout). By choosing another layout in the +configuration screen, user can customize `calcurse` appearance to best suit his needs by placing the different panels where needed. The following option is used to modify the layout configuration: -`layout` (default: *0*):: +`appearance.layout` (default: *0*):: Eight different layouts are to be chosen from (see layout configuration screen for the description of the available layouts). @@ -759,7 +889,7 @@ list. The following option is used to change the width of the sidebar: -`side-bar_width` (default: *0*):: +`appearance.sidebarwidth` (default: *0*):: Width (in percentage, 0 being the minimum width) of the side bar. [[options_notify]] @@ -768,27 +898,27 @@ Notify-bar settings The following options are used to modify the notify-bar behavior: -`notify-bar_show` (default: *yes*):: +`appearance.notifybar` (default: *yes*):: This option indicates if you want the notify-bar to be displayed or not. -`notify-bar_date` (default: *%a %F*):: +`format.notifydate` (default: *%a %F*):: With this option, you can specify the format to be used to display the current date inside the notification bar. You can see all of the possible formats by typing `man 3 strftime` inside a terminal. -`notify-bar_time` (default: *%T*):: +`format.notifytime` (default: *%T*):: With this option, you can specify the format to be used to display the current time inside the notification bar. You can see all of the possible formats by typing `man 3 strftime` inside a terminal. -`notify-bar_warning` (default: *300*):: +`notification.warning` (default: *300*):: When there is an appointment which is flagged as `important` within the next - `notify-bar_warning` seconds, the display of that appointment inside the - notify-bar starts to blink. Moreover, the command defined by the - `notify-bar_command` option will be launched. That way, the user is warned + `notification.warning` seconds, the display of that appointment inside the + notify-bar starts to blink. Moreover, the command defined by the + `notification.command` option will be launched. That way, the user is warned and knows there will be soon an upcoming appointment. -`notify-bar_command` (default: *printf '\a'*):: +`notification.command` (default: *printf '\a'*):: This option indicates which command is to be launched when there is an upcoming appointment flagged as `important`. This command will be passed to the user's shell which will interpret it. To know what shell must be used, @@ -805,13 +935,17 @@ $ calcurse --next | mail -s "[calcurse] upcoming appointment!" user@host.com ---- ==== -`notify-daemon_enable` (default: *no*):: +`notification.notifyall` (default: *no*):: + Invert the sense of flagging an appointment as `important`. If this is + enabled, all appointments will be notified - except for flagged ones. + +`daemon.enable` (default: *no*):: If set to yes, daemon mode will be enabled, meaning `calcurse` will run into background when the user's interface is exited. This will allow the notifications to be launched even when the interface is not running. More details can be found in section <<basics_daemon,Background mode>>. -`notify-daemon_log` (default: *no*):: +`daemon.log` (default: *no*):: If set to yes, `calcurse` daemon activity will be logged (see section <<basics_files,files>>). @@ -825,9 +959,9 @@ be used instead of *xterm-color* to set the `$TERM` variable: ____ "The xterm-color value for $TERM is a bad choice for XFree86 xterm because it -is commonly used for a terminfo entry which happens to not support bce. Use the -xterm-xfree86 entry which is distributed with XFree86 xterm (or the similar one -distributed with ncurses)." +is commonly used for a `terminfo` entry which happens to not support bce. Use +the xterm-xfree86 entry which is distributed with XFree86 xterm (or the similar +one distributed with ncurses)." ____ [[bugs]] @@ -878,7 +1012,7 @@ http://www.gnu.org/software/gettext/manual/ IMPORTANT: Since we switched to Transifex, editing *po* files is not necessary anymore as Transifex provides a user-friendly, intuitive web - interface for translators. Knowlegde of `gettext` and the *po* + interface for translators. Knowledge of `gettext` and the *po* format is still useful for those of you who prefer the command line and local editing. If you want to use the web UI to edit the translation strings, you can skip over to <<transifex_webui,Using @@ -906,12 +1040,12 @@ translation. So, translatable strings are first marked by the coders within the `C` source files, then gathered in a template file (*calcurse.pot* - the *pot* extension meaning *portable object template*). The content of this template file is then -merged with the translation files for each language (*fr.po* for french, for +merged with the translation files for each language (*fr.po* for French, for instance - with *po* standing for *portable object*, ie meant to be read and edited by humans). A given translation team will take this file, translate its strings, and send it back to the developers. At compilation time, a binary version of this file (for efficiency reasons) will be produced (*fr.mo* - *mo* -stands for *machine object*, ie meant to be read by programs), and then +stands for *machine object*, i.e. meant to be read by programs), and then installed. Then `calcurse` will use this file at runtime, translating the strings according to the locale settings of the user. @@ -1050,7 +1184,7 @@ Using transifex-client You can also use a command line client to submit translations instead of having to use the web interface every time you want to submit an updated version. If -you have a recent version of setuptools installed, you can get the CLI client +you have a recent version of `setuptools` installed, you can get the CLI client by issuing the following command: ---- @@ -1074,7 +1208,7 @@ To submit changes back to the server, use: $ tx push -r calcurse.calcursepot -t -l <locale> ---- -For more details, read up on transifex-client usage at the +For more details, read up on `transifex-client` usage at the http://help.transifex.net/user-guide/client/[The Transifex Command-line Client v0.4] section of the http://help.transifex.net/[Transifex documentation]. |