1332 lines
60 KiB
HTML
1332 lines
60 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
<!--
|
||
/*
|
||
* $calcurse: manual_en.html,v 1.29 2010/03/29 18:18:02 culot 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.
|
||
*/
|
||
-->
|
||
|
||
<html>
|
||
<head>
|
||
<title>CALCURSE documentation</title>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||
<style type="text/css" media="all">
|
||
@import url(manual.css);
|
||
</style>
|
||
</head>
|
||
<body>
|
||
|
||
<div id="mainContent">
|
||
|
||
<h1 id="title">
|
||
<span class="main">CALCURSE - text-based organizer</span></h1>
|
||
|
||
<div class="warn">
|
||
<h1>Abstract</h1> This manual describes <code>calcurse</code> 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
|
||
<code>calcurse</code> behavior. Last, bug reporting procedure is explained, as
|
||
well as the way one can contribute to <code>calcurse</code> development.
|
||
</div>
|
||
|
||
<div id="toc">
|
||
<h1>Table of Contents</h1>
|
||
<ul>
|
||
<li><a href="#intro">1. Introduction</a></li>
|
||
<li><a href="#overview">2. Overview</a>
|
||
<ul>
|
||
<li><a href="#overview_history">2.1 Creation history</a></li>
|
||
<li><a href="#overview_features">2.2 Important features</a></li>
|
||
</ul></li>
|
||
<li><a href="#install">3. Installation</a>
|
||
<ul>
|
||
<li><a href="#install_requirements">3.1 Requirements</a>
|
||
<ul>
|
||
<li><a href="#install_requirements_ncurses">3.1.1 <code>ncurses</code> library</a></li>
|
||
<li><a href="#install_requirements_gettext">3.1.2 <code>gettext</code> library</a></li>
|
||
</ul></li>
|
||
<li><a href="#install_process">3.2 Install process</a></li>
|
||
</ul></li>
|
||
<li><a href="#basics">4. <code>calcurse</code> basics</a>
|
||
<ul>
|
||
<li><a href="#basics_invocation">4.1 Invocation</a>
|
||
<ul>
|
||
<li><a href="#basics_invocation_commandline">4.1.1 Command line arguments</a></li>
|
||
<li><a href="#basics_invocation_variable">4.1.2 Environment variable for i18n</a></li>
|
||
<li><a href="#basics_invocation_environment">4.1.3 Other environment variables</a></li>
|
||
</ul></li>
|
||
<li><a href="#basics_interface">4.2 User interface</a>
|
||
<ul>
|
||
<li><a href="#basics_interface_noninteractive">4.2.1 Non-interactive mode</a></li>
|
||
<li><a href="#basics_interface_interactive">4.2.2 Interactive mode</a></li>
|
||
</ul></li>
|
||
<li><a href="#basics_daemon">4.3 Background mode</a></li>
|
||
<li><a href="#basics_files">4.4 <code>calcurse</code> files</a></li>
|
||
<li><a href="#basics_import_export">4.5 Import/Export capabilities</a>
|
||
<ul>
|
||
<li><a href="#basics_import">4.5.1 Import</a></li>
|
||
<li><a href="#basics_export">4.5.2 Export</a></li>
|
||
</ul></li>
|
||
<li><a href="#basics_help">4.6 Online help</a></li>
|
||
</ul></li>
|
||
<li><a href="#options">5. Options</a>
|
||
<ul>
|
||
<li><a href="#options_general">5.1 General options</a></li>
|
||
<li><a href="#options_keys">5.2 Key bindings</a></li>
|
||
<li><a href="#options_colors">5.3 Color themes</a></li>
|
||
<li><a href="#options_layout">5.4 Layout configuration</a></li>
|
||
<li><a href="#options_sidebar">5.5 Sidebar configuration</a></li>
|
||
<li><a href="#options_notify">5.6 Notify-bar settings</a></li>
|
||
</ul></li>
|
||
<li><a href="#known_bugs">6. Known bugs</a></li>
|
||
<li><a href="#bugs">7. Reporting bugs and feedback</a></li>
|
||
<li><a href="#contribute">8. How to contribute?</a>
|
||
<ul>
|
||
<li><a href="#contribute_documentation">8.1 Translating documentation</a></li>
|
||
<li><a href="#contribute_i18n">8.2 <code>calcurse</code> i18n</a>
|
||
<ul>
|
||
<li><a href="#contribute_i18n_overview">8.2.1 Overview</a></li>
|
||
<li><a href="#contribute_i18n_translator">8.2.2 Translator tasks</a></li>
|
||
<li><a href="#contribute_i18n_po-files">8.2.3 po-files</a></li>
|
||
</ul></li>
|
||
</ul></li>
|
||
<li><a href="#links">9. Links</a>
|
||
<ul>
|
||
<li><a href="#links_homepage">9.1 <code>calcurse</code> homepage</a></li>
|
||
<li><a href="#links_list">9.2 <code>calcurse</code> announce list</a></li>
|
||
<li><a href="#links_rss">9.3 <code>calcurse</code> RSS feed</a></li>
|
||
<li><a href="#links_others">9.4 Other links</a></li>
|
||
</ul></li>
|
||
<li><a href="#thanks">10. Thanks</a></li>
|
||
</ul>
|
||
</div>
|
||
|
||
<h1>1. Introduction<a name="intro"></a></h1>
|
||
<p>
|
||
<code>calcurse</code> 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.
|
||
</p>
|
||
|
||
<h1>2. Overview<a name="overview"></a></h1>
|
||
<h2>2.1 Creation history<a name="overview_history"></a></h2>
|
||
<p>
|
||
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 ;)
|
||
</p>
|
||
<p>
|
||
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 <code>C</code>
|
||
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
|
||
<code>C</code> things !
|
||
</p>
|
||
<p>
|
||
Unfortunately, I finished my Ph.D. before finishing
|
||
<code>calcurse</code>,
|
||
but anyway, I still wanted to work on it, hoping it would
|
||
be helpful to other people. So here it is...
|
||
</p>
|
||
<p>
|
||
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.
|
||
</p>
|
||
|
||
<h2>2.2 Important features<a name="overview_features"></a></h2>
|
||
<p>
|
||
<code>Calcurse</code> 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.
|
||
</p>
|
||
<p>
|
||
<code>Calcurse</code> 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
|
||
<code>calcurse</code> with appropriate command line arguments
|
||
inside a cron tab or within a shell init script.
|
||
</p>
|
||
<p>
|
||
Moreover, <code>calcurse</code> 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.
|
||
</p>
|
||
|
||
<h1>3. Installation<a name="install"></a></h1>
|
||
<h2>3.1 Requirements<a name="install_requirements"></a></h2>
|
||
<h3>3.1.1 <code>ncurses</code> library<a name="install_requirements_ncurses"></a></h3>
|
||
<p>
|
||
<code>Calcurse</code> requires only a <code>C</code> compiler, such as
|
||
<code>cc</code> or <code>gcc</code>, and the <code>ncurses</code>
|
||
library.
|
||
It would be very surprising not to have a valid <code>ncurses</code>
|
||
library already installed on your computer, but if not, you can
|
||
find it at the following url :</p>
|
||
<pre>http://ftp.gnu.org/pub/gnu/ncurses/</pre>
|
||
<p>
|
||
<p class="rq"><span class="valorize">Note:</span>
|
||
It is also possible to link <code>calcurse</code> against the
|
||
<code>ncursesw</code> library (ncurses with support for unicode).
|
||
However, UTF-8 is not yet supported by <code>calcurse</code>.</p>
|
||
|
||
<h3>3.1.2 <code>gettext</code> library<a name="install_requirements_gettext"></a></h3>
|
||
<p>
|
||
<code>calcurse</code> supports internationalization
|
||
(<span class="emp">i18n</span> hereafter) through the <code>gettext</code>
|
||
utilities. This means <code>calcurse</code> can produce
|
||
multi-lingual messages if compiled with native language
|
||
support (i.e. <span class="emp">NLS</span>).
|
||
</p>
|
||
<p>
|
||
However,
|
||
<span class="emp">NLS</span> 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 <code>--disable-nls</code> option to
|
||
<code>configure</code> (see section <a
|
||
href="#install_process">Install process</a>).
|
||
To check if the <code>gettext</code> utilities are
|
||
installed on your system, you can search for the
|
||
<code>libintl.h</code> header file for instance:</p>
|
||
<pre>locate libintl.h</pre>
|
||
<p>
|
||
If this header file is not found, then you can obtain the
|
||
<code>gettext</code> sources at the following url :</p>
|
||
<pre>http://ftp.gnu.org/pub/gnu/gettext/</pre>
|
||
<p>
|
||
<p class="rq"><span class="valorize">Note:</span>
|
||
Even if <code>libintl.h</code> is found on your
|
||
system, it can be wise to specify its location during the <a
|
||
href="#install_process">install process</a>, by using the
|
||
<code>--with-libintl-prefix</code> option with
|
||
<code>configure</code>. Indeed, the <code>configure</code>
|
||
could fail to locate this library if installed in an uncommon
|
||
place.</p>
|
||
|
||
|
||
<h2>3.2 Install process<a name="install_process"></a></h2>
|
||
<p>
|
||
First you need to gunzip and untar the source archive:</p>
|
||
<pre>tar zxvf calcurse-2.8.tar.gz</pre>
|
||
<p>
|
||
Once you meet the requirements and have extracted the archive,
|
||
the install process is quite simple, and follows the standard
|
||
three steps process:
|
||
<ol>
|
||
<li><code>./configure</code></li>
|
||
<li><code>make</code></li>
|
||
<li><code>make install</code> (may require root privilege)</li>
|
||
</ol>
|
||
</p>
|
||
<p>
|
||
Use <code>./configure --help</code> to obtain a list of
|
||
possible options.
|
||
</p>
|
||
|
||
<h1>4. <code>calcurse</code> basics<a name="basics"></a></h1>
|
||
<h2>4.1 Invocation<a name="basics_invocation"></a></h2>
|
||
<h3>4.1.1 Command line arguments<a name="basics_invocation_commandline"></a></h3>
|
||
<p>
|
||
<code>calcurse</code> takes the following options from the
|
||
command line (both short and long options are supported):</p>
|
||
<p>
|
||
|
||
<dl>
|
||
<dt><code>-a, --appointment</code></dt>
|
||
<dd>
|
||
Print the appointments and events for the current day and exit.
|
||
<p class="rq"><span class="valorise">Note:</span> the calendar from
|
||
which to read the appointments can be specified using the '-c'
|
||
flag.</p>
|
||
</dd>
|
||
<dt><code>-c <file>, --calendar <file></code></dt>
|
||
<dd>
|
||
Specify the calendar file to use.
|
||
The default calendar is <code>~/.calcurse/apts</code>
|
||
(see section <a href="#basics_files"><code>calcurse</code>
|
||
files</a>).
|
||
</dd>
|
||
<dt><code>-d <date|num>, --day <date|num></code></dt>
|
||
<dd>
|
||
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:
|
||
<ul>
|
||
<li>a date (possible formats described below).</li>
|
||
<li>a number 'n'.</li>
|
||
</ul>
|
||
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 <code>calcurse -d 3</code>
|
||
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
|
||
<a href="#options_general">General options</a>), using the
|
||
<code>input_datefmt</code> variable.
|
||
|
||
<p class="rq"><span class="valorise">Note:</span> as for the '-a'
|
||
flag, the calendar from which to read the appointments
|
||
can be specified using the '-c' flag.</p>
|
||
</dd>
|
||
<dt><code>-D <dir>, --directory <dir></code></dt>
|
||
<dd>
|
||
Specify the data directory to use. This option is
|
||
incompatible with -c. If not specified, the
|
||
default directory is <code>'~/.calcurse/'</code>.
|
||
</dd>
|
||
<dt><code>-h, --help</code></dt>
|
||
<dd>
|
||
Print a short help text describing the supported
|
||
command-line options, and exit.</dd>
|
||
<dt><code>-i <file>, --import <file></code></dt>
|
||
<dd>
|
||
Import the icalendar data contained in <code>file</code>.
|
||
</dd>
|
||
<dt><code>-n, --next</code></dt>
|
||
<dd>
|
||
Print the next appointment within upcoming 24 hours and exit.
|
||
The indicated time is the number of hours and minutes left
|
||
before this appointment.
|
||
<p class="rq"><span class="valorise">Note:</span> the calendar
|
||
from which to read the appointments can be specified using the
|
||
'-c' flag.</p>
|
||
</dd>
|
||
<dt><code>-N, --note</code></dt>
|
||
<dd>
|
||
When used with the '-a' or '-t' flag, also print note content
|
||
if one is associated with the displayed item.
|
||
</dd>
|
||
<dt><code>-r[num], --range[=num]</code></dt>
|
||
<dd>
|
||
Print events and appointments for the num number of
|
||
days and exit. If no num is given, a range of 1 day
|
||
is considered.
|
||
</dd>
|
||
<dt><code>-s[date], --startday[=date]</code></dt>
|
||
<dd>
|
||
Print events and appointments from date and exit.
|
||
If no date is given, the current day is considered.
|
||
</dd>
|
||
<dt><code>-S<regex>, --search=<regex></code></dt>
|
||
<dd>
|
||
When used with the '-a', '-d', '-r', '-s', or '-t' flag,
|
||
print only the items having a description that matches the given
|
||
regular expression.
|
||
</dd>
|
||
<dt><code>--status</code></dt>
|
||
<dd>
|
||
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.
|
||
</dd>
|
||
<dt><code>-t[num], --todo[=num]</code></dt>
|
||
<dd>
|
||
Print the 'todo' list and exit. If the optional number
|
||
<code>num</code> is given, then only todos having a priority
|
||
equal to <code>num</code> 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.</p>
|
||
</dd>
|
||
<dt><code>-v, --version</code></dt>
|
||
<dd>
|
||
Display <code>calcurse</code> version and exit.
|
||
</dd>
|
||
<dt><code>-x[format], --export[=format]</code></dt>
|
||
<dd>
|
||
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 <a href="#links_others">Links</a> below).
|
||
If the optional argument <code>format</code> is not given,
|
||
ical format is selected by default.
|
||
<p class="rq"><span class="valorise">Note:</span>
|
||
redirect standard output to export data to a file,
|
||
by issuing a command such as:
|
||
<code>$ calcurse --export > my_data.dat</code></p>
|
||
</dd>
|
||
</dl>
|
||
|
||
<h3>4.1.2 Environment variable for i18n<a name="basics_invocation_variable"></a></h3>
|
||
<p>
|
||
<code>calcurse</code> can be compiled with native language
|
||
support (see <a
|
||
href="#install_requirements_gettext"><code>gettext</code>
|
||
library</a>). Thus, if you wish to have messages displayed
|
||
into your native language, first make sure it is available by
|
||
looking at the <code>po/LINGUAS</code> file.
|
||
This file indicates the set of available languages by showing
|
||
the two-letters corresponding code (for exemple,
|
||
<span class="emp">fr</span>
|
||
stands for french). If you do not find your language, it
|
||
would be greatly appreciated if you could help translating
|
||
<code>calcurse</code> (see the <a href="#contribute">How to
|
||
contribute?</a> section).</p>
|
||
<p>
|
||
If your language is available, run
|
||
<code>calcurse</code> with the following command:</p>
|
||
<pre>LC_ALL=fr_FR calcurse</pre>
|
||
<p>
|
||
where <span class="emp">fr_FR</span> is the locale name in this exemple, but
|
||
should be replaced by the locale corresponding to the desired
|
||
language.</p>
|
||
<p>
|
||
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 <code>calcurse</code> using the following command:</p>
|
||
<pre>LC_ALL=fr_FR.ISO8859-1 calcurse</pre>
|
||
|
||
<h3>4.1.3 Other environment variables<a name="basics_invocation_environment"></a></h3>
|
||
<p>
|
||
The following environment variables affect the way <code>calcurse</code>
|
||
operates:</p>
|
||
<dl>
|
||
<dt><code>VISUAL</code></dt>
|
||
<dd>Specifies the external editor to use for writing notes.
|
||
</dd>
|
||
<dt><code>EDITOR</code></dt>
|
||
<dd>If the <code>VISUAL</code> environment variable
|
||
is not set, then <code>EDITOR</code> will be used as
|
||
the default external editor. If none of those variables are set,
|
||
then <code>/usr/bin/vi</code> is used instead.
|
||
</dd>
|
||
<dt><code>PAGER</code></dt>
|
||
<dd>Specifies the default viewer to be used for reading notes.
|
||
If this variable is not set, then <code>/usr/bin/less</code> is used.
|
||
</dd>
|
||
</dl>
|
||
|
||
<h2>4.2 User interface<a name="basics_interface"></a></h2>
|
||
<h3>4.2.1 Non-interactive mode<a name="basics_interface_noninteractive"></a></h3>
|
||
<p>
|
||
When called with at least one of the following arguments:
|
||
<code>-a</code>, <code>-d</code>, <code>-h</code>,
|
||
<code>-n</code>, <code>-t</code>, <code>-v</code>,
|
||
<code>-x</code>,
|
||
<code>calcurse</code> is started in non-interactive mode.
|
||
This means the desired information will be displayed, and
|
||
after that, <code>calcurse</code> simply quits and you are
|
||
driven back to the shell prompt.</p>
|
||
<p>
|
||
That way, one can add a line such as
|
||
<code>'calcurse --todo --appointment'</code>
|
||
in its init config file to display at logon the list of tasks
|
||
and appointments scheduled for the current day. </p>
|
||
|
||
|
||
<h3>4.2.2 Interactive mode<a name="basics_interface_interactive"></a></h3>
|
||
<p>
|
||
<p class="rq"><span class="valorise">Note:</span>
|
||
Key bindings that are indicated in this manual correspond to
|
||
the default ones, defined when <code>calcurse</code> 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 <a href="#options_keys">key bindings</a>).</p>
|
||
|
||
<p>When called without any argument or only with the
|
||
<code>-c</code> option, <code>calcurse</code> 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).</p>
|
||
<pre>
|
||
|
||
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
|
||
|
||
</pre>
|
||
<p>
|
||
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.</p>
|
||
<p>
|
||
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:</p>
|
||
<pre>
|
||
|
||
+------------------------------------+
|
||
| 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
|
||
+------------------------------------+
|
||
|
||
</pre>
|
||
<p>
|
||
The current week number is displayed on the top-right side of the panel
|
||
(<span class="emp"># 13</span> 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.
|
||
</p>
|
||
|
||
<p>
|
||
In the appointment panel, one can notice the <span
|
||
class="emp">'(|)'</span> 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:
|
||
<dl class="compact">
|
||
<dt>'<code> |) </code>':</dt>
|
||
<dd>first quarter</dd>
|
||
<dt>'<code> (|) </code>':</dt>
|
||
<dd>full moon</dd>
|
||
<dt>'<code> (| </code>':</dt>
|
||
<dd>last quarter</dd>
|
||
<dt>'<code> | </code>':</dt>
|
||
<dd>new moon</dd>
|
||
<dt>no sign:</dt>
|
||
<dd>phase of the moon does not correspond to any of
|
||
the above ones</dd>
|
||
</dl>
|
||
</p>
|
||
<p>
|
||
At the very bottom of the screen there is a status bar, which
|
||
indicates the possible actions and the corresponding keystrokes.</p>
|
||
<p>
|
||
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.</p>
|
||
<p class="rq"><span class="valorise">Note:</span>
|
||
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.</p>
|
||
<p>
|
||
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.</p>
|
||
<p>
|
||
Moreover, some editing commands are bound to particular control
|
||
characters. Hereafter are indicated the available editing commands
|
||
('^' stands for the control key):
|
||
<dl class="compact">
|
||
<dt><code>^a</code>:</dt>
|
||
<dd>moves the cursor to the beginning of the input line</dd>
|
||
<dt><code>^b</code>:</dt>
|
||
<dd>moves the cursor backward</dd>
|
||
<dt><code>^d</code>:</dt>
|
||
<dd>deletes one character forward</dd>
|
||
<dt><code>^e</code>:</dt>
|
||
<dd>moves the cursor to the end of the input line</dd>
|
||
<dt><code>^f</code>:</dt>
|
||
<dd>moves the cursor forward</dd>
|
||
<dt><code>^h</code>:</dt>
|
||
<dd>deletes one character backward</dd>
|
||
<dt><code>^k</code>:</dt>
|
||
<dd>deletes the input from the cursor to the end of the line</dd>
|
||
<dt><code>ESCAPE</code>:</dt>
|
||
<dd>cancels the editing</dd>
|
||
</dl>
|
||
</p>
|
||
|
||
<h2>4.3 Background mode<a name="basics_daemon"></a></h2>
|
||
|
||
<p>When the daemon mode is enabled in the notification configuration menu
|
||
(see <a href="#options_notify">Notify-bar settings</a>), <code>calcurse</code> will stay
|
||
in background when the user interface is not running. In background mode,
|
||
<code>calcurse</code> checks for upcoming appointments and runs the user-defined
|
||
notification command when necessary. When the user interface is started again,
|
||
the daemon automatically stops.</p>
|
||
|
||
<p><code>calcurse</code> background activity can be logged (set the
|
||
<code>notify-daemon_log</code> variable in the notification configuration
|
||
<a href="#options_notify">menu</a>), and in that case, information about the daemon
|
||
start and stop time, reminders' command launch time, signals received... will be written
|
||
in the <code>daemon.log</code> file (see section <a href="#basics_files">files</a>).</p>
|
||
|
||
<p>
|
||
Using the <code>--status</code> command line option (see section
|
||
<a href="#basics_invocation_commandline">Command line arguments</a>),
|
||
one can know if <code>calcurse</code> 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):
|
||
<pre>calcurse is running in background (pid 14536)</pre>
|
||
|
||
<p class="rq"><span class="valorise">Note:</span>
|
||
To stop the daemon, just send the <code>TERM</code> signal to it, using a command such as:
|
||
<code>'kill daemon_pid'</code>, where <span class="emp">daemon_pid</span> is the process id
|
||
of the daemon (14536 in the above example).
|
||
</p>
|
||
|
||
|
||
<h2>4.4 <code>calcurse</code> files<a name="basics_files"></a></h2>
|
||
<p>
|
||
The following structure is created in your <code>$HOME</code>
|
||
directory (or in the directory you specified with the -D option)
|
||
the first time <code>calcurse</code> is run :</p>
|
||
<pre>
|
||
$HOME/.calcurse/
|
||
|___notes/
|
||
|___conf
|
||
|___keys
|
||
|___apts
|
||
|___todo
|
||
</pre>
|
||
<dl class="compact">
|
||
<dt><code>notes/</code>:</dt>
|
||
<dd>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.</dd>
|
||
<dt><code>conf</code>:</dt>
|
||
<dd>this file contains the user configuration</dd>
|
||
<dt><code>keys</code>:</dt>
|
||
<dd>this file contains the user-defined key bindings</dd>
|
||
<dt><code>apts</code>:</dt>
|
||
<dd>this file contains all of the events and user's appointments</dd>
|
||
<dt><code>todo</code>:</dt>
|
||
<dd>this file contains the todo list</dd>
|
||
</dl>
|
||
|
||
<p class="rq"><span class="valorise">Note:</span>
|
||
If the logging of calcurse daemon activity was set in the notification
|
||
configuration menu, the extra file <code>daemon.log</code> will appear
|
||
in calcurse data directory. This file contains logs about calcurse activity
|
||
when running in background.
|
||
</p>
|
||
|
||
<h2>4.5 Import/Export capabilities<a name="basics_import_export"></a></h2>
|
||
<p>
|
||
The import and export capabilities offered by <code>calcurse</code>
|
||
are described below.
|
||
</p>
|
||
|
||
<h3>4.5.1 Import<a name="basics_import"></a></h3>
|
||
<p>
|
||
Data in icalendar format as described in the rfc2445 specification
|
||
(see <a href="#links_others">links</a> 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.
|
||
</p>
|
||
<p>
|
||
The following icalendar properties are handled by calcurse:
|
||
<ul>
|
||
<li><code>VTODO</code> items:<br>
|
||
"PRIORITY", "VALARM", "SUMMARY", "DESCRIPTION"</li>
|
||
<li><code>VEVENT</code> items:<br>
|
||
"DTSTART", "DTEND", "DURATION", "RRULE", "EXDATE", "VALARM", "SUMMARY",
|
||
"DESCRIPTION"</li>
|
||
</ul>
|
||
</p>
|
||
<p>
|
||
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).
|
||
</p>
|
||
<p>
|
||
Here are the properties that are not implemented:
|
||
<ul>
|
||
<li>negative time durations are not taken into account (item is skipped)</li>
|
||
<li>some recurence frequences are not recognize:<br>
|
||
"SECONDLY" / "MINUTELY" / "HOURLY"</li>
|
||
<li>some recurrence keywords are not recognized
|
||
(all those starting with 'BY'):<br>
|
||
"BYSECOND" / "BYMINUTE" / "BYHOUR" / "BYDAY" / "BYMONTHDAY"<br>
|
||
"BYYEARDAY" / "BYWEEKNO" / "BYMONTH" / "BYSETPOS"<br>
|
||
plus "WKST"</li>
|
||
<li>the recurrence exception keyword "EXRULE" is not recognized</li>
|
||
<li>timezones are not taken into account</li>
|
||
</ul>
|
||
</p>
|
||
|
||
<h3>4.5.2 Export<a name="basics_export"></a></h3>
|
||
<p>
|
||
Two possible export formats are available: <code>ical</code> and
|
||
<code>pcal</code> (see section <a href="#links_others">Links</a> below
|
||
to find out about those formats).
|
||
</p>
|
||
|
||
<h2>4.6 Online help<a name="basics_help"></a></h2>
|
||
<p>
|
||
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.
|
||
</p>
|
||
|
||
<h1>5. Options<a name="options"></a></h1>
|
||
<p>
|
||
All of the <code>calcurse</code> 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
|
||
<code>calcurse</code> 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'.</p>
|
||
|
||
<h2>5.1 General options<a name="options_general"></a></h2>
|
||
<p>
|
||
These options control <code>calcurse</code> general behavior,
|
||
as described below:</p>
|
||
<dl>
|
||
<dt><code>auto_save</code>
|
||
(default: <span class="emp">yes</span>)</dt>
|
||
<dd>This option allows to automatically save the user's data
|
||
(if set to <span class="emp">yes</span>) when quitting.
|
||
<p class="rq"><span class="valorise">warning:</span>
|
||
No data will be automatically saved if
|
||
<code>auto_save</code> is set to <span class="emp">no</span>.
|
||
This means the user must press 'S' (for saving) in order to
|
||
retrieve its modifications.</p>
|
||
</dd>
|
||
<dt><code>periodic_save</code>
|
||
(default: <span class="emp">0</span>)</dt>
|
||
<dd>If different from '0', user's data will be automatically
|
||
saved every <span class="emp">periodic_save</span> minutes.
|
||
When an automatic save is performed, two asterisks
|
||
(i.e. '<code>**</code>') will appear on the top right-hand side
|
||
of the screen).</p>
|
||
</dd>
|
||
<dt><code>confirm_quit</code>
|
||
(default: <span class="emp">yes</span>)</dt>
|
||
<dd>If set to <span class="emp">yes</span>, confirmation is required before
|
||
quitting, otherwise pressing 'Q' will cause <code>calcurse</code>
|
||
to quit without prompting for user confirmation.
|
||
</dd>
|
||
<dt><code>confirm_delete</code> (default: <span class="emp">yes</span>)</dt>
|
||
<dd>If this option is set to <span class="emp">yes</span>, pressing 'D' for
|
||
deleting an item (either a <span class="emp">todo</span>,
|
||
<span class="emp">appointment</span>,
|
||
or <span class="emp">event</span>), 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.
|
||
</dd>
|
||
<dt><code>skip_system_dialogs</code>
|
||
(default: <span class="emp">no</span>)</dt>
|
||
<dd>Setting this option to <span class="emp">yes</span> 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.
|
||
</dd>
|
||
<dt><code>skip_progress_bar</code>
|
||
(default: <span class="emp">no</span>)</dt>
|
||
<dd>If set to <span class="emp">yes</span>, this will cause the disappearing of the
|
||
progress bar which is usually shown when saving data to file.
|
||
If set to <span class="emp">no</span>, this bar will be displayed, together with
|
||
the name of the file being saved
|
||
(see section <a href="#basics_files"><code>calcurse</code> files</a>).
|
||
</dd>
|
||
<dt><code>calendar_default_view</code>
|
||
(default: <span class="emp">0</span>)</dt>
|
||
<dd>If set to <span class="emp">0</span>, the monthly calendar view will be
|
||
displayed by default otherwise it is the weekly view that will be displayed.
|
||
</dd>
|
||
<dt><code>week_begins_on_monday</code>
|
||
(default: <span class="emp">yes</span>)</dt>
|
||
<dd>One can choose between Monday and Sunday as the first day of the
|
||
week. If the option <code>week_begins_on_monday</code> is set to
|
||
<span class="emp">yes</span>, Monday will be first in the calendar view. Else if
|
||
the option is set to <span class="emp">no</span>, then Sunday will be the first
|
||
day of the week.</dd>
|
||
<dt><code>output_datefmt</code>
|
||
(default: <span class="emp">%D</span>)</dt>
|
||
<dd>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: <span class="emp">mm/dd/aa</span>.
|
||
You can see all of the possible formats by typing <code>man 3 strftime</code>
|
||
inside a terminal.</dd>
|
||
<dt><code>input_datefmt</code>
|
||
(default: <span class="emp">1</span>)</dt>
|
||
<dd>This option indicates the format that will be used to enter dates in
|
||
<span class="emp">calcurse</span>. Four choices are available:
|
||
<ol>
|
||
<li>mm/dd/yyyy</li>
|
||
<li>dd/mm/yyyy</li>
|
||
<li>yyyy/mm/dd</li>
|
||
<li>yyyy-mm-dd</li>
|
||
</ol>
|
||
</dd>
|
||
</dl>
|
||
|
||
|
||
<h2>5.2 Key bindings<a name="options_keys"></a></h2>
|
||
<p>
|
||
One can define it's own keybindings within the 'Keys' configuration
|
||
menu. The default keys look like the one used by the <code>vim</code>
|
||
editor, especially the displacement keys. Anyway, within this
|
||
configuration menu, users can redefine all of the keys available from
|
||
within calcurse's user interface.</p>
|
||
<p>
|
||
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.</p>
|
||
<p>
|
||
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.</p>
|
||
<p>
|
||
The following keys can be used to define bindings:
|
||
<ul>
|
||
<li>lower-case, upper-case letters and numbers, such as 'a', 'Z', '0'</li>
|
||
<li>CONTROL-key followed by one of the above letters</li>
|
||
<li>escape, horizontal tab, and space keys</li>
|
||
<li>arrow keys (up, down, left, and right)</li>
|
||
<li>'HOME' and 'END' keys</li>
|
||
</ul> </p>
|
||
<p>
|
||
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.</p>
|
||
|
||
|
||
<h2>5.3 Color themes<a name="options_colors"></a></h2>
|
||
<p>
|
||
<code>calcurse</code> 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.</p>
|
||
<p>
|
||
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.</p>
|
||
<p class="rq"><span class="valorise">Notes:</span>
|
||
Depending on your terminal type and on the value of the
|
||
<code>$TERM</code> 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 <code>calcurse</code> to display them, try to set your
|
||
<code>$TERM</code> variable to another value (such as
|
||
<span class="emp">xterm-xfree86</span> for instance).
|
||
</p>
|
||
|
||
|
||
<h2>5.4 Layout configuration<a name="options_layout"></a></h2>
|
||
<p>
|
||
The layout corresponds to the position of the panels inside
|
||
<code>calcurse</code> 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
|
||
<a href="#basics_interface_interactive">Interactive mode</a>
|
||
for an exemple of the default layout).
|
||
By choosing another layout in the configuration screen, user
|
||
can customize <code>calcurse</code> appearence to best suit
|
||
his needs by placing the different panels where needed.</p>
|
||
<p>
|
||
The following option is used to modify the layout configuration:</p>
|
||
<dl>
|
||
<dt><code>layout</code>
|
||
(default: <span class="emp">0</span>)</dt>
|
||
<dd>Eight different layouts are to be chosen from (see layout
|
||
configuration screen for the description of the available layouts).</dd>
|
||
</dl>
|
||
|
||
<h2>5.5 Sidebar configuration<a name="options_sidebar"></a></h2>
|
||
<p>
|
||
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.</p>
|
||
<p>
|
||
The following option is used to change the width of the sidebar:</p>
|
||
<dl>
|
||
<dt><code>side-bar_width</code>
|
||
(default: <span class="emp">0</span>)</dt>
|
||
<dd>Width (in percentage, 0 being the minimum width) of the side bar.</dd>
|
||
</dl>
|
||
|
||
|
||
<h2>5.6 Notify-bar settings<a name="options_notify"></a></h2>
|
||
<p>
|
||
The following options are used to modify the notify-bar behavior:</p>
|
||
<dl>
|
||
<dt><code>notify-bar_show</code>
|
||
(default: <span class="emp">yes</span>)</dt>
|
||
<dd>This option indicates if you want the notify-bar to be displayed
|
||
or not.</dd>
|
||
<dt><code>notify-bar_date</code>
|
||
(default: <span class="emp">%a %F</span>)</dt>
|
||
<dd>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 <code>man 3 strftime</code>
|
||
inside a terminal.</dd>
|
||
<dt><code>notify-bar_time</code>
|
||
(default: <span class="emp">%T</span>)</dt>
|
||
<dd>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 <code>man 3 strftime</code>
|
||
inside a terminal.</dd>
|
||
<dt><code>notify-bar_warning</code>
|
||
(default: <span class="emp">300</span>)</dt>
|
||
<dd>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 <code>notify-bar_command</code>
|
||
option will be launched.
|
||
That way, the user is warned and knows there
|
||
will be soon an upcoming appointment.
|
||
</dd>
|
||
<dt><code>notify-bar_command</code>
|
||
(default: <span class="emp">printf '\a'</span>)</dt>
|
||
<dd>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 <code>$SHELL</code> environment variable
|
||
is used. If this variable is not set, <code>/bin/sh</code> is used
|
||
instead.
|
||
<p class="rq"><span class="valorise">Example:</span>
|
||
Say the <code>mail</code> 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):</p>
|
||
<code>
|
||
calcurse --next | mail -s "[calcurse] upcoming appointment!" user@host.com
|
||
</code>
|
||
</dd>
|
||
<dt><code>notify-daemon_enable</code>
|
||
(default: <span class="emp">no</span>)</dt>
|
||
<dd>If set to yes, daemon mode will be enabled, meaning <code>calcurse</code>
|
||
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 <a href="#basics_daemon">'Background mode'</a>.
|
||
</dd>
|
||
<dt><code>notify-daemon_log</code>
|
||
(default: <span class="emp">no</span>)</dt>
|
||
<dd>If set to yes, <code>calcurse</code> daemon activity will be logged (see section
|
||
<a href="#basics_files">files</a>).
|
||
</dd>
|
||
</dl>
|
||
|
||
<h1>6. Known bugs<a name="known_bugs"></a></h1>
|
||
<p>
|
||
Incorrect highlighting of items appear when using calcurse
|
||
black and white theme together with a <code>$TERM</code>
|
||
variable set to <span class="emp">xterm-color</span>.
|
||
To fix this bug, and as advised by Thomas E. Dickey
|
||
(<code>xterm</code> maintainer), <span class="emp">xterm-xfree86</span>
|
||
should be used instead of <span class="emp">xterm-color</span> to set
|
||
the <code>$TERM</code> variable:</p>
|
||
<blockquote class="rq">
|
||
"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)."
|
||
</blockquote>
|
||
|
||
<h1>7. Reporting bugs and feedback<a name="bugs"></a></h1>
|
||
<p>
|
||
Please send bug reports and feedback to:</p>
|
||
<pre>calcurse .at. culot .dot. org</pre>
|
||
<p>
|
||
or to the author:</p>
|
||
<pre>frederic .at. culot .dot. org</pre>
|
||
|
||
<h1>8. How to contribute?<a name="contribute"></a></h1>
|
||
<p>
|
||
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 <code>calcurse</code>.
|
||
For now on, possible contributions concern the translation
|
||
of <code>calcurse</code> messages and documentation. </p>
|
||
<p class="rq"><span class="valorise">Note:</span>
|
||
any help in getting <code>calcurse</code>
|
||
internationalized would be very welcomed, but before
|
||
contributing, send a mail to
|
||
<code>calcurse-i18n .at. culot .dot. org</code> to know if someone
|
||
already started the translation process into your language.</p>
|
||
|
||
<h2>8.1 Translating documentation<a name="contribute_documentation"></a></h2>
|
||
<p>
|
||
The <span class="emp">doc/</span> directory of the source package already
|
||
contains translated version of <code>calcurse</code>
|
||
manual. However, if the manual is not yet available into your
|
||
native language, it would be appreciated if you could help
|
||
translating it.</p>
|
||
<p>
|
||
To do so, just copy one of the existing manual
|
||
file to <code>manual_XX.html</code>, where <span class="emp">XX</span>
|
||
identifies your language. Then translate this newly created
|
||
file and send it to the author (see <a href="#bugs">Reporting
|
||
bugs and feeback</a>), so that it can be included in the
|
||
next <code>calcurse</code> release.</p>
|
||
|
||
<h2>8.2 <code>calcurse</code> i18n<a name="contribute_i18n"></a></h2>
|
||
<p>
|
||
As already mentioned, <code>gettext</code> utilities are used
|
||
by <code>calcurse</code> 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 <code>gettext</code> for <code>calcurse</code>
|
||
specifically. For more comprehensive informations or to grasp
|
||
the Big Picture of Native Language Support, you should refer
|
||
to the <code>GNU gettext</code> manual at:</p>
|
||
<pre>http://www.gnu.org/software/gettext/manual/ </pre>
|
||
<p>
|
||
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.</p>
|
||
|
||
|
||
<h3>8.2.1 Overview<a name="contribute_i18n_overview"></a></h3>
|
||
<p>
|
||
To be able to display texts in the native language of the
|
||
user, two steps are required: <span class="emp">internationalization</span>
|
||
(i18n) and <span class="emp">localization</span> (l10n).</p>
|
||
<p>
|
||
i18n is about making
|
||
<code>calcurse</code> support multiple languages. It is
|
||
performed by coders, who will mark translatable texts and
|
||
provide a way to display them translated at runtime.</p>
|
||
<p>
|
||
l10n is
|
||
about making the i18n'ed <code>calcurse</code> adapt to the
|
||
specific language of the user, ie translating the strings
|
||
previously marked by the developers, and setting the
|
||
environment correctly for <code>calcurse</code> to use the
|
||
result of this translation.</p>
|
||
<p>
|
||
So, translatable strings are first marked by the coders within
|
||
the <code>C</code> source files, then gathered in a template
|
||
file (<span class="emp">calcurse.pot</span> - the <span class="emp">pot</span> extension
|
||
meaning <span class="emp">portable object template</span>). The content of
|
||
this template file is then merged with the translation files
|
||
for each language (<span class="emp">fr.po</span> for french, for instance -
|
||
with <span class="emp">po</span> standing for <span class="emp">portable object</span>, 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
|
||
(<span class="emp">fr.mo</span> - <span class="emp">mo</span> stands for
|
||
<span class="emp">machine
|
||
object</span>, ie meant to be read by programs), and then
|
||
installed. Then <code>calcurse</code> will use this file at
|
||
runtime, translating the strings according to the locale
|
||
settings of the user.</p>
|
||
|
||
|
||
<h3>8.2.2 Translator tasks<a name="contribute_i18n_translator"></a></h3>
|
||
<p>
|
||
Suppose someone wants to initiate the translation of a new
|
||
language. Here are the steps to follow:</p>
|
||
<ul>
|
||
<li>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 <code>LC_ALL</code> environment
|
||
variable for software to be translated (see <a
|
||
href="#basics_invocation_variable">Environment variable for
|
||
i18n</a>).</li>
|
||
<li>Then, go into the <span class="emp">po/</span> directory, and create a new po-file
|
||
from the template file using the following command:
|
||
<code>'msginit -i calcurse.pot -o fr.po -l fr --no-translator'</code>
|
||
If you do not have <code>msginit</code> installed on your
|
||
system, simply copy the <span class="emp">calcurse.pot</span> file to
|
||
<span class="emp">fr.po</span> and edit the header by hand.</li>
|
||
</ul>
|
||
<p>
|
||
Now, having this <span class="emp">fr.po</span> file, the translator is ready
|
||
to begin.</p>
|
||
|
||
|
||
<h3>8.2.3 po-files<a name="contribute_i18n_po-files"></a></h3>
|
||
<p>
|
||
The format of the po-files is quite simple. Indeed, po-files
|
||
are made of four things:</p>
|
||
<ol>
|
||
<li><span class="emp">location lines:</span> tells you where the strings can
|
||
be seen (name of file and line number), in case you need to
|
||
see a bit of context.</li>
|
||
<li><span class="emp">msgid lines:</span> the strings to translate.</li>
|
||
<li><span class="emp">msgstr lines:</span> the translated strings.</li>
|
||
<li><span class="emp">lines prefixed with '#':</span> comments (some with a
|
||
special meaning, as we will see below).</li>
|
||
</ol>
|
||
<p>
|
||
Basically, all you have to do is fill the <span class="emp">msgstr</span>
|
||
lines with the translation of the above <span class="emp">msgid</span>
|
||
line.</p>
|
||
<p>
|
||
<span class="valorise">A few notes:</span>
|
||
<dl>
|
||
<dt><span class="emp">Fuzzy strings</span></dt>
|
||
<dd>You will meet strings marked with a <code>"#, fuzzy"</code>
|
||
comment. <code>calcurse</code> 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
|
||
<code>gettext</code> 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
|
||
<code>"#, fuzzy"</code> line, and the translation will be used
|
||
again in <code>calcurse</code>.</dd>
|
||
<dt><span class="emp">c-format strings and special sequences</span></dt>
|
||
<dd>Some strings have the following comment: <code>"#,
|
||
c-format"</code>. 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
|
||
<code>"%s"</code>. These means that <code>calcurse</code> will
|
||
replace them with another string. So it is important it
|
||
remains. There are also \-sequences, like <code>\n</code> or
|
||
<code>\t</code>. Leave them, too. The former represents an end
|
||
of line, the latter a tabulation.</dd>
|
||
<dt><span class="emp">Translations can be wrapped</span></dt>
|
||
<dd>If lines are too long, you can just break them like this:
|
||
<pre>
|
||
msgid ""
|
||
"some very long line"
|
||
"another line"
|
||
</pre></dd>
|
||
<dt><span class="emp">po-file header</span></dt>
|
||
<dd>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
|
||
<pre>
|
||
"Content-Type: text/plain; charset=utf-8\n"
|
||
</pre>
|
||
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:
|
||
<pre>
|
||
"Last-Translator: Frederic Culot <frederic@culot.org>\n"
|
||
</pre></dd>
|
||
<dt><span class="emp">Comments</span></dt>
|
||
<dd>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.</dd>
|
||
<dt><span class="emp">Strings size</span></dt>
|
||
<dd><code>calcurse</code> 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.</dd>
|
||
<dt><span class="emp">A few useful tools</span></dt>
|
||
<dd>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:
|
||
<ul>
|
||
<li><code>poEdit</code> (<a
|
||
href="http://www.poedit.org/" target="_blank">
|
||
http://www.poedit.org/</a>)</li>
|
||
<li><code>KBabel</code> (<a
|
||
href="http://i18n.kde.org/tools/kbabel/" target="_blank">
|
||
http://i18n.kde.org/tools/kbabel/</a>)</li>
|
||
<li><code>GTranslator</code> (<a
|
||
href="http://gtranslator.sourceforge.net/" target="_blank">
|
||
http://gtranslator.sourceforge.net/</a>)</li>
|
||
<li><code>Emacs</code> po mode</li>
|
||
<li><code>Vim</code> po mode</li>
|
||
</ul>
|
||
</dd>
|
||
<dt><span class="emp">And finally</span></dt>
|
||
<dd>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
|
||
<span class="emp">frederic .at. culot .dot. org</span>.</dd>
|
||
</dl>
|
||
|
||
|
||
<h1>9. Links<a name="links"></a></h1>
|
||
<p>
|
||
This section contains links and references that may be of
|
||
interest to you.</p>
|
||
|
||
<h2>9.1 <code>calcurse</code> homepage<a name="links_homepage"></a></h2>
|
||
<p>
|
||
The <code>calcurse</code> homepage can be found at </p>
|
||
<pre>http://culot.org/calcurse</pre>
|
||
|
||
<h2>9.2 <code>calcurse</code> announce list<a name="links_list"></a></h2>
|
||
<p>
|
||
If you are interested in the project and want to be warned
|
||
when a new release comes out, you can subscribe to the
|
||
<code>calcurse</code> announce list. In doing so, you will
|
||
receive an email as soon as a new feature appears in
|
||
<code>calcurse</code>.</p>
|
||
<p>
|
||
To subscribe to this list, send a message to
|
||
<span class="emp">calcurse-announce .at. culot .dot. org</span>
|
||
with "subscribe" in the subject field.</p>
|
||
|
||
<h2>9.3 <code>calcurse</code> RSS feed<a name="links_rss"></a></h2>
|
||
<p>
|
||
Another possibility to get warned when new releases come out
|
||
is to follow the RSS feed at:</p>
|
||
<pre>http://culot.org/calcurse/news_rss.xml</pre>
|
||
<p>
|
||
This RSS feed is updated each time a new version of calcurse is
|
||
available, describing newly added features.</p>
|
||
|
||
<h2>9.4 Other links<a name="links_others"></a></h2>
|
||
<p>
|
||
You may want to look at the ical format specification (rfc2445) at:
|
||
<pre>http://tools.ietf.org/html/rfc2445</pre>
|
||
<p>
|
||
The pcal project page can be found at:
|
||
<pre>http://pcal.sourceforge.net/</pre>
|
||
|
||
<h1>10. Thanks<a name="thanks"></a></h1>
|
||
<p>
|
||
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 :
|
||
<ul>
|
||
<li>Alex for its patches, help and advices with <code>C</code> programming</li>
|
||
<li>Gwen for testing and general discussions about how to
|
||
improve <code>calcurse</code></li>
|
||
<li>Herbert for packaging <code>calcurse</code> for FreeBSD</li>
|
||
<li>Zul for packaging <code>calcurse</code> for NetBSD</li>
|
||
<li>Wain, Steffen and Ronald for packaging <code>calcurse</code> for Archlinux</li>
|
||
<li>Kevin, Ryan, and fEnIo for packaging <code>calcurse</code> for Debian
|
||
and Ubuntu</li>
|
||
<li>Pascal for packaging <code>calcurse</code> for Slackware</li>
|
||
<li>Alexandre and Markus for packaging <code>calcurse</code> for Mac OsX
|
||
and Darwin</li>
|
||
<li>Igor for packaging <code>calcurse</code> for ALT Linux</li>
|
||
<li>Joel for its calendar script which inspired <code>calcurse</code>
|
||
calendar view</li>
|
||
<li>Michael Schulz and Chris M. for the german translation of
|
||
<code>calcurse</code> and its manual</li>
|
||
<li>Jose Lopez for the spanish translation of
|
||
<code>calcurse</code> and its manual</li>
|
||
<li>Neil Williams for the english translation</li>
|
||
<li>Leandro Noferini for the italian translation</li>
|
||
<li>Tony for its patch which helped improving the
|
||
recur_item_inday() function, and for implementing the date format configuration
|
||
options</li>
|
||
<li>Jeremy Roon for the dutch translation</li>
|
||
<li>Erik Saule for its patch implementing the '-N', '-s', '-S', '-r' and '-D' flags</li>
|
||
<li>people who write softwares I like and which inspired me,
|
||
especially :
|
||
<ul>
|
||
<li><code>vim</code> for the displacement keys</li>
|
||
<li><code>orpheus</code> and <code>abook</code> for documentation</li>
|
||
<li><code>pine</code> and <code>aptitude</code>
|
||
for the text user interface</li>
|
||
<li><code>tmux</code> for coding style</li>
|
||
</ul></li>
|
||
</ul>
|
||
</p>
|
||
<p>
|
||
And last, many many thanks to all of the <code>calcurse</code>
|
||
users who sent me their feedback.</p>
|
||
|
||
<div class="footer">
|
||
Copyright © 2004-2010 Fr<46>d<EFBFBD>ric Culot<br>
|
||
Calcurse version 2.8 - Last change: March 29, 2010<br>
|
||
</div>
|
||
</div>
|
||
|
||
</body>
|
||
</html>
|