From a657b2e55a5ce0b9c68dff5d705b0745c84fc5d8 Mon Sep 17 00:00:00 2001 From: Dianne Skoll Date: Fri, 4 Mar 2022 15:40:39 -0500 Subject: [PATCH] Update man page. --- man/remind.1 | 174 +++++++++++++++++++++++++-------------------------- 1 file changed, 87 insertions(+), 87 deletions(-) diff --git a/man/remind.1 b/man/remind.1 index 1412770a..9010b01b 100644 --- a/man/remind.1 +++ b/man/remind.1 @@ -3139,6 +3139,93 @@ Returns \fBRemind\fR's notion of "today." This may be the actual system date, or a date supplied on the command line, or the date of the calendar entry currently being computed. .TP +.B trig(s_1 [,s_2, ...]) +For each string argument s_\fIn\fR, \fBtrig\fR evaluates s_\fIn\fR +as if it were a REM or IFTRIG trigger +specification. If the trigger would trigger today, then the trigger +date is returned and no further triggers are evaluated. If none +of the triggers would trigger today, then the zero date +1990-01-01 is returned. +.RS +\fBtrig\fR also has a zero-argument form; this returns the trigger +date of the \fImost recent\fR \fBtrig\fR function that returned a +non-zero trigger date. +.PP +\fBtrig\fR can be used to make more sophisticated versions of +\fBIFTRIG\fR. For example, if you have meetings every Monday in +June and July, and you want warnings 3 days in advance, you +could use: +.nf + REM [trig("Mon Jun +3", "Mon July +3")] +3 MSG Meeting %b +.fi +.PP +NOTE: We need to repeat the +3 delta outside of the \fBtrig\fR +function for advance warning to work properly. This is because +\fBtrig\fR returns a date constant (the trigger date) and the +REM command does not know the details of \fBtrig\fR's arguments. +.PP +Note that because \fBRemind\fR does not have short-circuit logical +operators, something like: +.PP +.nf + SET a trig("Mon +7") || trig("Fri +7") +.fi + +would set the value of trig() to the date of the following +Thursday. Even though trig("Mon +7") always returns true, +the logical-OR operator still evaluates trig("Fri +7") which +\fIalso\fR returns true and sets \fBtrig()\fR. +.PP +You can work around the lack of a short-circuit logical-OR as follows: +If \fBtrig\fR returns a true value, the specific value it returns +can be coerced to a DATE which is the trigger date. So the following code: +.PP +.nf + SET a trig("Mon +4") || trig("Fri +4") + IF a + REM [a] +4 MSG [wkday($T)] %b. + ENDIF +.fi +.PP +would operate as follows: +.PP +.nf + On Monday: Monday today. + On Tuesday: Friday in 3 days' time. + On Wednesday: Friday in 2 days' time. + On Thursday: Monday in 4 days' time. + On Friday: Monday in 3 days' time. + On Saturday: Monday in 2 days' time. + On Sunday: Monday tomorrow. +.fi +.PP +Compare with the following: +.PP +.nf + SET a trig("Mon +4") || trig("Fri +4") + IF a + REM [trig()] +4 MSG [wkday($T)] %b. + ENDIF +.fi +.PP +which yields: +.PP +.nf + On Monday: Friday in 4 days' time. + On Tuesday: Friday in 3 days' time. + On Wednesday: Friday in 2 days' time. + On Thursday: Friday tomorrow. + On Friday: Friday today. + On Saturday: Monday in 2 days' time. + On Sunday: Monday tomorrow. +.fi +.PP +That is because \fBtrig()\fR returns the trigger date of +the \fIlast\fR trig function that returns true, +whereas the value of \fBa\fR is the trigger date of the \fIfirst\fR +trig function that returns true. +.RE +.TP .B trigdate() Returns the calculated trigger date of the last \fBREM\fR or \fBIFTRIG\fR command. If used @@ -3334,93 +3421,6 @@ representing the day of the week of the date. If \fIarg\fR is an Returns a number from 0 to 6 representing the day-of-week of the specified \fIdate\fR. (0 represents Sunday, and 6 represents Saturday.) .TP -.B wouldtrig(s_1 [,s_2, ...]) -For each string argument s_\fIn\fR, \fBwouldtrig\fR evaluates s_\fIn\fR -as if it were a REM or IFTRIG trigger -specification. If the trigger would trigger today, then the trigger -date is returned and no further triggers are evaluated. If none -of the triggers would trigger today, then the zero date -'1990-01-01' is returned. -.RS -\fBwouldtrig\fR also has a zero-argument form; this returns the trigger -date of the \fImost recent\fR \fBwouldtrig\fR function that returned a -non-zero trigger date. -.PP -\fBwouldtrig\fR can be used to make more sophisticated versions of -\fBIFTRIG\fR. For example, if you have meetings every Monday in -June and July, and you want warnings 3 days in advance, you -could use: -.nf - REM [wouldtrig("Mon Jun +3", "Mon July +3")] +3 MSG Meeting %b -.fi -.PP -NOTE: We need to repeat the +3 delta outside of the \fBwouldtrig\fR -function for advance warning to work properly. This is because -\fBwouldtrig\fR returns a date constant (the trigger date) and the -REM command does not know the details of \fBwouldtrig\fR's arguments. -.PP -Note that because \fBRemind\fR does not have short-circuit logical -operators, something like: -.PP -.nf - SET a wouldtrig("Mon +7") || wouldtrig("Fri +7") -.fi - -would set the value of wouldtrig() to the date of the following -Thursday. Even though wouldtrig("Mon +7") always returns true, -the logical-OR operator still evaluates wouldtrig("Fri +7") which -\fIalso\fR returns true and sets \fBwouldtrig()\fR. -.PP -You can work around the lack of a short-circuit logical-OR as follows: -If \fBwouldtrig\fR returns a true value, the specific value it returns -can be coerced to a DATE which is the trigger date. So the following code: -.PP -.nf - SET a wouldtrig("Mon +4") || wouldtrig("Fri +4") - IF a - REM [a] +4 MSG [wkday($T)] %b. - ENDIF -.fi -.PP -would operate as follows: -.PP -.nf - On Monday: Monday today. - On Tuesday: Friday in 3 days' time. - On Wednesday: Friday in 2 days' time. - On Thursday: Monday in 4 days' time. - On Friday: Monday in 3 days' time. - On Saturday: Monday in 2 days' time. - On Sunday: Monday tomorrow. -.fi -.PP -Compare with the following: -.PP -.nf - SET a wouldtrig("Mon +4") || wouldtrig("Fri +4") - IF a - REM [wouldtrig()] +4 MSG [wkday($T)] %b. - ENDIF -.fi -.PP -which yields: -.PP -.nf - On Monday: Friday in 4 days' time. - On Tuesday: Friday in 3 days' time. - On Wednesday: Friday in 2 days' time. - On Thursday: Friday tomorrow. - On Friday: Friday today. - On Saturday: Monday in 2 days' time. - On Sunday: Monday tomorrow. -.fi -.PP -That is because \fBwouldtrig()\fR returns the trigger date of -the \fIlast\fR wouldtrig function that returns true, -whereas the value of \fBa\fR is the trigger date of the \fIfirst\fR -wouldtrig function that returns true. -.RE -.TP .B year(dq_date) Returns a \fBINT\fR that is the year component of \fIdate\fR.