mohamed@hscfvax.harvard.edu (Mohamed_el_Lozy) (03/23/88)
What is the current status of the month and appt programs? As I recall, several patches to month were posted a long time ago, together with a month/appt interface. There seems to be a version of month in Volume 9 of comp.sources.unix. Is it the latest and greatest? If not, what is and where is it? Also, where can I get appt from? Many thanks.
morrell@hpsal2.HP.COM (Michael Morrell) (03/25/88)
We have worked significantly on month since it was first posted. Many bugs
have been fixed and many new features have been added. It does not however
contain a month/appt interface. The format of the .month file is different
but our program comes with a "chmonth" program to convert any old format
(including the original) to our latest format. There are a few bugs that
we'd like to take care of before posting, but it should be available soon
(we are first trying to contact the original author to get his approval).
Below is a slightly out-of-date man page which will give you an idea of some
of the new features.
Michael Morrell
Jim Hull
--------------
.TH MONTH 1 "Version 7.07" "LOCAL"
.SH NAME
month \- a visual monthly calendar and time/event browser
.SH SYNOPSIS
.B month
[
.B \-AaIiKkOoRr
] [
.I date
] [
.I user
]
.br
.B month
.BI \-B days
[
.B \-V
] [
.I date
] [
.I user
]
.br
.B month
.B \-V
.br
.B monthd
[
.BI \-i minutes
]
.SH DESCRIPTION
.SS Overview
In the first form,
.IR month (1)
displays a calendar of the current month of the current year,
with the current day highlighted.
It then allows the user to browse to any month/day/year desired
(between 1/1/1753 and 12/31/9999),
and to schedule and recall events for a day or for some
regular repeating series of days.
.PP
There are four flags which control various functions of \fImonth\fP.
The state of these flags is displayed above the calendar
(a \fBhighlighted\fP letter indicates the flag is set).
These flags may be set or reset from the command line, from commands,
or from the
.B MONTH
environment variable.
Their use is explained below.
.PP
If compiled with MULTIUSER=1,
.IR month (1)
can be used to post or examine events in another user's event database.
When accessing another user's event database,
the following restrictions apply:
.IP 1)
Private events are not accessible.
.IP 2)
Only those events posted by the month user may be edited or deleted.
.IP 3)
The Keep old events flag is permanently set.
.SS Screen Areas
There are five distinct areas of the screen:
the \fIdays\fP area where the days of the month are listed in calendar format,
the \fImonths\fP area where the months of the year are listed,
the \fIyears\fP area where a sequence of ten years are listed,
the \fIscan\fP area which is the first line of the screen and is used
for displaying messages,
and the \fIschedule\fP area,
which may be blank and occupies lines 18-24 on the terminal
(lines below 24 are not used).
.SS Dates
.I Month
keeps track of two dates at all times:
the \fIcurrent\fP date and \fItoday's\fP date.
Today's date is simply the date on which the program is being run,
while the current date is a date typically initialized to today's date
but can be changed to any other date by the user.
The current date is always \fBhighlighted\fP in the
days, months, and years areas.
.SS Events
Events are defined by the following properties:
.IP \-
Private.
This flag indicates whether the event is private and therefore
hidden from other \fImonth\fP users.
.IP \-
Anti.
This flag indicates whether the event is an anti-event which cancels
specific instances of another event.
.IP \-
Regularity.
This specifies how often the event occurs.
.IP \-
Start Time.
This specifies what time of day the event is to start.
.IP \-
Duration.
This specifies how long the event is to last.
.IP \-
Description.
This is a one-line description of what the event is.
.IP \-
Warning Time.
This sepcifies how much in advance of the starting time
the user should be informed of the event.
.IP \-
Owner.
This is the name of the person who posted the event.
.SS Commands
The following commands may be entered when in the days, months,
or years areas:
.sp
.I Quitting
.RS
The \fBQ\fP command is used to quit
.IR month (1).
This will update the current event database if any changes have been made.
The update will also delete all old events from the database.
The event database is in a file named ".month" in the user's login directory.
The user's interrupt and quit characters
(normally, control-C and control-\\)
can be used any time for an immediate abort and no event database update.
These characters can be set or displayed using
.IR stty (1).
.PP
Any time the program is terminated in any of these ways,
the user will be informed of whether the event database has been updated.
.RE
.I Help
.RS
The \fB?\fP command prints a list of all commands.
.RE
.I Cursor motion
.RS
The commands
.BR h ", " l ", " k ", "
.RB "and " j
are used to move the cursor left, right, up, and down,
respectively within a screen area.
These commands work in a wrap-around fashion and
do not change the current date.
Only
.BR h " and " l
are valid in the years area while only
.BR j " and " k
are valid in the months area.
.RE
.I Selection
.RS
\fB<CR>\fP and \fB<LF>\fP are used to select items/commands
at the cursor position.
.RE
.I Direct entry of numbers
.RS
The user may type the number of a desired month, day, or year
whenever the cursor is appropriately positioned.
This is true in all screen areas.
The user can also directly enter the hours and minutes in the schedule area.
\fB<ESC>\fP is used to abort the function.
.RE
.I Date Incrementing/Decrementing
.RS
The commands
.BR + " and " -
are used to increment or decrement the current month, day, or year.
When these commands are entered,
the user is prompted for the amount of the increment or decrement.
.sp
The commands
.BR n " and " p
are synonyms for
.BR +1 " and " -1 ,
respectively.
This makes it simple to go directly from the last day of one month to
the first day of the next or vice versa.
.RE
.I Time browsing
.RS
The commands
.BR m ", " d ", and " y
are used to move into
the months area, the days area, or the years area, respectively.
This is only when time browsing in these three areas.
To get to a particular month or year,
move to the appropriate area and onto the desired month or year,
and select it (\fB<CR>\fP).
Years may be scrolled a year at a time by using the scroll areas marked by
.BR << " and " >> .
Attempting to move past these areas will scroll by one year,
selecting them scrolls by ten years.
.PP
The commands
.BR n " and " p
can be used to go to the next or previous month, day, or year,
depending on which screen area the user is in.
.PP
The command \fBM\fP is used to mark a specific date.
The user is prompted for an identifier which is a single digit between
.BR 0 " and " 9 .
Once a mark has been set at a certain date,
the user may jump to that date from any other date with the \fB'\fP command,
described below.
.PP
The command \fB'\fP is used to go to a previously set mark.
The user is prompted for the mark's identifying digit.
.PP
The command \fB;\fP is used to go directly to (and select) the
previously selected date.
Use the same command again to return to the original date.
.PP
The command \fBT\fP is used to go directly to today's date,
which is typically the date initially displayed upon startup.
.PP
The command \fB/\fP is used to go directly to a date fully specified
by the user.
A prompt is given to which the user responds with a date in the form
.IB m / d /\c
.IR y ,
such as 5/6/86.
Years less than 100 are assumed to be in this century, hence,
5/6/86 is the same as 5/6/1986.
If the year is omitted,
the current year is assumed.
.RE
.I Overviewing a month
.RS
The command \fBA\fP will toggle a flag which, when set,
will mark all the days on the calendar that have
at least one event posted.
This feature is especially useful before overviewing a particular day,
described next.
.RE
.I Overviewing a day
.RS
The command \fBB\fP will list all the events for the current day on
a fresh screen;
press any key to return to the calendar.
.PP
The command \fBO\fP will fill the schedule area with a read-only view
of the current day according to the event database.
Four six-hour grids appear showing which hours of the
day have been pre-scheduled.
.PP
The command \fBS\fP (Scan today's events) will cause a sorted, sequential
list of events for the current day to be displayed in the schedule area.
The events for any given day may be scanned, deleted, or modified.
After displaying each one, the prompt \fB[n,p,d,e,q]\fP is put
up and will respond to these character commands:
.PP
.RS
.PD 0
.TP 4
.B n
go to next event
.TP
.B p
go to previous event
.TP
.B d
delete this event
.TP
.B e
edit this event as during a posting described below
.TP
.B q
quit the scan and return to calendar
.PD
.RE
.RE
.I Every event scan
.RS
The command \fBE\fP will display, one at a time,
every event and anti-event in the current event database.
The prompt \fB[n,p,d,e,q]\fP is displayed and will respond
to these character commands:
.PP
.RS
.PD 0
.TP 4
.B n
go to next event
.TP
.B p
go to previous event
.TP
.B d
delete this event
.TP
.B e
edit this event as during a posting described below
.TP
.B q
quit the scan and return to calendar
.PD
.RE
.RE
.I Posting an event
.RS
The \fBP\fP command is used to post an event or anti-event.
The cursor is placed into the schedule area with a host of
information displayed.
The cursor first appears on the first line of the schedule area.
This line gives the starting and ending dates for the event,
when it shall occur,
whether the event is private or not,
and whether the event is an \fIanti-event\fP.
.PP
Anti-events cancel events which are scheduled at the same time.
They can be used to generate irregularly scheduled events.
For example,
suppose a meeting was scheduled every Monday for the
next six weeks except one (e.g., because it's a holiday).
This could be represented by posting one event every Monday for the six weeks
and one anti-event for the Monday that is to be skipped.
.PP
The user may move into the starting or ending date and change the month,
day, and year by scrolling with
.BR n " and " p ,
or by directly typing it.
The other fields in this first line may be moved onto and selected.
\fBj\fP will move the cursor to the next line which contains the
time at which the event occurs.
The commands \fBh\fP and \fBl\fP move between the hours and minutes fields
which may be scrolled or directly entered
(hours are entered in 24-hour format).
The AM/PM indicator changes as the hours scroll across 12:00 boundaries.
\fBj\fP will move the cursor to the next line which gives the
duration of the event, and it is edited in the same fashion.
\fBj\fP will move the cursor to the next line which gives the
warning time of the event, and it is edited in the same fashion.
This line specifies how much in advance of when the event starts
will it be listed by the daemon.
\fBj\fP moves the cursor to the next line which is a
one-line description of the event,
to be typed whenever the cursor is placed here.
<CR> returns to the first line.
<^A> is used to accept the posting and put the event
into the current user's event database.
<ESC> is used to cancel the posting.
.RE
.I Event scheduling
.RS
When and how often will an event occur?
This information is contained in the first line of the schedule area.
The first date entered there is the starting date for the event,
that is, the event will not be recalled until that date.
This date is best entered by browsing to it,
placing the cursor in the days area on the desired day,
and then type \fBP\fP to post the event,
in which case the desired date automatically appears as the default,
but may be edited.
In the following examples,
only the fields that need to be selected are mentioned,
all others should be turned off (not highlighted).
.PP
Examples:
.RS
.nf
March 5, 1990 (once only)
3/5/1990
Every Tuesday and Wednesday
m/d/y every TueWed
The 7th of each month
m/7/y monthly
Each July 4th
7/4/y yearly
The 2nd and last sunday of each month
m/d/y monthly every 2nd last Sun
The 1st and last friday of each year
m/d/y yearly every 1st last Fri
Every other thursday till 12/31/86
m/d/y every 2nd Thu 12/31/1986
Note, this will include the 1st, 3rd, 5th, 7th, etc.
thursday, starting from the specified m/d/y
.fi
.RE
.sp 2
.RS
An example of a scheduled event is shown below:
.sp
.in 0
.po 0
.nf
\fB12/25/1987\fP priv anti monthly \fByearly\fP every 01st last SuMoTuWeThFrSa 1/22/1987
time: 12:00 am
duration: 23:45
warning: 0:15
event: Christmas!
owner: \fImorrell\fP
.fi
.po
.in
.sp
.RE
.RE
.I Group Posting
.RS
The \fBG\fP command allows the user to post an event to a group of people.
The user is prompted for a list of names and then creates an event.
When this event is accepted,
it will be posted to each of the users specified.
.PP
.I Month
supports a user alias feature.
Any name specified is first checked for in
.I .monthrc
in the user's login directory (if it exists)
and then in
.I /usr/local/lib/.monthrc
(if it exists).
.RE
.I Miscellaneous
.RS
The command \fB!\fP spawns a subshell.
The shell is specified by the SHELL environment variable
or the SHELLPROG compile option if SHELL is not defined.
.IR Month (1)
must be compiled with SHELL_ESCAPE=1 for this command to work.
.PP
The command \fBC\fP clears the schedule area.
.PP
The command \fBK\fP toggles the \fIKeep old events\fP flag.
.PP
The command \fBL\fP stands for lunar,
and causes a picture of what the moon looked like or will look like at
11:00PM on the current day.
.PP
The command \fBR\fP toggles the \fIRead-only\fP flag.
.PP
The command \fBU\fP changes to a new user's event database
(if compiled with MULTIUSER=1).
.PP
The command \fBV\fP prints the current version of month.
.PP
The command \fBW\fP writes out the event database,
if it has been changed.
Old events will not be written out unless the \fBK\fP flag is set.
.PP
The commands \fB^L\fP or \fB^R\fP redraw the screen.
.RE
.PP
The following commands may be entered when in the schedule area:
.sp
.I Scrolling numbers
.RS
Numbers may be scrolled forwards and backwards with the
.BR n " and " p " keys,"
respectively.
.RE
.PP
The \fB/\fP command can be used to change the start or until date of
an event.
.SS Options
Each of the options described below may be given in any order but must be
separated by white space.
.PP
Specifying the \-A flag will cause days which have events to be so noted
initially
(i.e., the \fIshow all events\fP flag is set).
.PP
Specifying the \-B (Book) flag prints out the list of scheduled events
for the current day.
The \-B flag may be optionally followed by a number to indicate
how many days to list
(note: no space between the B and the number).
Only those days which have an event will be listed.
.PP
Specifying the \-I (Insert mode) flag turns on insert character mode.
This has no effect except when entering an event description.
.PP
Specifying the \-K (Keep) flag causes old events to be kept
(by default, old events are not kept when the event database is changed).
.PP
Specifying the \-R (Read-only) flag causes a read-only copy of the event
database to be accessed.
.PP
Specifying the \-V (Version) flag prints the current version of month.
.PP
Invoking \fImonthd\fP causes a background daemon to be born that
will wake up at regular intervals during the current login session,
check the event database,
and print a message to the terminal with a bell if it finds an event
which starts within the next interval.
It will also do this check upon invocation,
and will continue to do so until killed or the user logs out.
.I Monthd
takes an optional \fI\-i\fP flag to indicate how often
(in minutes) the daemon should awake.
The default value is 15 minutes.
.PP
Specifying a date on the command line will cause that date to be used
as the initial current date instead of today's date.
Its format is \fBm/d\fP or \fBm/d/y\fP.
It also affects the starting date used by the \-B option.
If the year is less than 100,
this century is assumed.
When the year is omitted,
the current year is assumed.
.PP
Specifying a \fIuser\fP name on the command line will cause
that user's .month file to be used instead of the month user's.
.SH COMPILE OPTIONS
The following compile options must be specified when compiling
.IR month (1)
and affect the behavior of the program as shown:
.TS
center;
l lw(4i).
Option Effect
_
MULTIUSER T{
If 1, enables the \fBU\fP command and the \fIuser\fP argument.
T}
PAGERPROG T{
Specifies the default pager program to run the help file through.
This pager is used when the PAGER environment variable is not set.
T}
SHELL_ESCAPE If 1, enables the \fB!\fP command.
SHELLPROG T{
Specifies the default shell to be run when the \fB!\fP command is used.
This shell is used when the SHELL environment variable is not set.
T}
SYS5CURSES T{
If 1, enables keypad input so that the <NEXT>, <PREV>, <UP>, <DOWN>, <LEFT>,
and <RIGHT> keys may be used instead of
.BR n ", " p ,
.BR k ", " j ,
.BR h ", and " l ,
respectively.
T}
.TE
.SH CAVEATS/BUGS
The user interface is confused and may be revised in a later version.
.SH DIAGNOSTICS
.PD 0
.TP 15
.IR "cannot read .month version " x
The event database was created with an older version of month.
Use
.IR chmonth (1)
to update the database.
.TP
.I "Cannot get today's date"
The call to
.IR gettimeofday (2)
failed.
See the System Administrator.
.TP
.I ".month file locked"
Another user is accessing the event database in a read/write mode.
Either access the database in read-only mode or wait until the user
is finished.
.TP
.I "cannot open .month"
The event database is not readable.
Check the file permissions
(they should be 660, group month).
.TP
.I "Bad environment flag"
The MONTH environment variable may only contain the flags:
.BR A , I ,
.BR K ", and " R .
.TP
.I "Bad argument"
An invalid argument was specified -- check the SYNOPSIS.
.TP
.I "Cannot print schedule"
.TP
.I "area stack underflow"
Should never happen -- send bug report to author.
.TP
.I "area stack overflow"
Should never happen -- send bug report to author.
.TP
.I "cannot write .month"
.TP
.I "invalid user"
A user not found in /etc/passwd was specified in the \fBU\fP command.
.TP
.I "read-only mode"
.TP
.I "invalid start date"
The start date ior an event is not valid (e.g., Feb 30).
.TP
.I "invalid until date"
The until date ior an event is not valid (e.g., Feb 30).
.TP
.I "missing day of week"
When \fBevery\fP, \fInth\fP, or \fBlast\fP are specified,
one or more days of the week must be specified also.
.TP
.I "missing qualifier"
.TP
.I "need 'every'"
.TP
.I "monthly or yearly?"
.TP
.I "no events this day"
.TP
.I "no events at all"
.TP
.I "must keep old events"
.PD
.SH FILES
.nf
~/.month
~/.monthrc
/usr/local/lib/.monthrc
/usr/local/lib/month.help
.fi
.SH SEE ALSO
chmonth(1), stty(1), gettimeofday(2).