
Calcurse documentation
    by F. Culot, 2004-2005

Contents
--------
1. Installation
    1.1. Requirements
    1.2. Install process

2. Calcurse Overview
    2.1. Creation history
    2.2. Features overview
    
3. User interface
    3.1. Non-interactive mode
    3.2. Interactive mode
    
4. Configuration
    
5. Links
    5.1. The program homepage
    5.2. Calcurse announce list
    5.3. culot.org
    5.4. Other programs I write

6. Thanks



1. Installation
---------------


1.1. Requirements
-----------------

  Calcurse is intended to be lightweight, fast and reliable.  
  It 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/
  
  Calcurse also needs a color terminal for now on to run properly 
  (a future release will eventually allow to use non-color terminals),
  so you need to have your TERM variable set to xterm-color. 


1.2. Install process
--------------------
	
  Once you meet the requirements, the install process is quite simple, and
  follows the standard three steps process :
  
  1) ./configure
  2) make
  3) make install

  Use the ./configure --help to obtain a list of possible options.



2. Introduction
---------------


2.1. 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 uses 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.


2.2. Features overview
----------------------

  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.



3. User interface
-----------------


3.2. Non-interactive mode
--------------------------

  Calcurse can be called with command-line arguments, in order to
  display the todo list and appointments for specified days. After
  having displayed the desired information, 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. 
  

3.2. Interactive mode
---------------------

  Calcurse interface contains three different panels which you can
  browse using the 'TAB' key. The first panel represents a calendar
  which allows to highligth a particular day, the second one contains
  the list of the 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.



4. Configuration
----------------

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



5. Links
--------

  This section contains links and references that may be of interest to you.


5.1. The program homepage
-------------------------

The Calcurse homepage can be found at http://culot.org/calcurse/


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


5.3. culot.org
--------------

  If you want to find out more about my recent activities, news, software
  developments and other things I'm involved in, visit my web site at
  
  http://culot.org

  It's currently available in French and English (only part of it).


5.4. Other programs I write
---------------------------

  To find out more about my software developments use the following URL:
  http://culot.org



6. Thanks
---------

 Its time now to thank other people without whom this program would not
 exist!  So here is a list of contributing persons I would like to thank :
	* Alex for its patches, help and advices with C programming 
	* Gwen for testing and general discussions about how to improve Calcurse
	* Kevin and Ryan for packaging Calcurse for Debian
	* Steffen for packaging Calcurse for Archlinux
	* Alexandre for packaging Calcurse for Mac OsX
	* people who write softwares I like and which inspired me, especially :
		- vim for the displacement keys
		- orpheus for documentation
		- pine for the text user interface
		- cal for the calendar view
