=========================================================================== jcal.doc -- USER DOCUMENTATION FOR "jcal" program. Copyright (c) 1999 by Jeffrey S. Rosenthal (jeff@math.toronto.edu). Available from http://probability.ca/jeff/comp/ jcal, jcal.c, and jcal.doc are licensed for general copying, distribution and modification according to the GNU General Public License (http://www.gnu.org/copyleft/gpl.html). NAME jcal - a plain-text calendar program SYNOPSIS jcal is a simple plain-text program for maintaining an "agenda" or calendar of appointments and events. It is much less fancy/pretty/sophisticated than similar programs such as ical(1). However, it has the advantage that it runs as plain text (using the curses(3X) screen-handling package), so it can be used e.g. over a modem or telnet session when it may be difficult or impossible to run xwindows. In addition, jcal has several other features considered desirable by its author: * each day's agenda is a separate plain-text file, with no pre-defined format, which may be edited using the user's preferred editor, and may be acted upon by any unix utilities such as grep(1), sed(1), awk(1), etc. * you can see a bit of each day's agenda on an entire three-week display, even before selecting that day. * the months run into each other naturally, instead of each having a separate "page". DESCRIPTION jcal begins by creating a directory ~/.jcal (if it does not already exist). [NOTE: It is possible to change the choice of directory, and therefore maintain more than one calendar at once; see ENVIRONMENT VARIABLES below.] It then displays three weeks worth of calendar days, beginning with the current week. A reverse-video mark of the form ***yyyy*** (e.g. ***1999***) shows the currently selected day. The user can move from one day to the next using the vim(1) style movement keys h,j,k,l for left/down/up/right movement. They can also move off of the three-week display to visit previous or subsequent weeks. They may optionally type a base-10 number before the movement key to repeat it a number of times. In addition, ctrl-j and ctrl-k move down/up one space by moving the calendar only (not moving the selected-day screen position). Also 'J' (or ctrl-d or ctrl-f) executes a page-down (i.e. ctrl-j three times), while 'K' (or ctrl-u or ctrl-b) executes a page-up (i.e. ctrl-k three times). The keys 'm' and 'M' move forward/backward one month, while 'y' and 'Y' move forward/backward one year. The user can edit the data for the currently-selected day by pressing 'e'. This command invokes an editor ($VISUAL if defined, otherwise $EDITOR if defined, otherwise "vi") to edit a file of the form ~/.jcal/yyyy-mm-dd (e.g. ~/.jcal/1999-01-14). This file can be edited in any way desired. Once finished, the first ten characters of each of the first four lines (not counting "comment" lines with '#' or '%' in the first column) are displayed on the three-week display. The full file can be viewed by re-editing it at a later time. The user can at any time press 't' to return to the starting "today" position, or 'q' to quit. (Note that "ZZ" also quits, for compatibility with vim(1).) The user can also press ctrl-x to delete all data from the currently selected day. There are also some special "copying" commands, 'D' and 'W'. These commands move forward one day or week, respectively, and append all the data from the old day to the new day. In addition, the user can type 'A' to edit a special "auxiliary" file, and can then type 'V' to append this file to the currently-selected day. Alternatively, they can type 'C' to copy the currently-selected day's data to the auxiliary file. Finally, the user can type 'p' to print a six-week time interval (the three weeks showing plus the three subsequent weeks) to the file ~/.jcal/toprint, and then optionally print it using a user-specified plain-text-printing command (if left blank the print command will be $PRINTCOMMAND if defined, otherwise "print"). Thus, to print an additional six weeks a user could type 'J' twice and then 'p' again. Note that, for printing, the command ~/.jcal/toprint is simply passed to sh. Hence, other commands, such as "cat" or "more" for viewing, or "vi" or "emacs" for editing, or "sz" or "kermit -s" for sending over a modem, or even "mail user <" for sending by e-mail, could be entered instead of "print" to act on the ~/.jcal/toprint file in other ways. Alternatively, the printing can be aborted (by typing ctrl-a), and then the file ~/.jcal/toprint can later be edited, ftp'ed, etc. as desired. SUMMARY OF COMMANDS h,j,k,l - move selected day one space left/down/up/right (Arrow keys may also work, see BUGS below.) ctrl-j, ctrl-k - move down/up without changing screen position J, ctrl-d, ctrl-f - page-down (i.e. forward three weeks) K, ctrl-u, ctrl-b - page-up (i.e. back three weeks) m,M - move forward/backward one month y,Y - move forward/backward one year . - repeat last command - number of repetitions of following command e - edit selected day's data D, W - move ahead one day / week, and copy (i.e. append) all data from previous day to new day A - edit special "auxiliary" file V - copy (i.e. append) "auxiliary" file to selected day's data C - copy (i.e. overwrite) selected day's data to "auxiliary" file ctrl-x - delete all data from selected day t - return to original "today" position p - save six weeks (the three showing plus three subsequent) to ~/.jcal/toprint, and then, optionally, print ctrl-l - refresh screen q or ZZ - quit ? - help (displays this jcal.doc file) ENVIRONMENT VARIABLES jcal accepts a number of environment variables to customise the working environment, which can be set from csh (using the "setenv" command, e.g. "setenv VISUAL joe") or from sh (by e.g. "VISUAL=joe; export VISUAL"): JCALDIR - directory to read/write data from (default is "~/.jcal", i.e. "$HOME/.jcal", and requires that $HOME be set properly) VISUAL or EDITOR - editor to use to edit data (default is "vi") PRINTCOMMAND - command to use for printing if user does not specify a command (default is "print") JCALDOCPATH - full path of location of jcal documentation file (default is "/usr/local/doc/jcal.doc") JCALVERTCHAR - if non-null, first character is used for vertical separation in displays (otherwise '$' is used) JCALPAGER - pager to use for viewing documentation (default is "more") JCALNORESIZE - if non-null, jcal does not run "resize" upon startup (by default it does; see BUGS below) JCALNOWAIT - if non-null, jcal does not wait for user to press a key after viewing documentation (by default it does) JCALNOCENTER - if non-null, jcal does not center short data lines within the day area (by default it does) [Note: aside from JCALNOWAIT and JCALNOCENTER, these variables are read only at start-up.] In addition, jcal uses the curses(3X) package, so environment variables affecting the curses environment will also affect the jcal environment. RETURN VALUE A value of 0 is returned upon successful exit; a value of 1 is returned (hopefully!) if the program exits through an error. NOTES Since the calendar data is stored as separate plain-text files with names of the form $HOME/.jcal/yyyy-mm-dd, it is possible to write other scripts which access this information in various ways. For example, here is a simple shell script which could be run from a user's .login; it prints out the current day's schedule if there is one, otherwise does nothing: #!/bin/sh # shell-script "showtoday": if test -s `echo -n "$HOME/.jcal/"; date +%Y-%m-%d` then echo '' echo -n "-----------" echo -n `date +%Y-%m-%d` echo "-----------" cat `echo -n "$HOME/.jcal/"; date +%Y-%m-%d` echo "--------------------------------" echo '' fi To show tomorrow's schedule instead, simply replace "date" by "date --date '1 day'" throughout. See "man date" for many similar options. Similarly, to look for, say, all occurrances of the word "movie" in 1999, one could use e.g. "grep movie ~/.jcal/1999*". Note also that the format yyyy-mm-dd is the International Standard notation; see e.g. http://www.cl.cam.ac.uk/~mgk25/iso-time.html BUGS While the program does correctly compute leap-years according to the formula "divisible by 4 and (divisible by 400 or not divisible by 100)", it does not account for historical oddities like the Gregorian Reformation. Furthermore it generally assumes a four-digit year; thus, it may not format perfectly for calendar years before A.D. 1000 or after A.D. 10,000. The program only makes use of 24 * 80 of the window regardless of actual window size. Furthermore, it will not fit properly on a window smaller than 24 * 80. Since curses on linux occasionally has a problem with setting the initial LINES (window height) variable, jcal sets the LINES and COLUMNS environment variables using (for now!) the data from the resize(1) shell command (unless those environment variables were already set). This takes about a quarter of a second at start-up; there must be a more efficient way. The arrow-keys can be used for movement, as an alternative to using h,j,k,l, but this feature isn't implemented properly (yet) and may not work on all terminal types. If a pager like "more" is SUSPENDED (with ^Z) when viewing jcal.doc, and then returned to (with fg), it seems to leave the terminal in an unstable state. Thus, to prevent problems, ^Z is temporarily DISABLED while viewing jcal.doc. If the user presses a key that does not correspond to a jcal command, then nothing happens. Arguably, the terminal should beep at that point. FILES jcal.c (source code) /usr/local/bin/jcal (binary code) /usr/local/doc/jcal.doc (this document) SEE ALSO ical(1), cal(1), date(1) AUTHOR Jeffrey S. Rosenthal jeff@math.toronto.edu http://probability.ca/jeff/ Comments welcome. ===========================================================================