diff options
Diffstat (limited to 'Doc/Zsh')
-rw-r--r-- | Doc/Zsh/.distfiles | 2 | ||||
-rw-r--r-- | Doc/Zsh/calsys.yo | 547 | ||||
-rw-r--r-- | Doc/Zsh/compsys.yo | 10 | ||||
-rw-r--r-- | Doc/Zsh/intro.yo | 1 | ||||
-rw-r--r-- | Doc/Zsh/manual.yo | 1 | ||||
-rw-r--r-- | Doc/Zsh/modules.yo | 2 | ||||
-rw-r--r-- | Doc/Zsh/tcpsys.yo | 2 |
7 files changed, 559 insertions, 6 deletions
diff --git a/Doc/Zsh/.distfiles b/Doc/Zsh/.distfiles index 5961f6201..2dd39b20b 100644 --- a/Doc/Zsh/.distfiles +++ b/Doc/Zsh/.distfiles @@ -1,6 +1,6 @@ DISTFILES_SRC=' .cvsignore .distfiles - arith.yo builtins.yo compat.yo compctl.yo compsys.yo compwid.yo + arith.yo builtins.yo calsys.yo compat.yo compctl.yo compsys.yo compwid.yo cond.yo exec.yo expn.yo filelist.yo files.yo func.yo grammar.yo index.yo intro.yo invoke.yo jobs.yo manual.yo metafaq.yo mod_cap.yo mod_clone.yo mod_compctl.yo mod_complete.yo mod_complist.yo 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. diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index de8f18094..d8e43ea77 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -1361,10 +1361,14 @@ specified will always be completed. kindex(file-list, completion style) item(tt(file-list))( This style controls whether files completed using the standard builtin -mechanism are to be listed with a long list similar to tt(ls -l) -(although note that this feature actually uses the shell module +mechanism are to be listed with a long list similar to tt(ls -l). +Note that this feature uses the shell module tt(zsh/stat) for file information; this loads the builtin tt(stat) -which will replace any external tt(stat) executable). +which will replace any external tt(stat) executable. To avoid +this the following code can be included in an initialization file: + +example(zmodload -i zsh/stat +disable stat) The style may either be set to a true value (or `tt(all)'), or one of the values `tt(insert)' or `tt(list)', indicating that files diff --git a/Doc/Zsh/intro.yo b/Doc/Zsh/intro.yo index c56dcaedd..510a7bda5 100644 --- a/Doc/Zsh/intro.yo +++ b/Doc/Zsh/intro.yo @@ -26,6 +26,7 @@ list(em(zshcompwid) Zsh completion widgets) list(em(zshcompsys) Zsh completion system) list(em(zshcompctl) Zsh completion control) list(em(zshmodules) Zsh loadable modules) +list(em(zshcalsys) Zsh built-in calendar functions) list(em(zshtcpsys) Zsh built-in TCP functions) list(em(zshzftpsys) Zsh built-in FTP client) list(em(zshcontrib) Additional zsh functions and utilities) diff --git a/Doc/Zsh/manual.yo b/Doc/Zsh/manual.yo index 4bf9f6bcd..ff6ecae41 100644 --- a/Doc/Zsh/manual.yo +++ b/Doc/Zsh/manual.yo @@ -34,6 +34,7 @@ menu(Completion Widgets) menu(Completion System) menu(Completion Using compctl) menu(Zsh Modules) +menu(Calendar Function System) menu(TCP Function System) menu(Zftp Function System) menu(User Contributions) diff --git a/Doc/Zsh/modules.yo b/Doc/Zsh/modules.yo index cbec478e3..3f9986096 100644 --- a/Doc/Zsh/modules.yo +++ b/Doc/Zsh/modules.yo @@ -1,4 +1,4 @@ -texinode(Zsh Modules)(TCP Function System)(Completion Using compctl)(Top) +texinode(Zsh Modules)(Calendar Function System)(Completion Using compctl)(Top) chapter(Zsh Modules) cindex(modules) sect(Description) diff --git a/Doc/Zsh/tcpsys.yo b/Doc/Zsh/tcpsys.yo index f1586b602..c93736a37 100644 --- a/Doc/Zsh/tcpsys.yo +++ b/Doc/Zsh/tcpsys.yo @@ -1,4 +1,4 @@ -texinode(TCP Function System)(Zftp Function System)(Zsh Modules)(Top) +texinode(TCP Function System)(Zftp Function System)(Calendar Function System)(Top) chapter(TCP Function System) cindex(TCP function system) cindex(ztcp, function system based on) |