1 files changed, 547 insertions, 0 deletions

diff --git a/Doc/Zsh/calsys.yo b/Doc/Zsh/calsys.yo
new file mode 100644
index 000000000..61226d39d
--- /dev/null
+++ b/Doc/Zsh/calsys.yo
@@ -0,0 +1,547 @@
+texinode(Calendar Function System)(TCP Function System)(Zsh Modules)(Top)
+chapter(Calendar Function System)
+cindex(calendar function system)
+cindex(zsh/datetime, function system based on)
+sect(Description)
+
+The shell is supplied with a series of functions to replace and enhance the
+traditional Unix tt(calendar) programme, which warns the user of imminent
+or future events, details of which are stored in a text file (typically
+tt(calendar) in the user's home directory).  The version provided here
+includes a mechanism for alerting the user when an event is due.
+
+In addition a function tt(age) is provided that can be used in a glob
+qualifier; it allows files to be selected based on their modification
+times.
+
+The format of the tt(calendar) file and the dates used there in and in
+the tt(age) function are described first, then the functions that can
+be called to examine and modify the tt(calendar) file.
+
+The functions here depend on the availability of the tt(zsh/datetime)
+module which is usually installed with the shell.  The library function
+tt(strptime+LPAR()RPAR()) must be available; it is present on most recent
+operating systems.
+
+startmenu()
+menu(Calendar File and Date Formats)
+menu(Calendar System User Functions)
+menu(Calendar Styles)
+menu(Calendar Utility Functions)
+menu(Calendar Bugs)
+endmenu()
+
+
+texinode(Calendar File and Date Formats)(Calendar System User Functions)()(Calendar Function System)
+sect(File and Date Formats)
+
+subsect(Calendar File Format)
+
+The calendar file is by default tt(~/calendar).  This can be configured
+by the tt(calendar-file) style, see
+ifzman(the section STYLES below)\
+ifnzman(noderef(Calendar Styles)).  The basic format consists
+of a series of separate lines, with no indentation, each including
+a date and time specification followed by a description of the event.
+
+Various enhancements to this format are supported, based on the syntax
+of Emacs calendar mode.  An indented line indicates a continuation line
+that continues the description of the event from the preceeding line
+(note the date may not be continued in this way).  An initial ampersand
+(tt(&)) is ignored for compatibility.
+
+The Emacs extension that a date with no description may refer to a number
+of succeeding events at different times is not supported.
+
+Unless the tt(done-file) style has been altered, any events which
+have been processed are appended to the file with the same name as the
+calendar file with the suffix tt(.done), hence tt(~/calendar.done) by
+default.
+
+An example is shown below.
+
+subsect(Date Format)
+
+The format of the date and time is designed to allow flexibility without
+admitting ambiguity.  Note that there is no localization support; month and
+day names must be in English (though only the first three letters are
+significant) and separator characters are fixed.  Furthermore, time zones
+are not handled; all times are assumed to be local.
+
+It is recommended that, rather than exploring the intricacies of the
+system, users find a date format that is natural to them and stick to it.
+This will avoid unexpected effects.  Various key facts should be noted.
+
+startitemize()
+itemiz(In particular, note the confusion between
+var(month)tt(/)var(day)tt(/)var(year) and
+var(day)tt(/)var(month)tt(/)var(year) when the month is numeric; these
+formats should be avoided if at all possible.  Many alternatives are
+available.)
+itemiz(The year must be given in full to avoid confusion, and only years
+from 1900 to 2099 inclusive are matched.)
+enditemize()
+
+The following give some obvious examples; users finding here
+a format they like and not subject to vagaries of style may skip
+the full description.  As dates and times are matched separately
+(even though the time may be embedded in the date), any date format
+may be mixed with any format for the time of day provide the
+separators are clear (whitespace, colons, commas).
+
+example(2007/04/03 13:13
+2007/04/03:13:13
+2007/04/03 1:13 pm
+3rd April 2007, 13:13
+April 3rd 2007 1:13 p.m.
+Apr 3, 2007 13:13
+Tue Apr 03 13:13:00 2007
+13:13 2007/apr/3)
+
+More detailed rules follow.
+
+Times are parsed and extracted before dates.  They must use colons
+to separate hours and minutes, though a dot is allowed before seconds
+if they are present.  This limits time formats to the following:
+
+startitemize()
+itemiz(var(HH)tt(:)var(MM)[tt(:)var(SS)[tt(.)var(FFFFF)]] [tt(am)|tt(pm)|tt(a.m.)|tt(p.m.)])
+itemiz(var(HH)tt(:)var(MM)tt(.)var(SS)[tt(.)var(FFFFF)] [tt(am)|tt(pm)|tt(a.m.)|tt(p.m.)])
+enditemize()
+
+Here, square brackets indicate optional elements, possibly with
+alternatives.  Fractions of a second are recognised but ignored.  For
+absolute times (the normal format require by the tt(calendar) file and the
+tt(age) function) a date is mandatory but a time of day is not; the time
+returned is at the start of the date.  One variation is allowed: if
+tt(a.m.) or tt(p.m.) or one of their variants is present, an hour without a
+minute is allowed, e.g. tt(3 p.m.).
+
+Time zones are not handled, though if one is matched following a time
+specification it will be removed to allow a surrounding date to be
+parsed.  This only happens if the format of the timezone is not too
+unusual.  The following are examples of forms that are understood:
+
+example(+0100
+GMT
+GMT-7
+CET+1CDT)
+
+Any part of the timezone that is not numeric must have exactly three
+capital letters in the name.
+
+Dates suffer from the ambiguity between var(DD)tt(/)var(MM)tt(/)var(YYYY)
+and var(MM)tt(/)var(DD)tt(/)var(YYYY).  It is recommended this form is
+avoided with purely numeric dates, but use of ordinals,
+eg. tt(3rd/04/2007), will resolve the ambiguity as the ordinal is always
+parsed as the day of the month.  Years must be four digits (and the first
+two must be tt(19) or tt(20)); tt(03/04/08) is not recognised.  Other
+numbers may have leading zeroes, but they are not required.  The following
+are handled:
+
+startitemize()
+itemiz(var(YYYY)tt(/)var(MM)tt(/)var(DD))
+itemiz(var(YYYY)tt(-)var(MM)tt(-)var(DD))
+itemiz(var(YYYY)tt(/)var(MNM)tt(/)var(DD))
+itemiz(var(YYYY)tt(-)var(MNM)tt(-)var(DD))
+itemiz(var(DD)[tt(th)|tt(st)|tt(rd)] var(MNM)[tt(,)] [ var(YYYY) ])
+itemiz(var(MNM) var(DD)[tt(th)|tt(st)|tt(rd)][tt(,)] [ var(YYYY) ])
+itemiz(var(DD)[tt(th)|tt(st)|tt(rd)]tt(/)var(MM)[tt(,)] var(YYYY))
+itemiz(var(DD)[tt(th)|tt(st)|tt(rd)]tt(/)var(MM)tt(/)var(YYYY))
+itemiz(var(MM)tt(/)var(DD)[tt(th)|tt(st)|tt(rd)][tt(,)] var(YYYY))
+itemiz(var(MM)tt(/)var(DD)[tt(th)|tt(st)|tt(rd)]tt(/)var(YYYY))
+enditemize()
+
+Here, var(MNM) is at least the first three letters of a month name,
+matched case-insensitively.  The remainder of the month name may appear but
+its contents are irrelevant, so janissary, febrile, martial, apricot,
+maybe, junta, etc. are happily handled.
+
+Where the year is shown as optional, the current year is assumed.  There
+are only two such cases, the form tt(Jun 20) or tt(14 September) (the only
+two commonly occurring forms, apart from a "the" in some forms of English,
+which isn't currently supported).  Such dates will of course become
+ambiguous in the future, so should ideally be avoided.
+
+Times may follow dates with a colon, e.g. tt(1965/07/12:09:45); this is in
+order to provide a format with no whitespace.  A comma and whitespace are
+allowed, e.g. tt(1965/07/12, 09:45).  Currently the order of these
+separators is not checked, so illogical formats such as tt(1965/07/12, :
+,09:45) will also be matched.  For simplicity such variations are not shown
+in the list above.  Otherwise, a time is only recognised as being
+associated with a date if there is only whitespace in between, or if the
+time was embedded in the date.
+
+Days of the week are not scanned, but will be ignored if they occur
+at the start of the date pattern only.
+
+For example, the standard date format:
+
+example(Fri Aug 18 17:00:48 BST 2006)
+
+is handled by matching var(HH)tt(:)var(MM)tt(:)var(SS) and removing it
+together with the matched (but unused) time zone.  This leaves the following:
+
+example(Fri Aug 18 2006)
+
+tt(Fri) is ignored and the rest is matched according to the standard rules.
+
+subsect(Relative Time Format)
+
+In certain places relative times are handled.  Here, a date is not allowed;
+instead a combination of various supported periods are allowed, together
+with an optional time.  The periods must be in order from most to
+least significant.
+
+The periods handled, with possible abbreviations are:
+
+startitem()
+item(Years)(
+tt(years), tt(yrs), tt(ys), tt(year), tt(yr), tt(y).
+Currently a year is 365.25 days, not a calendar year.
+)
+item(Months)(
+tt(months), tt(mons), tt(mnths), tt(mths), tt(month), tt(mon),
+tt(mnth), tt(mth).  Note that tt(m), tt(ms), tt(mn), tt(mns)
+are ambiguous and are em(not) handled.  Currently a month is a period
+of 30 days rather than a calendar month.
+)
+item(Weeks)(
+tt(weeks), tt(wks), tt(ws), tt(week), tt(wk), tt(w)
+)
+item(Days)(
+tt(days), tt(dys), tt(ds), tt(day), tt(dy), tt(d)
+)
+item(Minutes)(
+tt(minutes), tt(mins), tt(minute), tt(min), but em(not) tt(m),
+tt(ms), tt(mn) or tt(mns)
+)
+item(Seconds)(
+tt(seconds), tt(secs), tt(ss), tt(second), tt(sec), tt(s)
+)
+enditem()
+
+Spaces between the numbers are optional, but are required between items,
+although a comma may be used (with or without spaces).
+
+Here are some examples:
+
+example(30 years 3 months 4 days 3:42:41
+14 days 5 hours
+4d,10hr)
+
+subsect(Example)
+
+Here is an example calendar file.  It uses a consistent date format,
+as recommended above.  The second entry has a continuation line.
+
+example(Feb 1, 2006 14:30 Pointless bureaucratic meeting
+Mar 27, 2006 11:00 Mutual recrimination and finger pointing
+  Bring water pistol and waterproofs
+Apr 10, 2006 13:30 Even more pointless blame assignment exercise)
+
+
+texinode(Calendar System User Functions)(Calendar Styles)(Calendar File and Date Formats)(Calendar Function System)
+sect(User Functions)
+
+This section describes functions that are designed to be called
+directly by the user.  The first part describes those functions
+associated with the user's calendar; the second part describes
+the use in glob qualifiers.
+
+subsect(Calendar system functions)
+
+startitem()
+findex(calendar)
+xitem(tt(calendar) [ tt(-dDsv) ] [ tt(-C) var(calfile) ] [ -n var(num) ] [ tt(-S) var(showprog) ] [ [ var(start) ] var(end) ])(
+item(tt(calendar -r) [ tt(-dDrsv) ] [ tt(-C) var(calfile) ] [ -n var(num) ] [ tt(-S) var(showprog) ] [ var(start) ])(
+Show events in the calendar.
+
+With no arguments, show events from the start of today until the end of
+the next working day after today.  In other words, if today is Friday,
+Saturday, or Sunday, show up to the end of the following Monday, otherwise
+show today and tomorrow.
+
+If var(end) is given, show events from the start of today up to the time
+and date given, which is in the format described in the previous section.
+Note that if this is a date the time is assumed to be midnight at the
+start of the date, so that effectively this shows all events before
+the given date.
+
+var(end) may start with a tt(+), in which case the remainder of the
+specification is a relative time format as described in the previous
+section indicating the range of time from the start time that is to
+be included.
+
+If var(start) is also given, show events starting from that time and date.
+The word tt(now) can be used to indicate the current time.
+
+To implement an alert when events are due, include tt(calendar -s) in your
+tt(~/.zshrc) file.
+
+Options:
+
+startitem()
+item(tt(-C) var(calfile))(
+Explicitly specify a calendar file instead of the value of
+the tt(calendar-file) style or the the default tt(~/calendar).
+)
+item(tt(-d))(
+Move any events that have passed from the calendar file to the
+"done" file, as given by the tt(done-file) style or the default
+which is the calendar file with tt(.done) appended.  This option
+is implied by the tt(-s) option.
+)
+item(tt(-D))(
+Turns off the option tt(-d), even if the tt(-s) option is also present.
+)
+item(tt(-n) var(num), tt(-)var(num))(
+Show at least var(num) events, if present in the calendar file, regardless
+of the tt(start) and tt(end).
+)
+item(tt(-r))(
+Show all the remaining options in the calendar, ignoring the given tt(end)
+time.  The tt(start) time is respected; any argument given is treated
+as a tt(start) time.
+)
+item(tt(-s))(
+Use the shell's tt(sched) command to schedule a timed event that
+will warn the user when an event is due.  Note that the tt(sched) command
+only runs if the shell is at an interactive prompt; a foreground taks
+blocks the scheduled task from running until it is finished.
+
+The timed event usually runs the programme tt(calendar_show) to show
+the event, as described in
+ifzman(the section UTILITY FUNCTIONS below)\
+ifnzman(noderef(Calendar Utility Functions)).
+
+By default, a warning of the event is shown five minutes before it is due.
+The warning period can be configured by the style tt(warn-time) or
+for a single calendar entry by including tt(WARN) var(reltime) in the first
+line of the entry, where var(reltime) is one of the usual relative time
+formats.
+
+It is safe to run tt(calendar -s) to reschedule an existing event
+(if the calendar file has changed, for example), and also to have it
+running in multiples instances of the shell since the calendar file
+is locked when in use.
+
+By default, expired events are moved to the "done" file; see the tt(-d)
+option.  Use tt(-D) to prevent this.
+)
+item(tt(-S) var(showprog))(
+Explicitly specify a programme to be used for showing events instead
+of the value of the tt(show-prog) style or the default tt(calendar_show).
+)
+item(tt(-v))(
+Verbose:  show more information about stages of processing.
+)
+enditem()
+)
+findex(calendar_add)
+item(tt(calendar_add) var(event ...))(
+Adds a single event to the calendar in the appropriate location.
+Using this function ensures that the calendar file is sorted in date
+and time order.  It also makes special arrangments for locking
+the file will it is altered.  The old calendar is left in a file
+with the suffix tt(.old).
+)
+findex(calendar_sort)
+item(tt(calendar_sort))(
+Sorts the calendar file into date and time order.    The old calendar is
+left in a file with the suffix tt(.old).
+)
+enditem()
+
+subsect(Glob qualifiers)
+findex(age)
+
+The function tt(age) can be autoloaded and use separately from
+the calendar system, although it uses the function tt(calendar_scandate)
+for date formatting.  It requires the tt(zsh/stat) builtin, which
+makes available the builtin tt(stat).  This may conflict with an
+external programme of the same name; if it does, the builtin may be
+disabled for normal operation by including the following code in
+an initialization file:
+
+example(zmodload -i zsh/stat
+disable stat)
+
+tt(age) selects files having a given modification time for use
+as a glob qualifer.  The format of the date is the same as that
+understood by the calendar system, described in
+ifzman(the section FILE AND DATE FORMATS above)\
+ifnzman(noderef(Calendar File and Date Formats)).
+
+The function can take one or two arguments, which can be supplied either
+directly as command or arguments, or separately as shell parameters.
+
+example(print *+LPAR()e:age 2006/10/04 2006/10/09:+RPAR())
+
+The example above matches all files modified between the start of those
+dates.
+
+example(print *+LPAR()e:age 2006/10/04+RPAR())
+
+The example above matches all files modified on that date.  If the second
+argument is omitted it is taken to be exactly 24 hours after the first
+argument (even if the first argument contains a time).
+
+example(print *+LPAR()e-age 2006/10/04:10:15 2006/10/04:10:45-RPAR())
+
+The example above supplies times.  Note that whitespace within the time and
+date specification must be quoted to ensure tt(age) receives the correct
+arguments, hence the use of the additional colon to separate the date and
+time.
+
+example(AGEREF1=2006/10/04:10:15
+AGEREF2=2006/10/04:10:45
+print *+LPAR()PLUS()age+RPAR())
+
+This shows the same example before using another form of argument
+passing.  The dates and times in the parameters tt(AGEREF1) and tt(AGEREF2)
+stay in effect until unset, but will be overridden if any argument is
+passed as an explicit argument to age.  Any explicit argument
+causes both parameters to be ignored.
+
+
+texinode(Calendar Styles)(Calendar Utility Functions)(Calendar System User Functions)(Calendar Function System)
+sect(Styles)
+
+The zsh style mechanism using the tt(zstyle) command is describe in
+ifzman(zmanref(zshmodules))\
+ifnzman(noderef(The zsh/zutil Module)).  This is the same mechanism
+used in the completion system.
+
+The styles below are all examined in the context
+tt(:datetime:)var(function)tt(:), for example tt(:datetime:calendar:).
+
+startitem()
+kindex(calendar-file)
+item(tt(calendar-file))(
+The location of the main calendar.  The default is tt(~/calendar).
+)
+kindex(done-file)
+item(tt(done-file))(
+The location of the file to which events which have passed are appended.
+The default is the calendar file location with the suffix tt(.done).
+The style may be set to an empty string in which case a "done" file
+will not be maintained.
+)
+kindex(show-prog)
+item(tt(show-prog))(
+The programme run by tt(calendar) for showing events.  It will
+be passed the start time and stop time of the events requested in seconds
+since the epoch followed by the event text.  Note that tt(calendar -s) uses
+a start time and stop time equal to one another to indicate alerts
+for specific events.
+
+The default is the function tt(calendar_show).
+)
+kindex(warn-time)
+item(tt(warn-time))(
+The time before an event at which a warning will be displayed, if the
+first line of the event does not include the text tt(EVENT) var(reltime).
+The default is 5 minutes.
+)
+enditem()
+
+
+texinode(Calendar Utility Functions)(Calendar Bugs)(Calendar Styles)(Calendar Function System)
+sect(Utility functions)
+
+startitem()
+findex(calendar_lockfiles)
+item(tt(calendar_lockfiles))(
+Attempt to lock the files given in the argument.  To prevent
+problems with network file locking this is done in an ad hoc fashion
+by attempting to create a symbolic link to the file with the name
+var(file)tt(.lockfile).  Otherwise, however, the function is not
+specific to the calendar system.  Three attempts are made to lock
+the file before giving up.
+
+The files locked are appended to the array tt(lockfiles), which should
+be local to the caller.
+
+If all files were successully, status zero is returned, else status one.
+)
+findex(calendar_read)
+item(tt(calendar_read))(
+This is a backend used by various other functions to parse the
+calendar file, which is passed as the only argument.  The array
+tt(calendar_entries) is set to the list of events in the file; no
+pruning is done except that ampersands are removed from the start of
+the line.  Each entry may contain multiple lines.
+)
+findex(calendar_scandate)
+item(tt(calendar_scandate))(
+This is a generic function to parse dates and times that may be
+used separately from the calendar system.  The argument is a date
+or time specification as described in
+ifzman(the section FILE AND DATE FORMATS above)\
+ifnzman(noderef(Calendar File and Date Formats).  The parameter tt(REPLY)
+is set to the number of seconds since the epoch corresponding to that date
+or time.  By default, the date and time may occur anywhere within the given
+argument.
+
+Returns status zero if the date and time were successfully parsed,
+else one.
+
+Options:
+startitem()
+item(tt(-a))(
+The date and time are anchored to the start of the argument; they
+will not be matched if there is preceeding text.
+)
+item(tt(-A))(
+The date and time are anchored to both the start and end of the argument;
+they will not be matched if the is any other text in the argument.
+)
+item(tt(-d))(
+Enable additional debugging output.
+)
+item(tt(-r))(
+The arguments passed is to be parsed as a relative time.
+)
+item(tt(-s))(
+In addition to setting tt(REPLY), set tt(REPLY2) to the remainder of
+the argument after the date and time have been stripped.  This is
+empty if the option tt(-A) was given.
+)
+enditem()
+)
+findex(calendar_show)
+item(tt(calendar_show))(
+The function used by default to display events.  It accepts a start time
+and end time for events, both in epoch seconds, and an event description.
+
+The event is always printed to standard output.  If the command line editor
+is active (which will usually be the case) the command line will be
+redisplayed after the output.
+
+If the parameter tt(DISPLAY) is set and the start and end times are
+the same (indicating a scheduled event), the function uses the
+command tt(xmessage) to display a window with the event details.
+)
+enditem()
+
+texinode(Calendar Bugs)(Calendar Utility Functions)()(Calendar Function System)
+sect(Bugs)
+
+There is no tt(calendar_delete) function.
+
+There is no localization support for dates and times, nor any support
+for the use of time zones.
+
+Relative periods of months and years do not take into account the variable
+number of days.
+
+Recurrent events are not yet supported.
+
+The tt(calendar_show) function is currently hardwired to use tt(xmessage)
+for displaying alerts on X Window System displays.  This should be
+configurable and ideally integrate better with the desktop.
+
+tt(calendar_lockfiles) hangs the shell while waiting for a lock on a file.
+If called from a scheduled task, it should instead reschedule the event
+that caused it.