From ac36e94341ca73d581f0df39f1c7bbf2138b2845 Mon Sep 17 00:00:00 2001 From: Frederic Culot Date: Mon, 31 Jul 2006 21:00:02 +0000 Subject: Initial revision --- doc/manual_en.html | 783 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 783 insertions(+) create mode 100755 doc/manual_en.html (limited to 'doc/manual_en.html') diff --git a/doc/manual_en.html b/doc/manual_en.html new file mode 100755 index 0000000..3b1420b --- /dev/null +++ b/doc/manual_en.html @@ -0,0 +1,783 @@ + + + + + +CALCURSE documentation + + + + +

CALCURSE - text-based organizer

+

+

+ +

Table of Contents

+ +

+ + +

Introduction

+

+ calcurse is a text-based personal organizer + which helps keeping track of events and everyday tasks. + It contains a calendar, a 'todo' list, and puts your + appointments in order. The user interface is configurable, + and one can choose between different color schemes and + layouts. 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 also configurable, and one can choose + between several color and layout combinations. + + +

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/
+
+ +

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).
+ 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, 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

+

+ First you need to gunzip and untar the source archive: + 

+	tar zxvf calcurse-1.4.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: +
    +
  1. ./configure +
  2. make +
  3. make install (may require root privilege) +
+ Use ./configure --help to obtain a list of + possible options. + + +

calcurse basics

+

Invocation

+

Command line arguments

+

+ calcurse takes the following options from the + command line: + +

+
-a +
+ Print the appointments for the current day and exit.
+ Note: the calendar from which to read the appointments + can be specified using the '-c' flag.
+
+
-c +
+ Specify the calendar file to use.
+ The default calendar is ~/.calcurse/apts + (see section calcurse files).
+
+
-d +
+ 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 of the form 'mm/dd/yyyy'. +
  • 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.
+ Note: as for the '-a' flag, the calendar from + which to read the appointments can be specified using + the '-c' flag.
+
+
-h +
+ Print a short help text describing the supported + command-line options, and exit.
+
+
-t +
+ Print the 'todo' list and exit.
+
+
-v +
+ Display calcurse version and exit. +
+ +

Environment variable for i18n

+

+ calcurse can be compiled with native language + support (see 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 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. + +

User interface

+

Non-interactive mode

+

+ When called with at least one of the following arguments:
+ -a, -d, -t, + -h, -v
+ 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 -ta' + in its init config file to display at logon the list of tasks + and appointments scheduled for the current day. + + +

Interactive mode

+

+ 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 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
+ |                                    ||                            |   |
+ |                                    ||                            |   |
+ |                                    ||                            |<--.
+ |                                    ||                            |
+ |                                    ||                            |
+ |                                    ||                            |
+ +------------------------------------++----------------------------+
+ | ? 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 highligth + 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. + In the bottom line of the screen there is a status bar, which + indicates the possible actions and the corresponding keystrokes. + + +

calcurse files

+

+ The following structure is created in your $HOME + directory the first time calcurse is run : + 

+        $HOME/.calcurse/
+                  |___conf
+                  |___apts
+                  |___todo
+
+ The conf file contains the user configuration.
+ The apts file contains all of the events and + user's appointments.
+ The todo file contains the todo list. + + +

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 three 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), and last you can choose between + different general options by pressing 'G'. + +

General options

+

+ These options control calcurse general behavior, + as described below: +

+ + +

Color themes

+

+ calcurse color theme is configurable and is to be + chosen by typing the number corresponding to the desired + theme. This color 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.
+ Notes: +

+ + +

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 + 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. + + +

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)." +
+ +

Reporting bugs and feedback

+

+ Please send bug reports and feedback to: + 

+        calcurse@culot.org
+
+ or to the author: + 
+        frederic@culot.org
+
+ +

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@culot.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 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: +

+ + +

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: +

+ + +

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@culot.org with "subscribe" + in the subject field. + + +

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 : +

+
+ And last, many many thanks to all of the calcurse + users who sent me their feedback. + +
+ +Copyright (c) 2004-2006 Frédéric Culot
+Calcurse version 1.4 - Last change: May 07, 2006 + + + + + -- cgit v1.2.3-54-g00ecf