diff options
Diffstat (limited to 'doc/manual.txt')
| -rw-r--r-- | doc/manual.txt | 1112 |
1 files changed, 1112 insertions, 0 deletions
diff --git a/doc/manual.txt b/doc/manual.txt new file mode 100644 index 0000000..563f9e2 --- /dev/null +++ b/doc/manual.txt @@ -0,0 +1,1112 @@ +//// +/* + * $calcurse: manual.txt,v 1.1 2011/02/24 11:36:50 fleischer Exp $ + * + * Copyright (c) 2004-2010 Frederic Culot <frederic@culot.org> + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * - Redistributions of source code must retain the above + * copyright notice, this list of conditions and the + * following disclaimer. + * + * - Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the + * following disclaimer in the documentation and/or other + * materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ +//// + +CALCURSE - text-based organizer +=============================== + +Abstract +-------- + +This manual describes `calcurse` functionnalities, 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 +procedure is explained, as well as the way one can contribute to `calcurse` +development. + +Introduction +------------ + +`calcurse` is a text-based calendar and scheduling application. It helps +keeping track of events, appointments and everyday tasks. A configurable +notification system reminds user of upcoming deadlines, and the curses based +interface can be customized to suit user needs. All of the commands are +documented within an online help system. + +Overview +-------- + +Creation history +~~~~~~~~~~~~~~~~ + +I started thinking about this project when I was finishing my Ph.D. in +Astrophysics... It started to be a little hard to organize myself, and I really +needed a good tool to help me in that difficult task ;) + +I like programs which use Text User Interfaces, because they are simple, fast, +portable and efficient, so I thought about working on coding a simple calendar +using such an interface. Moreover, I wanted to go on learning the `C` +language, which I only used for a while during my undergraduate studies. So I +thought that would be the good project to start in order to get organized and +to learn about a few `C` things ! + +Unfortunately, I finished my Ph.D. before finishing `calcurse`, but anyway, I +still wanted to work on it, hoping it would be helpful to other people. So +here it is... + +But why _calcurse_ anyway ? Well, it is simply the concatenation of _CALendar_ +and _nCURSEs_, the name of the library used to build the user interface. + +Important features +~~~~~~~~~~~~~~~~~~ + +`Calcurse` is multi-platform and intended to be lightweight, fast and reliable. +It is to be used inside a console or terminal, locally or on a distant machine +within an ssh (or similar) connection. + +`Calcurse` can be run in two different modes : interactive or non-interactive +mode. The first mode allows oneself to view its own personal organizer almost +everywhere, thanks to the text-based interface. The second mode permits to +easily build reminders just by adding `calcurse` with appropriate command line +arguments inside a cron tab or within a shell init script. + +Moreover, `calcurse` was created with the end-user in mind, and tends to be as +friendly as possible. This means a complete on-line help system, together with +having all of the possible actions displayed at any time inside a status bar. +The user interface is configurable, and one can choose between several color +and layout combinations. Key bindings are also configurable, to fit everyone's +needs. Last, a configurable notification system reminds user of upcoming +appointments. The reminders are sent even if the user's interface is not +running, as calcurse is able to run in background. + +Installation +------------ + +Requirements +~~~~~~~~~~~~ + +ncurses library +^^^^^^^^^^^^^^^ + +`Calcurse` requires only a `C` compiler, such as `cc` or `gcc`, and the +`ncurses` library. It would be very surprising not to have a valid `ncurses` +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`. + +[[installation_requirements_gettext]] +gettext library +^^^^^^^^^^^^^^^ + +`calcurse` supports internationalization (*i18n* hereafter) through the +`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 +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 +installed on your system, you can search for the `libintl.h` header file for +instance: + +---- +$ locate libintl.h +---- + +If this header file is not found, then you can obtain the `gettext` sources at +the following url : http://ftp.gnu.org/pub/gnu/gettext/ + +NOTE: Even if `libintl.h` is found on your system, it can be wise to specify + its location during the <<install_process,install process>>, by using the + `--with-libintl-prefix` option with `configure`. Indeed, the `configure` + could fail to locate this library if installed in an uncommon place. + +[[install_process]] +Install process +~~~~~~~~~~~~~~~ + +First you need to gunzip and untar the source archive: + +---- +$ tar zxvf calcurse-2.8.tar.gz +---- + +Once you meet the requirements and have extracted the archive, the install +process is quite simple, and follows the standard three steps process: + +---- +$ ./configure +$ make +$ make install # (may require root privilege) +---- + +Use `./configure --help` to obtain a list of possible options. + +calcurse basics +--------------- + +Invocation +~~~~~~~~~~ + +[[invocation_commandline]] +Command line arguments +^^^^^^^^^^^^^^^^^^^^^^ + +`calcurse` takes the following options from the command line (both short and +long options are supported): + +`-a, --appointment`:: + Print the appointments and events for the current day and exit. The calendar + from which to read the appointments can 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>>). + +`-d <date|num>, --day <date|num>`:: + Print the appointments for the given date or for the given number of + upcoming days, depending on the argument format. Two possible formats are + supported: ++ +-- + * a date (possible formats described below). + * a number `n`. +-- ++ +In the first case, the appointment list for the specified date will be +returned, while in the second case the appointment list for the `n` upcoming +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. ++ +Note: as for the `-a` flag, the calendar from which to read the appointments +can be specified using the `-c` flag. + +`-D <dir>, --directory <dir>`:: + Specify the data directory to use. This option is incompatible with -c. + If not specified, the default directory is `~/.calcurse/`. + +`-h, --help`:: + Print a short help text describing the supported command-line options, + and exit. + +`-i <file>, --import <file>`:: + Import the icalendar data contained in `file`. + +`-n, --next`:: + Print the next appointment within upcoming 24 hours and exit. The indicated + time is the number of hours and minutes left before this appointment. ++ +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. + +`-s[date], --startday[=date]`:: + Print events and appointments from date and exit. If no date is given, the + current day is considered. + +`-S<regex>, --search=<regex>`:: + When used with the `-a`, `-d`, `-r`, `-s`, or `-t` flag, print only the items + having a description that matches the given regular expression. + +`--status`:: + Display the status of running instances of calcurse. If calcurse is + running, this will tell if the interactive mode was launched or if + calcurse is running in background. The process pid will also be indicated. + +`-t[num], --todo[=num]`:: + Print the `todo` list and exit. If the optional number `num` is given, then + only todos having a priority equal to `num` will be returned. The priority + number must be between 1 (highest) and 9 (lowest). It is also possible to + specify `0` for the priority, in which case only completed tasks will be + shown. + +`-v, --version`:: + Display `calcurse` version and exit. + +`-x[format], --export[=format]`:: + Export user data to specified format. Events, appointments and todos are + converted and echoed to stdout. Two possible formats are available: ical and + pcal (see section <<links_others,Links>> below). If the optional + argument `format` is not given, ical format is selected by default. ++ +Note: redirect standard output to export data to a file, by issuing a command +such as: ++ +---- +$ calcurse --export > my_data.dat +---- + +Environment variable for i18n +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +`calcurse` can be compiled with native language support (see +<<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* +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). + +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 +the locale corresponding to the desired language. + +You should also specify the charset to be used, because in some cases the +accents and such are not displayed correctly. This charset is indicated at the +beginning of the po file corresponding to the desired language. For instance, +you can see in the fr.po file that it uses the iso-8859-1 charset, so you could +run `calcurse` using the following command: + +---- +$ LC_ALL=fr_FR.ISO8859-1 calcurse +---- + +Other environment variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following environment variables affect the way `calcurse` operates: + +`VISUAL`:: + Specifies the external editor to use for writing notes. + +`EDITOR`:: + If the `VISUAL` environment variable is not set, then `EDITOR` will be used + as the default external editor. If none of those variables are set, then + `/usr/bin/vi` is used instead. + +`PAGER`:: + Specifies the default viewer to be used for reading notes. If this variable + is not set, then `/usr/bin/less` is used. + +User interface +~~~~~~~~~~~~~~ + +Non-interactive mode +^^^^^^^^^^^^^^^^^^^^ + +When called with at least one of the following arguments: `-a`, `-d`, `-h`, +`-n`, `-t`, `-v`, `-x`, `calcurse` is started in non-interactive mode. This +means the desired information will be displayed, and after that, `calcurse` +simply quits and you are driven back to the shell prompt. + +That way, one can add a line such as `calcurse --todo --appointment` in its +init config file to display at logon the list of tasks and appointments +scheduled for the current day. + +[[basics_interface_interactive]] +Interactive mode +^^^^^^^^^^^^^^^^ + +NOTE: Key bindings that are indicated in this manual correspond to the default + ones, defined when `calcurse` is launched for the first time. If those + key bindings do not suit user's needs, it is possible to change them + within the keys configuration menu (see <<options_keys,key bindings>>). + +When called without any argument or only with the `-c` option, `calcurse` is +started in interactive mode. In this mode, you are shown an interface +containing three different panels which you can browse using the `TAB` key, +plus a notification bar and a status bar (see figure below). + +---- + appointment panel---. .---calendar panel + | | + v v + +------------------------------------++----------------------------+ + | Appointments || Calendar | + |------------------------------------||----------------------------| + | (|) April 6, 2006 || April 2006 | + | ||Mon Tue Wed Thu Fri Sat Sun | + | || 1 2 | + | || 3 4 5 6 7 8 9 | + | || 10 11 12 13 14 15 16 | + | || 17 18 19 20 21 22 23 | + | || 24 25 26 27 28 29 30 | + | || | + | |+----------------------------+ + | |+----------------------------+ + | || ToDo | todo + | ||----------------------------| panel + | || | | + | || | | + | || |<--. + | || | + +------------------------------------++----------------------------+ + |---[ Mon 2006-11-22 | 10:11:43 ]---(apts)----> 01:20 :: lunch <---|<--. + +------------------------------------------------------------------+ notify-bar + | ? Help R Redraw H/L -/+1 Day G GoTo C Config | + | Q Quit S Save J/K -/+1 Week Tab Chg View |<-. + +------------------------------------------------------------------+ | + | + status bar +---- + +The first panel represents a calendar which allows to highlight a particular +day, the second one contains the list of the events and appointments on that +day, and the last one contains a list of tasks to do but which are not assigned +to any specific day. + +Depending on the selected view, the calendar could either display a monthly +(default as shown in previous figure) or weekly view. The weekly view would +look like the following: + +---- ++------------------------------------+ +| Calendar | +|----------------------------(# 13)--| +| Mon Tue Wed Thu Fri Sat Sun | +| 29 30 31 01 02 03 04 | +| <----+-- slice 1: 00:00 to 04:00 AM +| -- -- -- -- -- -- | +| <----+-- slice 2: 04:00 to 08:00 AM +| -- -- -- -- -- -- | +| <----+-- slice 3: 08:00 to 12:00 AM +| - -- -- -- -- -- -- - <-+-- midday +| <----+-- slice 4: 12:00 to 04:00 PM +| -- -- -- -- -- -- | +| <----+-- slice 5: 04:00 to 08:00 PM +| -- -- -- -- -- -- | +| <----+-- slice 6: 08:00 to 12:00 PM ++------------------------------------+ +---- + +The current week number is displayed on the top-right side of the panel (*# 13* +meaning it is the 13th week of the year in the above example). The seven days +of the current week are displayed in column. Each day is divided into slices of +4 hours each (6 slices in total, see figure above). A slice will appear in a +different color if an appointment falls into the corresponding time-slot. + +In the appointment panel, one can notice the *`(|)`* sign just in front of the +date. This indicates the current phase of the moon. Depending on which is the +current phase, the following signs can be seen: + +` |) `:: + first quarter + +` (|) `:: + full moon + +` (| `:: + last quarter + +` | `:: + new moon + +no sign:: + Phase of the moon does not correspond to any of the above ones. + +At the very bottom of the screen there is a status bar, which indicates the +possible actions and the corresponding keystrokes. + +Just above this status bar is the notify-bar, which indicates from left to +right : the current date, the current time, the calendar file currently in use +(apts on the above example, which is the default calendar file, see the +following section), and the next appointment within the upcoming 24 hours. Here +it says that it will be lunch time in one hour and twenty minutes. + +NOTE: Some actions, such as editing or adding an item, require to type in some + text. This is done with the help of the built-in input line editor. + +Within this editor, if a line is longer than the screen width, a `>`, `*`, or +`<` character is displayed in the last column indicating that there are more +character after, before and after, or before the current position, +respectively. The line is scrolled horizontally as necessary. + +Moreover, some editing commands are bound to particular control characters. +Hereafter are indicated the available editing commands (`^` stands for the +control key): + +`^a`:: + moves the cursor to the beginning of the input line + +`^b`:: + moves the cursor backward + +`^d`:: + deletes one character forward + +`^e`:: + moves the cursor to the end of the input line + +`^f`:: + moves the cursor forward + +`^h`:: + deletes one character backward + +`^k`:: + deletes the input from the cursor to the end of the line + +`ESCAPE`:: + cancels the editing + +[[basics_daemon]] +Background mode +~~~~~~~~~~~~~~~ + +When the daemon mode is enabled in the notification configuration menu (see +<<options_notify,Notify-bar settings>>), `calcurse` will stay in background +when the user interface is not running. In background mode, `calcurse` checks +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>>). + +Using the `--status` command line option (see section +<<basics_invocation_commandline,Command line arguments>>), one can know if +`calcurse` is currently running in background or not. If the daemon is +running, a message like the following one will be displayed (the pid of the +daemon process will be shown): + +---- +calcurse is running in background (pid 14536) +---- + +NOTE: To stop the daemon, just send the `TERM` signal to it, using a command + such as: `kill daemon_pid`, where *daemon_pid* is the process id of the + daemon (14536 in the above example). + +[[basics_files]] +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 +: + +---- +$HOME/.calcurse/ + |___notes/ + |___conf + |___keys + |___apts + |___todo +---- +`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. +`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 + +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. + +Import/Export capabilities +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The import and export capabilities offered by `calcurse` are described below. + +Import +^^^^^^ + +Data in icalendar format as described in the rfc2445 specification (see +<<links_others,links>> section below) can be imported into calcurse. Calcurse +ical parser is based on version 2.0 of this specification, but for now on, only +a subset of it is supported. + +The following icalendar properties are handled by calcurse: + +* `VTODO` items: "PRIORITY", "VALARM", "SUMMARY", "DESCRIPTION" + +* `VEVENT` items: "DTSTART", "DTEND", "DURATION", "RRULE", "EXDATE", "VALARM", + "SUMMARY", "DESCRIPTION" + +The icalendar `DESCRIPTION` property will be converted into calcurse format by +adding a note to the item. If a "VALARM" property is found, the item will be +flagged as important and the user will get a notification (this is only +applicable to appointments). + +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" / + "HOURLY" + +* some recurrence keywords are not recognized (all those starting with `BY`): + "BYSECOND" / "BYMINUTE" / "BYHOUR" / "BYDAY" / "BYMONTHDAY" / "BYYEARDAY" / + "BYWEEKNO" / "BYMONTH" / "BYSETPOS" plus "WKST" + +* the recurrence exception keyword "EXRULE" is not recognized + +* timezones are not taken into account + +Export +^^^^^^ + +Two possible export formats are available: `ical` and `pcal` (see section +<<links_others,Links>> below to find out about those formats). + +Online help +~~~~~~~~~~~ + +At any time, the built-in help system can be invoked by pressing the `?` +key. Once viewing the help screens, informations on a specific command can be +accessed by pressing the keystroke corresponding to that command. + +Options +------- + +All of the `calcurse` parameters are configurable from the Configuration menu +available when pressing `C`. You are then driven to a submenu with five +possible choices : pressing `C` again will lead you to the Color scheme +configuration, pressing `L` allows you to choose the layout of the main +`calcurse` screen (in other words, where to put the three different panels on +screen), pressing `G` permits you to choose between different general options, +pressing `K` opens the key bindings configuration menu, and last you can modify +the notify-bar settings by pressing `N`. + +[[options_general]] +General options +~~~~~~~~~~~~~~~ + +These options control `calcurse` general behavior, as described below: + +`auto_save` (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. + +`periodic_save` (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). + +`confirm_quit` (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*):: + 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 + 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 + displayed, together with the name of the file being saved (see section + <<basics_files,calcurse files>>). + +`calendar_default_view` (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. + +`output_datefmt` (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*):: + This option indicates the format that will be used to enter dates in + *calcurse*. Four choices are available: ++ +1. mm/dd/yyyy +2. dd/mm/yyyy +3. yyyy/mm/dd +4. yyyy-mm-dd + +[[options_keys]] +Key bindings +~~~~~~~~~~~~ + +One can define it's own keybindings 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. +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. + +An automatic check is performed to see if the new key binding is not already +set for another action. In that case, you will be asked to choose a different +one. Another check is done when exiting from this menu, to make sure all +possible actions have a key associated with it. + +The following keys can be used to define bindings: + +* lower-case, upper-case letters and numbers, such as `a`, `Z`, `0` + +* CONTROL-key followed by one of the above letters + +* escape, horizontal tab, and space keys + +* arrow keys (up, down, left, and right) + +* `HOME` and `END` keys + +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. + +Color themes +~~~~~~~~~~~~ + +`calcurse` color theme can be customized to suit user's needs. To change the +default theme, the configuration page displays possible choices for foreground +and background colors. Using arrows or calcurse displacement keys to move, and +`X` or space to select a color, user can preview the theme which will be +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 +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 + 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 + `$TERM` variable to another value (such as *xterm-xfree86* for instance). + +Layout configuration +~~~~~~~~~~~~~~~~~~~~ + +The layout corresponds to the position of the panels inside `calcurse` screen. +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 +needs by placing the different panels where needed. + +The following option is used to modify the layout configuration: + +`layout` (default: *0*):: + Eight different layouts are to be chosen from (see layout configuration + screen for the description of the available layouts). + +Sidebar configuration +~~~~~~~~~~~~~~~~~~~~~ + +The sidebar is the part of the screen which contains two panels: the calendar +and, depending on the chosen layout, either the todo list or the appointment +list. + +The following option is used to change the width of the sidebar: + +`side-bar_width` (default: *0*):: + Width (in percentage, 0 being the minimum width) of the side bar. + +[[options_notify]] +Notify-bar settings +~~~~~~~~~~~~~~~~~~~ + +The following options are used to modify the notify-bar behavior: + +`notify-bar_show` (default: *yes*):: + This option indicates if you want the notify-bar to be displayed or not. + +`notify-bar_date` (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*):: + 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*):: + 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 + and knows there will be soon an upcoming appointment. + +`notify-bar_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, + the content of the `$SHELL` environment variable is used. If this variable is + not set, `/bin/sh` is used instead. ++ +==== +Say the `mail` command is available on the user's system, one can use the +following command to get notified by mail of an upcoming appointment (the +appointment description will also be mentioned in the mail body): + +---- +$ calcurse --next | mail -s "[calcurse] upcoming appointment!" user@host.com +---- +==== + +`notify-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*):: + If set to yes, `calcurse` daemon activity will be logged (see section + <<basics_files,files>>). + +Known bugs +---------- + +Incorrect highlighting of items appear when using calcurse black and white +theme together with a `$TERM` variable set to *xterm-color*. To fix this bug, +and as advised by Thomas E. Dickey (`xterm` maintainer), *xterm-xfree86* should +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)." +____ + +[[bugs]] +Reporting bugs and feedback +--------------------------- + +Please send bug reports and feedback to: `calcurse .at. culot .dot. org` or to +the author: `frederic .at. culot .dot. org`. + +[[contribute]] +How to contribute? +------------------ + +If you would like to contribute to the project, you can first send your +feedback on what you like or dislike, and if there are features you miss in +`calcurse`. For now on, possible contributions concern the translation of +`calcurse` messages and documentation. + +NOTE: any help in getting `calcurse` internationalized would be very welcomed, + but before contributing, send a mail to `calcurse-i18n .at. culot .dot. + org` to know if someone already started the translation process into your + language. + +Translating documentation +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The *doc/* directory of the source package already contains translated version +of `calcurse` manual. However, if the manual is not yet available into your +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 +included in the next `calcurse` release. + +calcurse i18n +~~~~~~~~~~~~~ + +As already mentioned, `gettext` utilities are used by `calcurse` to produce +multi-lingual messages. This section provides informations 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 refer to the `GNU gettext` manual at: +http://www.gnu.org/software/gettext/manual/ + +Basically, three different people get involved in the translation chain: +coders, language coordinator, and translators. After a quick overview of how +things work, the translator tasks will be described hereafter. + +Overview +^^^^^^^^ + +To be able to display texts in the native language of the user, two steps are +required: *internationalization* (i18n) and *localization* (l10n). + +i18n is about making `calcurse` support multiple languages. It is performed by +coders, who will mark translatable texts and provide a way to display them +translated at runtime. + +l10n is about making the i18n'ed `calcurse` adapt to the specific language of +the user, ie translating the strings previously marked by the developers, and +setting the environment correctly for `calcurse` to use the result of this +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 +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 +installed. Then `calcurse` will use this file at runtime, translating the +strings according to the locale settings of the user. + + +Translator tasks +^^^^^^^^^^^^^^^^ + +Suppose someone wants to initiate the translation of a new language. Here are +the steps to follow: + +* First, find out what the locale name is. For instance, for french, it is + `fr_FR`, or simply `fr`. This is the value the user will have to put in his + `LC_ALL` environment variable for software to be translated (see + <<basics_invocation_variable,Environment variable for i18n>>). + +* Then, go into the *po/* directory, and create a new po-file + from the template file using the following command: `msginit -i calcurse.pot + -o fr.po -l fr --no-translator` If you do not have `msginit` installed on + your system, simply copy the *calcurse.pot* file to *fr.po* and edit the + header by hand. + +Now, having this *fr.po* file, the translator is ready to begin. + +po-files +^^^^^^^^ + +The format of the po-files is quite simple. Indeed, po-files are made of four +things: + +1. *location lines:* tells you where the strings can be seen (name of file and + line number), in case you need to see a bit of context. + +2. *msgid lines:* the strings to translate. + +3. *msgstr lines:* the translated strings. + +4. *lines prefixed with `#`:* comments (some with a special meaning, as we will + see below). + +Basically, all you have to do is fill the *msgstr* lines with the translation +of the above *msgid* line. + +A few notes: + +*Fuzzy strings*:: + You will meet strings marked with a `"#, fuzzy"` comment. `calcurse` won't + use the translations of such strings until you do something about them. A + string being fuzzy means either that the string has already been translated + but has since been changed in the sources of the program, or that this is a + new string for which `gettext` made a 'wild guess' for the translation, based + on other strings in the file. It means you have to review the translation. + Sometimes, the original string has changed just because a typo has been + fixed. In this case, you won't have to change anything. But sometimes, the + translation will no longer be accurate and needs to be changed. Once you are + done and happy with the translation, just remove the `"#, fuzzy"` line, and + the translation will be used again in `calcurse`. + +*c-format strings and special sequences*:: + Some strings have the following comment: `"#, c-format"`. This tells that + parts of the string to translate have a special meaning for the program, and + that you should leave them alone. For instance, %-sequences, like `"%s"`. + These means that `calcurse` will replace them with another string. So it is + important it remains. There are also \-sequences, like `\n` or `\t`. Leave + them, too. The former represents an end of line, the latter a tabulation. + +*Translations can be wrapped*:: + If lines are too long, you can just break them like this: ++ +---- +msgid "" +"some very long line" +"another line" +---- + +*po-file header*:: + At the very beginning of the po-file, the first string form a header, where + various kind of information has to be filled in. Most important one is the + charset. It should resemble ++ +---- +"Content-Type: text/plain; charset=utf-8\n" +---- ++ +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: ++ +---- +"Last-Translator: Frederic Culot <frederic@culot.org>\n" +---- + +*Comments*:: + Adding comments (lines begining 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 + 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 + be displayed to adapt your translation. + +*A few useful tools*:: + The po-file format is very simple, and the file can be edited with a standard + text editor. But if you prefer, there are few specialized tools you may find + convenient for translating: ++ +* `poEdit` (http://www.poedit.org/) +* `KBabel` (http://i18n.kde.org/tools/kbabel/) +* `GTranslator` (http://gtranslator.sourceforge.net/) +* `Emacs` po mode +* `Vim` po mode + +*And finally*:: + I hope you'll have fun contributing to a more internationalized world. :) If + you have any more questions, don't hesitate to contact me at *frederic .at. + culot .dot. org*. + +Links +----- + +This section contains links and references that may be of interest to you. + +calcurse homepage +~~~~~~~~~~~~~~~~~ + +The `calcurse` homepage can be found at http://culot.org/calcurse + +calcurse announce list +~~~~~~~~~~~~~~~~~~~~~~ + +If you are interested in the project and want to be warned when a new release +comes out, you can subscribe to the `calcurse` announce list. In doing so, you +will receive an email as soon as a new feature appears in `calcurse`. + +To subscribe to this list, send a message to *calcurse-announce .at. culot +.dot. org* with "subscribe" in the subject field. + +calcurse RSS feed +~~~~~~~~~~~~~~~~~ + +Another possibility to get warned when new releases come out is to follow the +RSS feed at: http://culot.org/calcurse/news_rss.xml + +This RSS feed is updated each time a new version of calcurse is available, +describing newly added features. + +[[links_others]] +Other links +~~~~~~~~~~~ + +You may want to look at the ical format specification (rfc2445) at: +http://tools.ietf.org/html/rfc2445 + +The pcal project page can be found at: http://pcal.sourceforge.net/ + +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 + +* Gwen for testing and general discussions about how to improve `calcurse` + +* Herbert for packaging `calcurse` for FreeBSD + +* Zul for packaging `calcurse` for NetBSD + +* Wain, Steffen and Ronald for packaging `calcurse` for Archlinux + +* Kevin, Ryan, and fEnIo for packaging `calcurse` for Debian and Ubuntu + +* Pascal for packaging `calcurse` for Slackware + +* Alexandre and Markus for packaging `calcurse` for Mac OsX and Darwin + +* Igor for packaging `calcurse` for ALT Linux + +* Joel for its calendar script which inspired `calcurse` calendar view + +* Michael Schulz and Chris M. for the german translation of `calcurse` and its + manual + +* Jose Lopez for the spanish translation of `calcurse` and its manual + +* Neil Williams for the english translation + +* Leandro Noferini for the italian translation + +* Tony for its patch which helped improving the recur_item_inday() function, + and for implementing the date format configuration options + +* Jeremy Roon for the dutch translation + +* Erik Saule for its patch implementing the `-N`, `-s`, `-S`, `-r` and `-D` + flags + +* people who write softwares I like and which inspired me, especially : + + - `vim` for the displacement keys + - `orpheus` and `abook` for documentation + - `pine` and `aptitude` for the text user interface + - `tmux` for coding style + +And last, many many thanks to all of the `calcurse` users who sent me their +feedback. |