CALCURSE - text-based organizer
calcurse basics
	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.
  	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.
        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.
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.
 
First you need to gunzip and untar the source archive:
tar zxvf calcurse-1.7.tar.gzOnce 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)
	./configure --help to obtain a list of 
	possible options.
calcurse basics
        calcurse takes the following options from the 
        command line (both short and long options are supported):
	
-a, --appointment
	-c <file>, --calendar <file>
	~/.calcurse/apts 
	(see section calcurse files).-d <date|num>, --day <date|num>
	calcurse -d  3  
	will  display your  appointments  for  today, tomorrow, 
	and the day after tomorrow.-h, --help
	-n, --next
	-t[num], --todo[=num]
	num is given, then only todos having a priority
	equal to num will be returned.-v, --version
	calcurse version and exit.
	
        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.calcurse using the following command:
	LC_ALL=fr_FR.ISO8859-1 calcurse
        When called with at least one of the following arguments:
        -a, -d, -h, 
        -n, -t, -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 --todo --appointment' 
        in its init config file to display at logon the list of tasks 
        and appointments scheduled for the current day. 
        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.
	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):
	
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.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.
	All of the calcurse parameters are configurable from the 
	Configuration menu available when pressing 'C'. You are then 
	driven to a submenu with four 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, and last you can modify the notify-bar
	settings by pressing 'N'.
        These options control calcurse general behavior,
        as described below:
        
auto_save  (default: yes)auto_save is set to no. This means
	the user must press 'S' (for saving) in order to retrieve its
	modifications.confirm_quit (default: yes)calcurse 
	to quit without prompting for user confirmation.confirm_delete (default: yes)skip_system_dialogs (default: no)skip_progress_bar (default: no)calcurse files).week_begins_on_monday (default: yes)
        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: 
        
$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.calcurse to display them, try to set your
        $TERM variable to another value (such as
        xterm-xfree86 for instance).
        
        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.
The following options are used to modify the notify-bar behavior:
notify-bar_show (default: yes)notify-bar_date (default: %a %F)notify-bar_time (default: %T)notify-bar_warning (default: 300)
        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)."
Please send bug reports and feedback to:
        calcurse@culot.org
        
        or to the author:
        
        frederic@culot.org
        
        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.
        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.
        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.
Suppose someone wants to initiate the translation of a new language. Here are the steps to follow:
LC_ALL environment
        variable for software to be translated (see Environment variable for
        i18n).
                '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.The format of the po-files is quite simple. Indeed, po-files are made of four things:
A few notes:
"#, 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".  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.
                msgid ""
                "some very long line"
                "another line"
        
        
                "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"
        
        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.poEdit (
           http://www.poedit.org/)
           KBabel (
           http://i18n.kde.org/tools/kbabel/)
           GTranslator (
           http://gtranslator.sourceforge.net/)
           Emacs po mode
           Vim po mode
           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. 
calcurse RSS feedAnother possibility to get warned when new releases come out is to follow the RSS feed at:
http://culot.org/calcurse/news_rss.xmlThis RSS feed is updated each time a new version of calcurse is available, describing newly added features.
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 :
C programming 
	calcurse
	calcurse for FreeBSD
	calcurse for NetBSD
	calcurse for Archlinux
	calcurse for Debian
	and Ubuntu
	calcurse for Archlinux
	calcurse for Slackware
	calcurse for Mac OsX
	and Darwin
	calcurse for ALT Linux
	calcurse 
	calendar view 
        calcurse and its manual
	calcurse and its manual
	vim for the displacement keys
		orpheus and abook for documentation
		pine and aptitude 
	        for the text user interface
		calcurse
        users who sent me their feedback.