rsalz@uunet.uu.net (Rich Salz) (11/10/88)
Submitted-by: Michael Morrell <hplabs!hpda!morrell>
Posting-number: Volume 16, Issue 59
Archive-name: month8.7/part06
# This is a shell archive. Remove anything before this line,
# then unpack it by saving it in a file and typing "sh file".
# This archive contains:
# chmonth.1 month.1 xmonthd.1 month.help.n
LANG=""; export LANG
echo x - chmonth.1
sed 's/^@//' >chmonth.1 <<'@EOF'
.TH CHMONTH 1 "LOCAL"
.SH NAME
chmonth \- change .month file to current version of month
.SH SYNOPSIS
.B chmonth
[
.I user
]
.br
.B chmonths
.SH DESCRIPTION
.IR Chmonth (1)
should be used to update an existing
.B .month
file whenever a newer version of
.IR month (1)
is released.
.PP
Specifying a user name on the command line will cause that user's .month file
to be changed instead of your own.
.PP
.I Chmonths
searches the file system and runs
.I chmonth
on all
.B .month
files found.
.\".SH CAVEATS/BUGS
.SH AUTHOR
James Hull
.SH FILES
@~/.month
.SH SEE ALSO
month(1).
@EOF
chmod 664 chmonth.1
echo x - month.1
sed 's/^@//' >month.1 <<'@EOF'
.TH MONTH 1 "Version 8.7" "LOCAL"
.SH NAME
month \- a visual monthly calendar and time/event browser
.SH SYNOPSIS
.B month
[
.B \-AaIiKkOoRr
] [
.BR \-tS | \-tD | \-tE
] [
.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/1760 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:
.RS 3
.IP 1) 3
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.
.RE
.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 date\fP and \fItoday's date\fP.
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:
.RS 3
.IP \- 3
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 \-
End Time.
This specifies what time of day the event is to end.
.IP \-
Description.
This is a one-line description of what the event is.
.IP \-
Warning Time.
This specifies 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.
.RE
.SS Commands
The following commands may be entered when in the days, months, or years areas:
.PP
.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.
This command can currently only be executed from the days, months,
or years areas.
.RE
.I Cursor motion
.RS
The
.BR h ", " l ", " k ", "
.RB "and " j
commands 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
The date the cursor is on is made to be the current date by \fIselecting\fP it.
\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
.BR + " and " -
commands 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.
.PP
The
.BR n " and " p
commands 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
.BR m ", " d ", and " y
commands 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 set a particular month or year as the current date,
move to the appropriate area and onto the desired month or year,
and select it (\fB<CR>\fP).
.PP
The
.BR n " and " p
commands 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 \fBM\fP command 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 \fB'\fP command is used to go to a previously set mark.
The user is prompted for the mark's identifying digit.
.PP
The \fB;\fP command 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 \fBT\fP command is used to go directly to (and select) today's date,
which is typically the date initially displayed upon startup.
.PP
The \fB/\fP command is used to go directly to (and select) 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.
If \fIy\fP is less than 100,
the year selected is from the range [current_year-50, current_year+49].
For example,
if the current year is 1985,
a date specified as
.B 1/1/6
would mean
.B "Jan 1, 2006"
not
.BR "Jan 1, 1906" ,
but
.B 1/1/40
would mean
.BR "Jan 1, 1940" .
If the year is omitted,
the current year is assumed.
.RE
.I Overviewing a month
.RS
The \fBA\fP command 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 \fBB\fP command will list all the events for the current day on
a fresh screen;
press any key to return to the calendar.
.PP
The \fBO\fP command will toggle a flag which, when set,
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 \fBS\fP command (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 displayed
and the following functions are available:
.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 \fBE\fP command works just like the \fBS\fP command except that it will
display, one at a time, every event and anti-event in
the current event database.
.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.
In addition,
the \fB/\fP command can be used to change the start or until date of
an event.
The other fields in this first line may be moved onto and selected.
\fBj\fP will move the cursor to the next line which gives the
start time, duration, end time, warning time, and owner of the event.
The \fBh\fP and \fBl\fP commands move between the fields on this line
(fields which are
underlined\l'|0\(ul'
can not be changed).
Hours and minutes may be changed either by scrolling
(with the
.BR n ", " p ", " + ", and"
.BR - " commands)"
or directly entered as numbers
(hours are entered in 24-hour format).
The AM/PM indicator changes as the hours scroll across 12:00 boundaries.
.PP
At any time,
only two of start time, duration, and end time may be changed.
The time which can not be changed is determined by the
.IR "time mode" .
The time mode is initially
.I "end time"
and is changed using the \fBt\fP command anywhere in the schedule area.
The initial time mode can also be set using
the \fBMONTH\fP environment variable
(described below).
.PP
\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
.RS
An example of a scheduled event is shown below:
.sp
.if n .in 0
.if n .po 0
.nf
\fB12/25/1987\fP priv anti monthly \fByearly\fP every 01st last SuMoTuWeThFrSa 1/22/1987
start time duration end time warning owner
12:00 am \fI23:45\fP 11:45 pm 0:15 \fImorrell\fP
event: Christmas!
.fi
.if n .po
.if n .in
.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).
.PP
The \fBa\fP command lists the aliases found in these two alias files.
.RE
.I Miscellaneous
.RS
The \fB!\fP command 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 \fBC\fP command clears the schedule area
(if the \fIOverview\fP flag is not set) and the message area.
.PP
The \fBK\fP command toggles the \fIKeep old events\fP flag.
.PP
The \fBL\fP command 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 \fBR\fP command toggles the \fIRead-only\fP flag.
.PP
The \fBU\fP command changes to a new user's event database
(if compiled with MULTIUSER=1).
.PP
The \fBV\fP command prints the current version of month.
.PP
The \fBW\fP command 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 \fB^L\fP or \fB^R\fP commands redraw the screen.
.RE
.SS Options
Each of the options described below may be given in any order but must be
separated by white space.
.PP
Specifying the
.B \-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 \-B
(Book) flag prints out the list of scheduled events for the current day.
The
.B \-B
flag may be optionally followed by a number to indicate how many days to list
(note: no space between the \fBB\fP and the number).
Only those days which have an event will be listed.
.PP
Specifying the
.B \-I
(Insert mode) flag turns on insert character mode.
This has no effect except when entering an event description.
.PP
Specifying the
.B \-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
.B \-R
(Read-only) flag causes a read-only copy of the event database to be accessed.
.PP
Specifying the
.B \-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 \fB\-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,
the initial current year is selected from [today's_year-50, today's_year+49].
When the year is omitted,
the today's 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 ENVIRONMENT
.I Month
uses the
.B MONTH
environment variable to control the inital values of some of its flags.
The value of this variable is simply a list of one or more letters from the set
.BR AIKOR .
The occurrence of one of these letters is equivalent to specifying that letter
as a command-line option.
The variable may also contain one of the following two letter sequences:
.B tS ", " tD ", and " tE .
This sets the initial time mode to start mode, duration mode, and end mode,
respectively.
.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.
.PP
Since BSD curses does not have as much flexibility in character attributes
(it does not support the attr* functions),
some of the distinctions these atrributes make are lost.
.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 AUTHOR
.I Month
was originally written by Tim Stoehn.
All subsequent modifications were made by James Hull and Michael Morrell.
.SH FILES
.nf
@~/.month
@~/.monthrc
/usr/local/lib/.monthrc
/usr/local/lib/month.help
.fi
.SH SEE ALSO
chmonth(1), stty(1), gettimeofday(2).
@EOF
chmod 664 month.1
echo x - xmonthd.1
sed 's/^@//' >xmonthd.1 <<'@EOF'
.TH XMONTHD 1 "LOCAL"
.SH NAME
xmonthd \- inform users of upcoming month events (X10)
.SH SYNOPSIS
.B xmonthd
[
.BI = geometry
] [
.IB host : display
]
.SH DESCRIPTION
.IR Xmonthd (1)
is a daemon typically run automatically at login which informs the
user of upcoming events posted using
.IR month (1).
.SS X Defaults
The following X Defaults affect the operation of
.IR xmonthd :
.PP
.PD 0
.TP 5
Delay
Flash delay interval (in hundredths of a second)
(Default = 5).
.TP
Flashes
Number of flashes when an event is displayed
(Default = 10).
.TP
Geometry
Geometry specification for event window
(Default = +0+0).
.TP
InternalBorder
Width of internal border of event window
(Default = 2).
.TP
Interval
Time (in minutes) between checks for new events
(Default = 15).
.TP
BorderWidth
Width of border of event window
(Default = 2).
.TP
BaseFont
Font used to display events
(Default = "vtsingle").
.TP
Foreground
Foreground color of event window
(Default = "Black").
.TP
Background
Background color of event window
(Default = "White").
.TP
Border
Border color of event window
(Default = "Black").
.TP
ReverseVideo
If \fBon\fP,
reverse the forground and background colors on monochrome displays.
.\".SH CAVEATS/BUGS
.SH AUTHOR
James Hull
.SH FILES
@~/.month
.SH SEE ALSO
month(1).
@EOF
chmod 664 xmonthd.1
echo x - month.help.n
cat >month.help.n <<'@EOF'
.\" $Header: month.help.n,v 8.7 88/09/04 12:22:52 morrell Exp $
.nf
.ce
\fBCommands and their Functions (Version 8.7)\fP
.sp
\fBMonths, Days, or Years Area\fP
? - display this list of commands
! - shell escape
; - go to previously displayed date
/ - direct entry of current date (e.g., 5/6/86)
' - go to a previously marked date
a - display alias files
A - toggle show all events flag
B - display schedule list for current day
C - clear schedule area and message line
E - scan every event
G - group post an event (see man page)
K - toggle keep old events flag
L - display picture of moon for 11:00 PM of current day
M - mark the currently displayed date
O - toggle overview flag
P - post an event (see man page)
Q - quit, store any event changes
R - toggle read-only flag
S - scan the events for current day
T - go to today's actual date
U - go to new user's event database
V - display version number
W - write out schedule (if changed), may delete old events
.sp
\fBDays Area Only\fP
<CR> - select day at cursor
\fInumber\fP - direct entry of day
+\fInumber\fP - increment day by \fInumber\fP
-\fInumber\fP - decrement day by \fInumber\fP
n and p - go to the next or previous date
h, l, k, j - move cursor left, right, up, down
m and y - move to the months or years areas
.sp
\fBMonths Area Only\fP
<CR> - select month at cursor
\fInumber\fP - direct entry of month
+\fInumber\fP - increment month by \fInumber\fP
-\fInumber\fP - decrement month by \fInumber\fP
n and p - go to the next or previous month (same day)
k and j - move cursor up and down
d and y - move to the days or years areas
.sp
\fBYears Area Only\fP
<CR> - select year at cursor
\fInumber\fP - direct entry of year
+\fInumber\fP - increment year by \fInumber\fP
-\fInumber\fP - decrement year by \fInumber\fP
n and p - go to the next or previous year (same month and day)
h and l - move cursor left and right
d and m - move to the days or months areas
.sp
\fBWhen Scanning Events\fP
n - go to next event
p - go to previous event
d - delete this event
e - edit this event
q - quit the scan
.sp
\fBWhen Posting/Editing Event\fP
^A - accept event
/ - direct entry of start or until date (e.g., 5/6/86)
<CR> - select field at cursor
\fInumber\fP - direct entry of month/day/year/nth
+\fInumber\fP - increment month/day/year/nth by \fInumber\fP
-\fInumber\fP - decrement month/day/year/nth by \fInumber\fP
h, l, k, j - move cursor left, right, up, down
t - change time mode
.sp
\fBWhen Entering Event Description\fP
^A - accept event
^B - move cursor back one character
^D - delete character at cursor
^F - move cursor forward one character
^I - enter/exit insert mode
^U - delete entire line
^W - delete previous word
.sp
\fBAnytime\fR
^L or ^R - redraw screen (including this page)
^C or ^\\ - quit, ignore any event changes
<ESC> - abort function
@EOF
chmod 444 month.help.n
exit 0
--
Please send comp.sources.unix-related mail to rsalz@uunet.uu.net.