remind/man/remind.1.in

.TH REMIND 1 "@RELEASE_DATE@" "Remind" "VERSION @VERSION@"
.SH NAME
remind \- a sophisticated reminder service
.SH SYNOPSIS
.B remind [\fIoptions\fR] \fIfilename\fR [\fIdate\fR] [\fI*rep\fR] [\fItime\fR]
.SH DESCRIPTION
\fBRemind\fR reads the supplied \fIfilename\fR and executes the commands
found in it.  The commands are used to issue reminders and alarms.  Each
reminder or alarm can consist of a message sent to standard output, or
a program to be executed.
.PP
If \fIfilename\fR is specified as a single dash '-', then \fBRemind\fR
takes its input from standard input.  In this case, if \fBRemind\fR
has been compiled against the GNU Readline library, it will use
Readline to give you an interactive line-editing interface.
.PP
If \fIfilename\fR happens to be a directory rather than a plain file,
then \fBRemind\fR reads all of the files (but not any subdirectories!)
in that directory that match the pattern "*.rem".  The files are read
in sorted order; the sort order may depend on your locale, but should
match the sort order used by the shell to expand "*.rem".

.PP
\fBRemind\fR reads its files starting from the beginning to the end, or
until it encounters a line whose sole content is "__EOF__" (without the quotes.)
Anything after the __EOF__ marker is completely ignored.

.SH MODES OF OPERATION
\fBRemind\fR has four major modes of operation:
.TP
.B Agenda Mode
Agenda mode is the default mode.  In this mode, \fBRemind\fR prints
today's reminders on standard output and exits.  It may fork a background
process to pop up queued reminders for later in the day.
.TP
.B Calendar Mode
In this mode, \fBRemind\fR generates a calendar either by drawing it
in the terminal or by sending data in computer-readable format to a back-end
program that actually draws the calendar.
.TP
.B Daemon Mode
This is a special mode of operation in which \fBRemind\fR is invoked
by a front-end and runs as a daemon, accepting requests from
the front-end and sending messages back to the front-end.
\fBTkRemind\fR uses \fBRemind\fR in daemon mode.
.TP
.B Purge Mode
In this mode, \fBRemind\fR produces no output, but creates new versions of
its input files with all expired reminders commented out.

.SH OPTIONS
\fBRemind\fR has a slew of options.  If you're new to the program,
ignore them for now and skip to the section "REMINDER FILES".
.TP
.B \-n
The \fB\-n\fR option causes \fBRemind\fR to print the \fBnext\fR occurrence
of each reminder in a simple calendar format.  You can sort this by
date by piping the output through \fBsort(1)\fR.  Note that the \fB\-n\fR
option causes any \fB\-g\fR option to be \fIignored\fR and also implicitly
enables the \fB\-o\fR option.
.TP
.B \-j\fR[\fIn\fR]
Runs \fBRemind\fR in "purge" mode to get rid of expired reminders.
See the section PURGE MODE for details.
.TP
.B \-r
The \fB\-r\fR option disables \fBRUN\fR directives and the \fBshell()\fR
function.
.TP
.B \-c\fI[flags]\fIn\fR
The \fB\-c\fR option causes \fBRemind\fR to produce a calendar that is
sent to standard output.  If you supply a number \fIn\fR, then a
calendar will be generated for \fIn\fR months, starting with the
current month.  By default, a calendar for only the current month is
produced.  This option implicitly enables the \fB\-o\fR option.
.RS
.PP
You can precede \fIn\fR (if any) with a set of flags.  The flags
are as follows:
.TP
.B '+'
causes a calendar for \fIn\fR
weeks to be produced.
.TP
.B 'a'
causes \fBRemind\fR to display reminders on the calendar on the
day they actually occur \fIas well as\fR on any preceding days
specified by the reminder's \fIdelta\fR.  This \fIalso\fR causes
\fBRemind\fR to include text outside %"...%" sequences that would
otherwise be removed (though the actual %" markers themselves are removed.) \"" Add comment to avoid Emacs highlighting problems
.TP
.B 'l'
causes \fBRemind\fR to use VT100 line-drawing characters to draw
the calendar.  The characters are hard-coded and will only work
on terminals that emulate the VT00 line-drawing character set.
.TP
.B 'u'
is similar to 'l', but causes \fBRemind\fR to use UNICODE line-drawing
characters to draw the calendar.  The characters are hard-coded and will
only work on terminals that are set to UTF-8 character encoding.  This
flag also enables the use of the UNICODE "left-to-right" mark that
can fix up formatting problems with right-to-left languages in the calendar
display.
.TP
.B 'z'
has the effect of setting the system variable \fB$TerminalHyperlinks\fR
to 1.  See the documentation of this variable in the section "SYSTEM VARIABLES"
.TP
.B 'c'
causes \fBRemind\fR to use VT100 escape sequences to approximate
SPECIAL COLOR reminders.  Note that this flag is kept for
backwards-compatibility; you should use the \fB\-@\fI[n][,m][,b]\fR
command-line option instead.
.PP
In a UTF-8 locale, \fBRemind\fR will use "left-to-right marks" when
creating a calendar with the \fB\-c\fR option.  Some terminals don't
handle this correctly and garble the rendering of the calendar; see
the documentation of \fB$SuppressLRM\fR in the section "SYSTEM
VARIABLES" for a workaround.
.RE
.TP
.B \-@\fR[\fIn\fR][,\fIm\fR][,\fIb\fR]
Tells \fBRemind\fR to approximate SPECIAL COLOR and SHADE reminders
using VT100 escape sequences.  The approximation is (of necessity)
very coarse, because the VT100 only has eight different color
sequences, each with one of two brightnesses.  A color component
greater than 64 is considered "on", and if any of the three color
components is greater than 128, the color is considered "bright".
.RS
.PP
If you supply the optional numeric parameters, the have the following
meanings:  \fIn\fR=0 tells \fBRemind\fR to use the standard 16 VT100
colors.  \fIn\fR=1 tells it to use an extended 256-color palette supported
by many terminal emulators such as xterm.  And \fIn\fR=2 tells it to
use escape sequences that support true 24-bit colors, again supported
by many terminal emulators such as xterm.
.PP
If the optional \fIm\fR parameter is supplied following a comma, then
\fIm\fR=0 tells \fBRemind\fR that the terminal background is dark, and
\fBRemind\fR will brighten up dark colors to make them visible.  If
\fIm\fR=1, then \fBRemind\fR assumes the terminal background is light
and it will darken bright colors to make them visible.  If \fIm\fR is
specified as 2, then \fBRemind\fR does not perform any adjustments,
and some reminders may be hard or impossible to see if the color is
too close to the terminal background color.  If you supply the letter
\fBt\fR rather than a number, then \fBRemind\fR attempts to guess the background
color of the terminal, \fIeven if\fR stdout is not a terminal.
.PP
On startup, if the standard output is a terminal, \fBRemind\fR
attempts to determine if the terminal background is dark or light by
sending a special escape sequence to determine the background color.
The \fIm\fR parameter can override this check (or force it if
\fIm\fR is given as \fBt\fR.)
.PP
If the optional \fIb\fR parameter is supplied following a comma, then
\fIb=0\fR tells \fBRemind\fR to ignore SPECIAL SHADE reminders (the
default) and \fIb=1\fR tells \fBRemind\fR to respect SPECIAL SHADE
reminders by emitting VT100 escape codes to color the background of the
calendar cell.  Note that SHADE does not work well unless you are
using the extended 256-color palette (\fIn\fR=1) or the true
24-bit colors (\fIn\fR=2).  Note that for calendar cells that are
shaded, the clamping mechanism described earlier for \fIm=0\fR or
\fIm=1\fR is skipped; it is assumed that if you set \fIboth\fR the
foreground color of a reminder and the background color of a cell,
then you know what you are doing.
.RE
.TP
.B \-w\fR\fIcol\fR[,\fIpad\fR[,\fIspc\fR[,\fIspc2\fR]]]]
The \fB\-w\fR option specifies the output width, padding and spacing
of the formatted calendar output.  \fICol\fR specifies the number of
columns in the output device.  If \fIcol\fR is not specified, or is
specified as 0, it defaults to the larger of 71 or the actual width of
your terminal, or to 80 if standard output is not a terminal.  If
\fIcol\fR is specified as the letter \fBt\fR, then \fBRemind\fR
attempts to get the width of the \fB/dev/tty\fR terminal device.  This
is useful, for example, if you pipe calendar output into \fBless\fR;
even though standard output is a pipe, you want the calendar to be
sized correctly for your terminal window:
.RS
.PP
.nf
        remind -c -wt .reminders | less
.fi
.RE

.RS
.PP
Note that the value of \fIcol\fR is also used to set the system variable
$FormWidth, which is initialized to \fIcol\fR - 8.  See "SYSTEM VARIABLES"
for details.

.PP
\fIPad\fR specifies how many lines
to use to "pad" empty calendar boxes.  This defaults to 5.  If you
have many reminders on certain days that make your calendar too large
to fit on a page, you can try reducing \fIpad\fR to make the empty
boxes smaller.  \fISpc\fR specifies how many blank lines to leave
between the day number and the first reminder entry.  It defaults to
1.  \fIspc2\fR may be 0 or 1 and it specifies whether or not blank
lines should be printed in between reminders on the same day.  The
default is 1, which causes the blank lines to be printed.
.PP
Any of \fIcol\fR, \fIpad\fR or \fIspc\fR can be omitted, providing you
provide the correct number of commas.  Don't use any spaces in the option.
.RE
.TP
.B \-s\fR[\fBa\fR]\fIn\fR
The \fB\-s\fR option is very similar to the \fB\-c\fR option, except
that the output calendar is not formatted.  It is listed in a "simple
format" that can be used as input for more sophisticated calendar-drawing
programs.  If \fIn\fR starts with "+", then it is interpreted as a number
of weeks.  This option also implicitly enables the \fB\-o\fR option.

If you immediately follow the \fBs\fR with the letter
\fBa\fR, then \fBRemind\fR displays reminders on the calendar on the
day they actually occur \fIas well as\fR on any preceding days specified
by the reminder's \fIdelta\fR.
.TP
.B \-p\fR[\fBa\fR][\fBp\fR][\fBp\fR][\fBq\fR][+]\fIn\fR
The \fB\-p\fR option is very similar to the \fB\-s\fR option, except
that the output contains additional information for use by a back-end
such as the \fBRem2PS\fR program, which creates a PostScript calendar,
and various other back-end programs.  If \fIn\fR starts with "+", then
it specifies a number of weeks rather than a number of months, and
back-ends are expected to produce weekly calendars.  Note that not all
back-ends support weekly calendars; currently, only \fBrem2pdf\fR and
\fBrem2html\fR do.  Specifying a weekly calendar implicitly enables
the pure JSON interchange format, similar to \fB\-ppp\fR.
.RS
.PP
The format of the \fB\-p\fR output is described in the \fBrem2ps(1)\fR
man page.  If you immediately follow the \fBp\fR with the letter
\fBa\fR, then \fBRemind\fR displays reminders on the calendar on the
day they actually occur \fIas well as\fR on any preceding days specified
by the reminder's \fIdelta\fR.  If you follow the \fBp\fR with another
\fBp\fR, then \fBRemind\fR uses a more comprehensive JSON-based
format rather than the "simple calendar" format.  This format is
also documented in the \fBrem2ps(1)\fR man page.  Finally, if you use
three p's, as in \fB\-ppp\fR, then \fBRemind\fR uses a pure JSON
format, again documented in \fBrem2ps(1)\fR.  If you include a \fBq\fR
letter with this option, then the usual calendar-mode substitution filter
is disabled and the %"...%" sequences are preserved in the output.
.PP
Note that to pass INFO strings to a back-end, you must use \fB\-pp\fR
or \fB\-ppp\fR.  The simpler \fB\-p\fR format is not capable of
transmitting the INFO strings to the back-end.
.PP
The \fB\-p\fR, \fB\-pp\fR and \fB\-ppp\fR options implicitly enable
the \fB\-o\fR option.
.PP
Note that the \fB\-pp\fR or \fB\-ppp\fR options also enable the \fB\-l\fR
option.
.RE
.TP
.B \-l
If you use the \-l option in conjunction with the \-p option, then
\fBRemind\fR outputs additional information for back-end programs such
as \fBrem2ps\fR.  This additional information lets the back-end programs
correlate a reminder with the source file and line number that produced
it.
.TP
.B \-m
The \fB\-m\fR option causes the \fB\-c\fR or \fB\-p\fR options to produce
a calendar whose first column is Monday rather than Sunday.
(This conforms to the international standard.)
.TP
.B \-v
The \fB\-v\fR option makes the output of \fBRemind\fR slightly more verbose.
Currently, this causes \fBRemind\fR to echo a bad line in case of an
error, and to print a security message if a script tests the
$RunOff system variable.
.TP
.B \-o
The \fB\-o\fR option causes \fBRemind\fR to ignore all \fBONCE\fR
directives.  Note that \fBONCE\fR is also ignored if any of the
\fB\-c\fR, \fB\-n\fR, \fB\-p\fR, or \fB\-s\fR options is used, if a
repetition factor \fB*n\fR is used, or if a date other than today's
date is specified on the command-line.
.TP
.B \-t
The \fB\-t\fR option causes \fBRemind\fR to trigger all non-expired reminders,
regardless of the \fIdelta\fR supplied for each reminder.
.TP
.B \-t\fR\fIn\fR
If you supply a number \fIn\fR after the \fB\-t\fR option, then
\fBRemind\fR pretends that every \fBREM\fR command has a delta
of ++\fIn\fR, regardless of any existing delta.
.TP
.B \-tz\fR
If you supply the letter \fBz\fR after the \fB\-t\fR option, then
\fBRemind\fR sets all REM statements' deltas to zero, regardless of the
value supplied in the REM statement itself.  In effect, this disables
all deltas of the form \fB+\fIn\fR and \fB++\fIn\fR.
.TP
.B \-tt\fR[\fIn\fR]
The \fB-tt\fR option causes \fBRemind\fR to assume a default delta of
\fIn\fR minutes for all timed reminders.  If \fB\-tt\fR is given with
no \fIn\fR, a default delta of 5 minutes is used.
.TP
.B \-h
The \fB\-h\fR option ("hush...") suppresses certain warning and information
messages.  In particular, if no reminders are triggered, this mode
produces no output.
.TP
.B \-a
The \fB\-a\fR option causes \fBRemind\fR not to immediately trigger
timed reminders that trigger on the current day.  It also causes
\fBRemind\fR not to place timed reminders in a calendar.  If you
supply two or more \fB\-a\fR options, then \fBRemind\fR \fIwill\fR
trigger timed reminders that are in the future, but will not trigger
timed reminders whose time has passed.  (Regardless of how many
\fB\-a\fR options you supply, \fBRemind\fR will not include timed
reminders in the calendar if at least one \fB\-a\fR option is used.)

.TP
\fB\-q\fR
The \fB\-q\fR option causes \fBRemind\fR not to queue timed reminders
for later execution.
.TP
\fB\-f\fR
The \fB\-f\fR option causes \fBRemind\fR to remain in the foreground
when processing queued reminders, rather than forking off
a background process to handle them.
.TP
.B \-e
The \fB\-e\fR option diverts error messages (normally sent to the
standard error stream) to the standard output stream.
.TP
.B \-d\fR\fIchars\fR
The \fB-d\fR option enables certain debugging modes.  The \fIchars\fR
specify which modes to enable:
.RS
.TP
.B e
Echo all input lines
.TP
.B x
Trace all expression evaluation
.TP
.B t
Display all trigger date computation
.TP
.B v
Dump the variable table after execution of the reminder script
.TP
.B l
Echo lines when displaying error messages
.TP
.B f
Trace the reading of reminder files
.TP
.B s
Trace expression parsing and display the internal expression node
tree.  This is unlikely to be useful unless you are working on
\fBRemind\fR's expression evaluation engine.
.TP
.B h
Dump hash-table statistics on exit.
.TP
.B u
When \fBRemind\fR exits, print a list of variables that were SET, but
not subsequently used.
.RS
.PP
Note that the \fBu\fR debugging flag may produce spurious warnings.  For
example, this sequence of commands:
.PP
.nf
        DEBUG +u
        SET a 1
        IFTRIG Wed
                MSG a = [a]
        ENDIF
.fi
.PP
will issue a warning about \fBa\fR being unused unless it is run on a
Wednesday.
.RE
.TP
.B n
Print debugging information about why \fBRemind\fR considers an expression
to be "non-constant"
.TP
.B q
Output a TRANSLATE command each time the \fB_()\fR built-in function
is called or the \fB%(...)\fR substitution sequence is encountered.
.RE
.TP
\fB\-g\fR[\fBa|d\fR[\fBa|d\fR[\fBa|d\fR[\fBa|d\fR]]]]
Normally, reminders are issued in the order in which they are
encountered in the reminder script.  The \fB\-g\fR option cause
\fBRemind\fR to sort reminders by date and time prior to issuing them.
The optional \fBa\fR and \fBd\fR characters specify the sort order
(ascending or descending) for the date, time and priority fields.  See
the section "SORTING REMINDERS" for more information.

Note that \fB\-g\fR is \fIignored\fR if you use the \fB\-n\fR option.
.TP
\fB\-b\fR[\fIn\fR]
Set the time format for the calendar and simple-calendar outputs.  \fIN\fR
can range from 0 to 2, with the default 0.  A value of 0 causes times
to be inserted in 12-hour (am/pm) format.  1 causes times to be inserted
in 24-hour format, and 2 inhibits the automatic insertion of times in the
calendar output.
.TP
\fB\-x\fR[\fIn\fR]
Sets the iteration limit for the \fBSATISFY\fR clause of a \fBREM\fR
command.  Defaults to 1000.
.TP
\fB\-k\fR\fIcmd\fR
Instead of simply printing \fBMSG\fR-type
reminders, this causes them to be passed to the specific \fIcmd\fR.
You must use '%s' where you want the body to appear, and may need to
enclose this option in quotes.  Note that all shell characters in the
body of the reminder are escaped with a backslash, and the entire body
of the reminder is passed as a single argument.  Note that this option
\fBoverrides\fR the \fB\-r\fR option and the \fBRUN OFF\fR command.
.PP
.RS
As an example, suppose you have an X Window program called \fBxmessage\fR that
pops up a window and displays its invocation arguments.  You could use:
.PP
.nf
		remind '\-kxmessage %s &' ...
.fi
.PP
to have all of your \fBMSG\fR-type reminders processed using xmessage.
.PP
A word of warning: It is very easy to spawn dozens of xmessage
processes with the above technique.  So be very careful.  Because all
shell and whitespace characters are escaped, the program you execute
with the \fB\-k\fR option must be prepared to handle the entire
message as a single argument.
.PP
If you follow the \fB\-k\fR option with a colon, then the command is applied
only to queued timed reminders.  Normal reminders are handled as usual.
In the above example, if you want normal reminders to simply be displayed
as usual, but queued reminders to be sent to notify-send, you could use:
.PP
.nf
		remind '\-k:notify-send %s &' ...
.fi
.PP
You use both \fB\-k\fR\fIcmd1\fR and \fB\-k:\fR\fIcmd2\fR to use different
commands for queued versus non-queued reminders.
.RE
.TP
\fB\-z\fR[\fIn\fR] Runs \fBRemind\fR in "daemon mode".  If \fIn\fR
is supplied, it specifies how often (in minutes) \fBRemind\fR should
wake up to check if the reminder script has been changed.  \fIN\fR
defaults to 1, and can range from 1 to 60.  Note that the use of the
\fB\-z\fR option also enables the \fB\-f\fR option.
.PP
.RS
If \fBRemind\fR is compiled on a system that supports
\fBinotify\fR(7), then if the reminder script supplied on the
command-line is actually a directory, \fBRemind\fR additionally checks
if all files within that directory have been modified since startup.
.PP
If you supply the option \fB\-zj\fR, \fBRemind\fR runs in a
special mode called \fBserver mode\fR.  This is documented
in the tkremind man page; see tkremind(1).  The older server mode
option \fB\-z0\fR still works, but is deprecated; it uses an ad-hoc
method to communicate with the client rather than using JSON to communicate
with the client.
.RE
.TP
\fB\-u\fR\fIname\fR
Runs \fBRemind\fR with the uid and gid of the user specified by \fIname\fR.
The option changes the uid and gid as described, and sets the
environment variables HOME, SHELL and USER to the home directory, shell,
and user name, respectively, of the specified user.  LOGNAME is also
set to the specified user name.  This option is meant for
use in shell scripts that mail reminders to all users.  Note that
as of \fBRemind\fR 3.00.17, using \fB\-u\fR implies \fB\-r\fR -- the RUN
directive and shell() functions are disabled.  However, if you prefix
\fIname\fR with a \fB+\fR-sign, then RUN and shell() are \fInot\fR
disabled.  That is, \fB\-uwhatever\fR switches the user to \fBwhatever\fR
and disables RUN, whereas \fB\-u+whatever\fR switches the user to
\fBwhatever\fR but leaves RUN enabled.
.PP
.RS
Non-root users can also use the \fB\-u\fR option.  However, in this
case, it only changes the environment variables as described above.
It does not change the effective uid or gid.
.RE
.TP
\fB\-+\fIusername\fR
Causes \fBRemind\fR to trust files owned by the user \fIusername\fR.
Normally, if \fBRemind\fR reads a file that you do not own, it disables
RUN and the shell() function.  This option causes it to also trust files
owned by \fIusername\fR.  You can supply multiple \fB\-+\fR options
to trust multiple users, up to a limit of 20 trusted users.
.TP
\fB-y\fR
Causes \fBRemind\fR to synthesize a tag for any reminder that lacks a
TAG clause.
.TP
\fB\-i\fR\fIvar\fR\fB=\fR\fIexpr\fR
Sets the value of the specified \fIvar\fR to \fIexpr\fR, and \fBpreserves\fR
\fIvar\fR.  \fIExpr\fR can be any valid \fBRemind\fR expression.  See the
section "INITIALIZING VARIABLES ON THE COMMAND LINE" for more details.  If
you omit the \fB=\fR\fIexpr\fR part, then \fIvar\fR is initialized to 0.
In other words, \fB\-i\fIvar\fR is exactly the same as \fB\-i\fIvar\fR\fB=\fR0.
.TP
\fB\-i\fR\fIfunc\fR(\fIargs\fR)=\fIdefinition\fR
Allows you to define a function on the command line.
.PP
If you supply a \fIdate\fR on the command line, it must consist of
\fIday month year\fR, where \fIday\fR is the day of the month,
\fImonth\fR is at least the first three letters of the English name
of the month, and \fIyear\fR is a year (all 4 digits) from 1990 to
about 2075.  You can leave out the \fIday\fR, which then defaults to 1.
.PP
If you do supply a \fIdate\fR on the command line, then \fBRemind\fR
uses it, rather than the actual system date, as its notion of "today."
This lets you create calendars for future months, or test to see how
your reminders will be triggered in the future.  Similarly, you can
supply a \fItime\fR to set \fBRemind\fR's notion of "now" to a
particular time.  Supplying a \fItime\fR on the command line also
implicitly enables the \fB\-q\fR option and disables the \fB\-z\fR
option.  The \fItime\fR may be specified in 24-hour format (e.g., 13:20)
or common "AM/PM" format (1:20pm).
.PP
If you would rather specify the date more succinctly, you can supply
it as YYYY-MM-DD or YYYY/MM/DD.  You can even supply a date and
time on the command line as one argument: YYYY-MM-DD@HH:MM.
.PP
In addition, you can supply a \fIrepeat\fR parameter, which has the
form *\fIrep\fR.  This causes \fBRemind\fR to be run \fIrep\fR times,
with the date incrementing on each iteration.  You may have to enclose
the parameter in quotes to avoid shell expansion.  See the subsection
"Repeated Execution" in the section "CALENDAR MODE" for more
information.

.SH LONG OPTIONS

\fBRemind\fR supports the following long options, which \fIare\fR
case-sensitive:

.TP
.B \-\-version
The \fB\-\-version\fR option causes \fBRemind\fR to print its version number
to standard output and then exit.
.TP
.B \-\-hide-completed-todos
In Calendar Mode, \fBRemind\fR normally shows all TODOs.  If you supply
this option, the it will not show TODOs that have been marked as
completed.
.TP
.B \-\-only-todos
Only issue TODO-type reminders.
.TP
.B \-\-only-events
Do not issue TODO-type reminders.
.TP
.B \-\-json
In Agenda Mode, output JSON instead of the normal text-mode output.
\fB\-\-json\fR also disables sorting (the \fB-g\fR option) and
disables queueing (the \fB-q\fR option).  See the section "AGENDA MODE
JSON OUTPUT" for more details.  The \fB\-\-json\fR option is ignored
in Calendar Mode.  Note that in JSON mode, the output from any
\fBRUN\fR-type reminder that would normally appear on standard output
is redirected to standard error instead; this is so that \fBRUN\fR-type
reminders don't mess up the output and cause invalid JSON to be produced
on standard output.
.TP
.B \-\-print-errs
The \fB\-\-print-errs\fR option causes \fBRemind\fR to print all
possible error messages to standard output and then exit.  The
messages are printed in a format suitable for the first argument of a
TRANSLATE command.  If you TRANSLATE the error messages, then
\fBRemind\fR will use the translated versions when outputting error
and warning messages.  See also TRANSLATE GENERATE in the section
"THE TRANSLATION TABLE".
.RS
.PP
Note that if an untranslated message contains printf-style formatting
sequences like "%s" or "%d", then the translated message \fImust\fR
contain the same sequences in the same order, or \fBRemind\fR will
ignore it and use the original untranslated message.
.RE
.TP
.B \-\-print-config-cmd
This option causes \fBRemind\fR to print the exact \fB./configure\fR
command that was used when \fBRemind\fR was built.  You can use this
to build a new version of \fBRemind\fR using the same configuration
as an existing one by running:
.RS
.PP
.nf
        eval `remind --print-config-cmd`
.fi
.PP
from the top-level \fBRemind\fR source directory.  (However, it's safer
to simply run \fBremind --print-config-cmd\fR and then type in the
command once you've verified that it looks OK.)
.RE

.TP
.B \-\-print-tokens
The \fB\-\-print-tokens\fR option causes \fBRemind\fR to print the tokens
used by the parser, built-in function names, and system variable names
to standard output and then exit.  This output is designed to make it easy
to create a syntax-highlighting file for various text editors.  The output
can be modified by hand or by a script into a syntax-highlighting file
with relative ease.
.TP
.B \-\-max-execution-time\fR=\fIn\fR
Limit the total execution time (as measured by the wall clock) to
\fIn\fR seconds.  This is useful if \fBRemind\fR is invoked on
potentially-untrustworthy files that could attempt to use a lot of
resources.  Note that the limit \fIn\fR is approximate and
\fBRemind\fR might execute for one or two more seconds before it is
killed.  If \fIn\fR is specified as zero, then no limit is applied, just
as if the option had not been used at all.
.RS
.PP
If a limit is applied, it applies only to the foreground run of \fBRemind\fR.
If \fBRemind\fR finishes processing the script and then starts handling
queued reminders, the time limit is reset to no limit.
.RE
.TP
.B \-\-max-expr-complexity\fR=\fIn\fR
Limit the total complexity of expression valuation for a given line in a script
to \fIn\fR nodes.  Roughly speaking, each function call, operator, constant,
variable reference, etc corresponds to one expression node.  By default,
the limit is set to 10000000 (ten million).  You can explicitly set it
to zero if you don't want any limit to apply.  The default limit of ten
million should never be triggered by any sensible Remind script, however,
and we don't recommend changing the limit.
.TP
.B \-\-test
The \fB\-\-test\fR long option is only for use by the acceptance tests
run by "make test".  Do not use this option in production.
.TP
.B \-\-flush
The \fB\-\-flush\fR long option makes \fBRemind\fR's standard output
and standard error streams unbuffered.  It is mostly used for testing and
should probably not be used in production.
.SH REMINDER FILES
.PP
\fBRemind\fR uses scripts to control its operation.  You can use any
text editor capable of creating plain-text files to create a
\fBRemind\fR script.  The commands inside a script can range from the
very simple and almost immediately understandable:
.PP
.nf
        REM Mar 31 MSG International Transgender Day of Visibility
.fi
.PP
to the baroque and obscure:
.PP
.nf
        REM [date(thisyear, 1, 1) + 180] ++5 OMIT \\
        sat sun BEFORE MSG [ord(thisyear-1980)] payment due %b!
.fi
.PP
A reminder file consists of commands, with one command per line.  Several
lines can be continued using the backslash character, as in the above
example.  In this case, all of the concatenated lines are treated as a
single line by \fBRemind\fR.  Note that if an error occurs, \fBRemind\fR
reports the line number of the last line of a continued line.
.PP
\fBRemind\fR ignores blank lines, and lines beginning with the '#' or ';'
characters.  You can use the semicolon as a comment character if you
wish to pass a \fBRemind\fR script through the C pre-processor, which
interprets the '#' character as the start of a pre-processing
directive.
.PP
Note that \fBRemind\fR processes line continuations before anything else.
For example:
.PP
.nf
	# This is a comment \\
	This line is part of the comment because of line continuation \\
	and so on.
	REM MSG This line is not ignored (no \\ above)
.fi
.PP
\fBRemind\fR is not case sensitive; you can generally use any mixture of upper-
or lower-case for commands, parameters, invocation options, etc.
.SH THE REM COMMAND
.PP
The most powerful command in a \fBRemind\fR script is the \fBREM\fR command.
This command is responsible for issuing reminders.
Its syntax is:
.PP
.RS
\fBREM\fR [\fBONCE\fR] [\fIdate_spec\fR]
[\fIback\fR]
[\fIdelta\fR]
[\fIrepeat\fR]
[\fBTODO\fR]
[\fBMAX-OVERDUE\fR \fIn\fR]
[\fBCOMPLETE-THROUGH\fR \fIcomplete_date\fR]
[\fBPRIORITY\fR \fIprio\fR]
[\fBSKIP\fR | \fBBEFORE\fR | \fBAFTER\fR]
[\fBOMIT\fR \fIomit_list\fR]
[\fBADDOMIT\fR]
[\fBNOQUEUE\fR]
[\fBOMITFUNC\fR \fIomit_function\fR]
[\fBAT\fR \fItime\fR [\fItdelta\fR] [\fItrepeat\fR]]
[\fBSCHED\fR \fIsched_function\fR]
[\fBWARN\fR \fIwarn_function\fR]
[\fBUNTIL\fR \fIexpiry_date\fR | \fBTHROUGH\fR \fIlast_date\fR]
[\fBSCANFROM\fR \fIscan_date\fR | \fBFROM\fR \fIstart_date\fR]
[\fBDURATION\fR \fIduration\fR]
[\fBTAG\fR \fItag\fR]
[\fBTZ\fR \fItimezone\fR]
[\fBINFO\fR "\fIinfo_string\fR"]
\fBMSG\fR | \fBMSF\fR | \fBRUN\fR | \fBCAL\fR | \fBSATISFY\fR |
\fBSPECIAL\fR \fIspecial\fR | \fBPS\fR | \fBPSFILE\fR
.I body
.RE
.PP
The parts of the \fBREM\fR command can be specified in any order, except
that the \fIbody\fR must come immediately after the \fBMSG\fR,
\fBRUN\fR, \fBCAL\fR, \fBPS\fR, \fBPSFILE\fR or \fBSATISFY\fR keyword.
The portion of the \fBREM\fR command before the \fBMSG\fR, \fBMSF\fR
\fBRUN\fR, \fBCAL\fR or \fBSATISFY\fR clause is called a
\fItrigger\fR.
.PP
In earlier versions of \fBRemind\fR, the \fBREM\fR token was optional
providing that the remainder of the command cannot be mistaken for
another \fBRemind\fR command.  However, this use is deprecated and will
now cause a warning to be issued.  All of your reminder lines should
be written to start with the REM command.
.PP
.B "MSG, MSF, RUN, CAL, SPECIAL, PS and PSFILE"
.PP
These keywords denote the \fItype\fR
of the reminder.  (\fBSATISFY\fR is more complicated and will be explained
later.)  A \fBMSG\fR-type reminder normally prints a message to the standard
output, after passing the \fIbody\fR through a special substitution filter,
described in the section "THE SUBSTITUTION FILTER."  However, if you have
used the \fB\-k\fR command-line option, then \fBMSG\fR-type reminders are
passed to the appropriate program.  Note that the options \fB\-c\fR,
\fB\-s\fR, \fB\-p\fR and \fB\-n\fR disable the \fB\-k\fR option.
.PP
Earlier versions of \fBRemind\fR let you omit the reminder type,
in which case it defaulted to \fBMSG\fR.  However, this usage is
deprecated and will cause a warning.  Something like:
.PP
.nf
	REM 6 January Dianne's Birthday
.fi
.PP
will issue the warning "Missing REM type; assuming MSG"

.PP
The \fBMSF\fR keyword is almost the same as the \fBMSG\fR keyword,
except that the reminder is formatted to fit into a paragraph-like
format.  Three system variables control the formatting of \fBMSF\fR-type
reminders - they are \fB$FirstIndent\fR, \fB$SubsIndent\fR and
\fB$FormWidth\fR.  They are discussed in the section "SYSTEM VARIABLES."
The \fBMSF\fR keyword causes the spacing of your reminder to be altered -
extra spaces are discarded, and two spaces are placed after periods and
other characters, as specified by the system variables \fB$EndSent\fR and
\fB$EndSentIg\fR.  Note that if the body of the reminder includes
newline characters (placed there with the %_ sequence), then the newlines
are treated as the beginnings of new paragraphs, and the \fB$FirstIndent\fR
indentation is used for the next line.  You can use two consecutive
newlines to have spaced paragraphs emitted from a single reminder body.
.PP
A \fBRUN\fR-type reminder also passes the \fIbody\fR through the
substitution filter, but then executes the result as a system command.
A \fBCAL\fR-type reminder is used only to place entries in the
calendar produced when \fBRemind\fR is run with the \fB\-c\fR,
\fB\-s\fR or \fB\-p\fR options.  When \fBRemind\fR runs a command, it
sets the command's standard input to come from /dev/null.
.PP
A \fBPS\fR or \fBPSFILE\fR-type reminder is used to pass PostScript code
directly to the printer when producing PostScript calendars.  This can
be used to shade certain calendar entries (see the psshade() function),
include graphics in the calendar,
or almost any other purpose you can think of.  You
should not use these types of reminders unless you are an expert PostScript
programmer.  The \fBPS\fR and \fBPSFILE\fR reminders are ignored unless
\fBRemind\fR is run with the \fB\-p\fR option.  See the section
"More about PostScript" for more details.
.PP
A \fBSPECIAL\fR-type reminder is used to pass "out-of-band" information
from \fBRemind\fR to a calendar-producing back-end.  It should be followed
by a word indicating the type of special data being passed.  The type
of a special reminder depends on the back-end.  For the \fBRem2PS\fR
back-end, \fBSPECIAL PostScript\fR is equivalent to a \fBPS\fR-type
reminder, and \fBSPECIAL PSFile\fR is equivalent to a \fBPSFILE\fR-type
reminder.  The body of a \fBSPECIAL\fR reminder is obviously dependent
upon the back-end.  A back-end \fImust\fR ignore a \fBSPECIAL\fR that
it does not recognize.
.PP
.B DATE SPECIFICATIONS
.PP
A \fIdate_spec\fR consists of zero to four parts.
These parts are
.I day
(day of month),
.I month
(month name),
.I year
and
.I weekday.
.I Month
and
.I weekday
are the English names of months and weekdays.  At least the first three
characters must be used.  The following are examples of the various parts of a
.I date_spec:
.TP
.I day:
1, 22, 31, 14, 3
.TP
.I month:
JANUARY, feb, March, ApR, may, Aug
.TP
.I year:
1990, 1993, 2030.  The year can range
from 1990 to 2075.
.TP
.I weekday:
Monday, tue, Wed, THU, Friday, saturday, sundAy
.PP
Note that there can be several
.I weekday
components separated by spaces in a
.I date_spec.
.PP
.B INTERPRETATION OF DATE SPECIFICATIONS
.PP
The following examples show how date specifications are interpreted.
.PP
1. Null date specification - the reminder is triggered every day.
The trigger date for a specific run is simply the current system date.
For example:
.PP
.nf
        REM MSG This is triggered every time Remind runs
.fi
.PP
2. Only
.I day
present.  The reminder is triggered on the specified day of each month.
The trigger date for a particular run is the closest such day to the
current system date.  For example:
.PP
.nf
	REM 1 MSG First of every month.
	REM 31 MSG 31st of every month that has 31 days.
.fi
.PP
3. Only
.I month
present.  The reminder is triggered every day of the specified month.
Example:
.PP
.nf
	REM Feb MSG Every day in February
.fi
.PP
4.
.I day
and
.I month
present.  Examples:
.PP
.nf
	REM 6 Jan MSG Every 6th of January
	REM Feb 29 MSG Every 29th of February
.fi
.PP
5.  Only
.I year
present. Example:
.PP
.nf
	REM 1991 MSG Every day in 1991
.fi
.PP
6.
.I year
and
.I day
present.  Examples:
.PP
.nf
	REM 1 1990 MSG 1st of every month in 1990
	REM 1992 23 MSG 23rd of every month in 1992
.fi
.PP
7.
.I year
and
.I month
present.  Examples:
.PP
.nf
	REM Feb 1991 MSG Every day in Feb 1991
	REM 1992 September MSG Every day in Sept 1992
.fi
.PP
8.
.I year, month
and
.I day
present.  Examples:
.PP
.nf
	REM 8 Jan 1991 MSG 8th January 1991.
	REM 1992 March 9 MSG 9th March 1992.
.fi
.PP
9.
.I weekday
only.  Examples:
.PP
.nf
	REM Sat MSG Every Saturday
	REM Mon Tue Wed Thu Fri MSG Every working day
	REM Monday Wednesday MSG Every Monday and Wednesday
.fi
.PP
10.
.I weekday
and
.I day
present.  Examples:
.PP
.nf
	REM Sat 1 MSG First Saturday of every month
	REM Mon Tue Wed Thu Fri 15 \\
		MSG 1st working day on or after 15th of every month
.fi
.PP
11.
.I weekday
and
.I month
present.  Examples:
.PP
.nf
	REM Mon March MSG Every Monday in March
	REM Mon Tue Wed Thu Fri Feb MSG Every working day in February
.fi
.PP
12.
.I weekday, month
and
.I day
present.  Examples:
.PP
.nf
	REM Mon 1 March MSG First Monday in March
	REM Sat Sun 15 July MSG First Sat or Sun on or after 15 July
.fi
.PP
13.
.I weekday
and
.I year
present.  Example:
.PP
.nf
	REM Sat Sun 1991 MSG Every Saturday and Sunday in 1991
.fi
.PP
14.
.I weekday, day
and
.I year
present.  Examples:
.PP
.nf
	REM Mon 15 1990 MSG 1st Mon after 15th of every month in 1990
	REM Mon Tue Wed Thu Fri 1 1990 \\
		MSG 1st working day of every month in 1990
.fi
.PP
15.
.I weekday, month
and
.I year
present.  Example:
.PP
.nf
	REM Mon Wed 1991 Feb MSG Every Mon and Wed in Feb 1991.
.fi
.PP
16.
.I weekday, day, month
and
.I year
present.  Example:
.PP
.nf
	REM Mon Tue Wed Thu Fri 28 Oct 1990 \\
		MSG 1st working day on or after 28 October 1990.
.fi
.PP
Note that when both
.I weekday
and
.I day
are specified,
.B Remind
chooses the first date on or after the specified
.I day
that also satisfies the
.I weekday
constraint.  It does this by picking the first date on or after the specified
.I day
that is listed in the list of
.I weekdays.
Thus, a reminder like:
.PP
.nf
	REM Mon Tue 28 Oct 1990 MSG Hi
.fi
.PP
would be issued only on Monday, 29 October, 1990.  It would not be issued
on Tuesday, 30 October, 1990, since the 29th is the first date to satisfy
the
.I weekday
constraints.
.PP
.B SHORT-HAND DATE SPECIFICATIONS
.PP
In addition to spelling out the day, month and year separately, you
can specify YYYY-MM-DD or YYYY/MM/DD.  For example, the following statements
are equivalent:
.PP
.nf
	REM 5 June 2010 MSG Cool!
	REM 2010-06-05  MSG Cool!
.fi
.PP
You can also specify a date and time as YYYY-MM-DD@HH:MM.  These
statements are equivalent:
.PP
.nf
	REM 19 Dec 2010 AT 16:45 MSG Hi
	REM 2010-12-19@16:45 MSG Hi
.fi
.PP
There's one subtlety with short-hand date specifications:  The following
statements are \fInot\fR equivalent:
.PP
.nf
	REM 19 Dec 2010 AT 16:45 +60 MSG Hi
	REM 2010-12-19@16:45 +60 MSG Hi
.fi
.PP
In the second statement, the "+60" is a \fIdelta\fR that applies to the
date rather than a \fItdelta\fR that applies to the time.  We recommend
explicitly using the AT keyword with timed reminders.
.PP
.B THE REMIND ALGORITHM
.PP
\fBRemind\fR uses the following algorithm to compute a trigger date:
Starting from the current date, it examines each day, one at a time, until
it finds a date that satisfies the date specification, or proves to
itself that no such date exists.  (Actually, \fBRemind\fR merely
\fIbehaves\fR as if it used this algorithm; it would be much too slow
in practice.  Internally, \fBRemind\fR uses much faster techniques to
calculate a trigger date.)  See DETAILS ABOUT TRIGGER COMPUTATION for
more information.
.PP
.B BACKWARD SCANNING
.PP
Sometimes, it is necessary to specify a date as being a set amount of
time before another date.  For example, the last Monday in a given
month is computed as the first Monday in the next month, minus 7 days.
The \fIback\fR specification in the reminder is used in this case:
.PP
.nf
	REM Mon 1 \-7 MSG Last Monday of every month.
.fi
.PP
A \fIback\fR is specified with one or two dashes followed by an integer.
This causes \fBRemind\fR to move "backwards" from what would normally be the
trigger date.  The difference between \-\-7 and \-7 will be explained
when the \fBOMIT\fR keyword is described.
.PP
.B ADVANCE WARNING
.PP
For some reminders, it is appropriate to receive advance warning of the
event.  For example, you may wish to be reminded of someone's birthday
several days in advance.  The \fIdelta\fR portion of the \fBREM\fR command
achieves this.  It is specified as one or two "+" signs followed by a number
\fIn\fR.  Again, the difference between the "+" and "++" forms will
be explained under the \fBOMIT\fR keyword.
\fBRemind\fR will trigger the reminder on computed trigger date, as well as
on each of the \fIn\fR days before the event.  Here are some examples:
.PP
.nf
	REM 6 Jan +5 MSG Remind me of birthday 5 days in advance.
.fi
.PP
The above example would be triggered every 6th of January, as well as the
1st through 5th of January.
.PP
.B PERIODIC REMINDERS
.PP
We have already seen some built-in mechanisms for certain types of
periodic reminders.  For example, an event occurring every Wednesday
could be specified as:
.PP
.nf
	REM Wed MSG Event!
.fi
.PP
However, events that do not repeat daily, weekly, monthly or yearly require
another approach.  The \fIrepeat\fR component of the \fBREM\fR command
fills this need.  To use it, you must completely specify a date (year, month
and day, and optionally weekday); this is the start date of the
repetition period.  The \fIrepeat\fR component is an asterisk
followed by a number specifying the repetition period in days.
.PP
For example, suppose you get paid every second Wednesday, and your
last payday was Wednesday, 28 October, 1992.  You can use:
.PP
.nf
	REM 28 Oct 1992 *14 MSG Payday
.fi
.PP
This issues the reminder every 14 days, starting from 28 Oct 1992.
You can use \fIdelta\fR and \fIback\fR with \fIrepeat.\fR  Note,
however, that the \fIback\fR is used only to compute the starting
date; thereafter, the reminder repeats with the specified
period.  Similarly, if you specify a weekday, it is used only to calculate
the starting date, and does not affect the repetition period.
.PP
.B SCANFROM \fRand\fB FROM
.PP
The \fBSCANFROM\fR and \fBFROM\fR keywords are for advanced \fBRemind\fR programmers
only, and will be explained in the section "DETAILS ABOUT TRIGGER COMPUTATION"
near the end of this manual.  Note that \fBSCANFROM\fR is available only
in versions of \fBRemind\fR from 03.00.04 up.  \fBFROM\fR is available only
from 03.01.00 and later.
.PP
.B PRIORITY
.PP
The \fBPRIORITY\fR keyword must be followed by a number from 0 to 9999.
It is used in calendar mode and when sorting reminders.  If two reminders
have the same trigger date and time, then they are sorted by priority.
If the \fBPRIORITY\fR keyword is not supplied, a default priority of 5000
is used.  (This default can be changed by adjusting the system variable
\fB$DefaultPrio\fR.  See the section "SYSTEM VARIABLES" for more
information.)
.PP
.B EXPIRY DATES
.PP
Some reminders should be issued periodically for a certain time, but then
expire.  For example, suppose you have a class every Friday, and that your
last class is on 11 December 1992.  You can use:
.PP
.nf
	REM Fri UNTIL 11 Dec 1992 MSG Class today.
.fi
.PP
Another example:  Suppose you have jury duty from 30 November 1992 until
4 December 1992.  The following reminder will issue the message every day
of your jury duty, as well as 2 days ahead of time:
.PP
.nf
	REM 1992-11-30 *1 +2 UNTIL 1992-12-04 MSG Jury duty
.fi
.PP
Note that the \fIrepeat\fR of *1 is necessary; without it, the reminder
would be issued only on 30 November (and the two days preceding.)
.PP
As a special case, you can use the \fBTHROUGH\fR keyword instead of
*1 and \fBUNTIL\fR.  The following two \fBREM\fR commands are equivalent:
.PP
.nf
	REM 1992-11-30 *1 +2 UNTIL 1992-12-04 MSG Jury duty

	REM 1992-11-30 +2 THROUGH 1992-12-04 MSG Jury duty
.fi
.PP
If you have an expiry date via the use of \fBTHROUGH\fR or \fBUNTIL\fR,
then \fBRemind\fR will \fInever\fR trigger the reminder after the expiry
date.  For example, if you have this:
.PP
.nf
        OMIT 2021-01-08
        REM 2021-01-01 THROUGH 2021-01-08 AFTER MSG Test
.fi
.PP
the reminder will not be triggered on 2021-01-08, and nor will it be
triggered on 2021-01-09; even though the AFTER keyword would normally
move the 8th's reminder to the 9th, the expiry date of 2021-01-08
overrides that.
.PP
.B THE ONCE KEYWORD
.PP
Sometimes, it is necessary to ensure that reminders are run only once
on a given day.  For example, compare the following two reminders:
.PP
.nf
        REM Fri RUN do_backup
        REM Fri ONCE RUN do_backup
.fi
.PP
The first will be run every time you invoke \fBRemind\fR on a Friday,
whereas the second will be run only the first time you invoke
\fBRemind\fR on a given Friday.
.PP
If you run \fBRemind\fR from your .login script, for example, and log
in several times per day, the \fIdo_backup\fR program in the first
reminder will be run each time you log in.  If, however, you use the
\fBONCE\fR keyword in the reminder, the \fBRemind\fR checks the last
access date of the reminder script.  If it is the same as the current
date, \fBRemind\fR assumes that it has already been run, and will not
issue reminders containing the \fBONCE\fR keyword.
.PP
Note that if you view or edit your reminder script, the last access date
will be updated, and the \fBONCE\fR keyword will not operate properly.
You can fix this by setting a timestamp file for \fBRemind\fR to track
the last-run date; see the documentation of \fB$OnceFile\fR in the
\fBSYSTEM VARIABLES\fR section.  If you use standard input as your
\fBRemind\fR input file, then you \fImust\fR use \fB$OnceFile\fR for the
\fBONCE\fR keyword to work properly.
.PP
If you start \fBRemind\fR with the \fB\-o\fR option, then the \fBONCE\fR
keyword will be ignored and any \fB$OnceFile\fR will be ignored.
.PP
.B LOCALLY OMITTING WEEKDAYS
.PP
The \fBOMIT\fR portion of the \fBREM\fR command is used to "omit" certain
days when counting the \fIdelta\fR or \fIback\fR.  It is specified using
the keyword \fBOMIT\fR followed by a list of weekdays.  Its action is
best illustrated with examples:
.PP
.nf
	REM 1 +1 OMIT Sat Sun MSG Important Event
.fi
.PP
This reminder is normally triggered on the first of every month, as well
as the day preceding it.  However, if the first of the month falls on a
Sunday or Monday, then the reminder is triggered starting from the
previous Friday.  This is because the \fIdelta\fR of +1 does not count
Saturday or Sunday when it counts backwards from the trigger date to
determine how much advance warning to give.
.PP
Contrast this with the use of "++1" in the above command.  In this case,
the reminder is triggered on the first of each month, as well as the day
preceding it.  The omitted days are counted.
.PP
.nf
	REM 1 \-1 OMIT Sat Sun MSG Last working day of month
.fi
.PP
Again, in the above example, the \fIback\fR of \-1 normally causes the
trigger date to be the last day of the month.  However, because of the
\fBOMIT\fR clause, if the first of the month falls on a Sunday or Monday,
the trigger date is moved backwards past the weekend to Friday.  (If you
have globally omitted holidays, the reminder will be moved back past them,
also.  See "The OMIT command" for more details.)
.PP
By comparison, if we had used "\-\-1", the reminder would be triggered on
the last day of the month, regardless of the \fBOMIT\fR.
.PP
If you locally omit weekdays but also have globally-omitted weekdays, then
the list of omitted weekdays is the union of the two.  Consider this
example:
.PP
.nf
        OMIT Sat Sun
        REM 15 OMIT Fri Sat MSG Whatever
.fi
.PP
In the REM command, the effective list of omitted weekdays will
be Friday, Saturday and Sunday.
.PP
.B COMPUTED LOCAL OMITS
.PP
The \fBOMITFUNC\fR phrase of the \fBREM\fR command allows you to
supply a function that determines whether or not a date is omitted.
Note that \fBOMITFUNC\fR must be given just the name of a user-defined
function; it can't take an arbitrary expression or the name of a built-in
function.
.PP
The function is passed a single parameter of type \fBDATE\fR, and must
return a non-zero integer if the date is considered "omitted" and 0
otherwise.  Here's an example:
.PP
.nf
        FSET _third(x) (day(x) % 3) || \\
                       (wkdaynum(x) == 0) || \\
                       (wkdaynum(x) == 6)
        REM OMITFUNC _third AFTER MSG Working day divisible by 3
.fi
.PP
In the example above, the reminder is triggered every Monday to Friday whose
day-of-month number is divisible by three.  Here's how it works:
.TP
.B o
The \fBOMITFUNC _third\fR portion causes all days for which \fB_third(x)\fR
returns non-zero to be considered "omitted".  This causes all days whose
day-of-month number is \fInot\fR a multiple of three to be omitted.  Note
that _third also returns non-zero if the weekday is Sunday or Saturday.
.TP
.B o
The \fBAFTER\fR keyword causes the reminder to be moved after a block of
omitted days.
.PP
The combination of OMITFUNC and AFTER keyword causes the reminder to
be issued on all days whose day-of-month number is divisible by three,
but not on Saturday or Sunday.
.PP
Note that if you use \fBOMITFUNC\fR, then a local \fBOMIT\fR is
\fIignored\fR as are \fIall global OMITs\fR.  If you want to omit specific
weekdays, your omit function will need to test for them specifically.  If
you want to take into account the global \fBOMIT\fR context, then your omit
function will need to test for that explicitly (using the \fBisomitted()\fR
function.)
.PP
Note that an incorrect \fBOMITFUNC\fR might cause all days to be considered
omitted.  For that reason, when \fBRemind\fR searches through omitted days,
it terminates the search after the \fBSATISFY\fR iteration limit
(command-line option \fB\-x\fR.)
.PP
.B ADDING TRIGGER DATES TO THE OMIT CONTEXT
.PP
If the \fBADDOMIT\fR keyword appears in a \fBREM\fR command, then
the trigger date (if one could be calculated) is automatically
added to the list of global OMITs.
.PP
The command:
.PP
.nf
        REM ... whatever ... ADDOMIT MSG Foo
.fi
.PP
is identical in behavior to the sequence:
.PP
.nf
        REM ... whatever ... SATISFY 1
        IF trigvalid()
            OMIT [trigdate()] MSG Foo
        ENDIF
.fi
.PP
.B TIMED REMINDERS
.PP
Timed reminders are those that have an \fBAT\fR keyword followed
by a \fItime\fR and optional \fItdelta\fR and \fItrepeat\fR.  The \fItime\fR
may be specified in 24-hour format, with 0:00 representing midnight,
12:00 representing noon, and 23:59 representing one minute to midnight.
Alternatively, it may be specified in common "AM/PM" format; in this case,
the hour must range from 1 to 12.  12:00am represents midnight, 12:00pm
represents noon, and 11:59pm represents one minute to midnight.  The "am"
and "pm" portions are case-insensitive and the "m" is optional.
.PP
You can use either a colon or a period to separate the hours from the
minutes.  That is, 13:39 and 13.39 are equivalent.
.PP
\fBRemind\fR treats timed reminders specially.  If the trigger date
for a timed reminder is the same as the current system date, the
reminder is queued for later activation.  When \fBRemind\fR has
finished processing the reminder file, it puts itself in the
background, and activates timed reminders when the system time reaches
the specified time.  Note that if you use the \fBNOQUEUE\fR modifier
in the \fBREM\fR command, then this queuing and background activation
is \fInot\fR performed.  \fBNOQUEUE\fR is useful if you want a time
to be associated with a reminder (e.g., in the calendar) but are not
interested in a popup reminder happening at the specified time.

.PP
If the trigger date is \fInot\fR the same as the system date, the reminder
is not queued.
.PP
For example, the following reminder, triggered every working day,
will emit a message telling you to
leave at 5:00pm:
.PP
.nf
	REM Mon Tue Wed Thu Fri AT 17:00 MSG Time to leave!
.fi
.PP
The following reminder will be triggered on Thursdays and Fridays,
but will only be queued on Fridays:
.PP
.nf
	REM Fri ++1 AT 1:00PM MSG Lunch at 1pm Friday.
.fi
.PP
The \fItdelta\fR and \fItrepeat\fR have the same form as a \fIrepeat\fR
and \fIdelta\fR, but are specified in minutes.  For example, this reminder
will be triggered at 12:00pm as well as 45 minutes before:
.PP
.nf
	REM AT 12:00 +45 MSG Example
.fi
.PP
The following will be issued starting at 10:45, every half hour until 11:45,
and again at noon.
.PP
.nf
	REM AT 12:00 +75 *30 MSG Example2
.fi
.PP
The "+75" means that the reminder is issued starting 75 minutes before noon;
in other words, at 10:45.  The *30 specifies that the reminder is subsequently
to be issued every 30 minutes.  Note that the reminder is always issued at
the specified time, even if the \fItdelta\fR is not a multiple of the
\fItrepeat\fR.  So the above example is issued at 10:45am, 11:15am, 11:45am,
and 12:00pm.  Note that in the time specification, there is no distinction
between the "+" and "++" forms of \fItdelta\fR.
.PP
Normally, \fBRemind\fR will issue timed reminders as it processes the reminder
script, as well as queuing them for later.  If you do not want \fBRemind\fR to
issue the reminders when processing the script, but only to queue them
for later, use the \fB\-a\fR command-line option.  If you do not want
reminders to be queued for later, use the \fB\-q\fR command-line
option.
.PP
Normally, \fBRemind\fR forks a background process to handle queued reminders.
If you want \fBRemind\fR to remain in the foreground, use the \fB\-f\fR
command-line option.  This is useful, for example, in .xinitrc
scripts, where you can use the command:
.PP
.nf
	remind \-fa myreminders &
.fi
.PP
This ensures that when you exit X-Windows, the \fBRemind\fR process is killed.
.PP
.B WARNING ABOUT TIMED REMINDERS
.PP
Note:  If you use user-defined functions or variables (described later)
in the bodies of timed reminders, then when the timed reminders are
activated, the variables and functions have the definitions that were
in effect at the end of the reminder script.  These definitions may
\fInot\fR necessarily be those that were in effect at the time the reminder
was queued.  In addition, the OMIT context is whatever was in effect at
the end of the reminder script, which may not necessarily be the same
as when the \fBREM\fR command was first processed.
.PP
.B THE SCHED AND WARN KEYWORDS
.PP
The \fBSCHED\fR keyword allows more precise control over the triggering
of timed reminders, and the \fBWARN\fR keyword allows precise control
over the advance triggering of all types of reminders.
However, discussion must be deferred until after
expressions and user-defined functions are explained.  See the subsection
"PRECISE SCHEDULING" further on.
.PP
.B TAG, INFO AND DURATION
.PP
The \fBTAG\fR keyword lets you "tag" certain reminders.  This facility
is used by certain back-ends or systems built around \fBRemind\fR,
such as \fBTkRemind\fR.  These back-ends have specific rules about
tags; see their documentation for details.
.PP
The \fBTAG\fR keyword is followed by a tag consisting of up to
48 characters.  You can have as many TAG clauses as you like in
a given REM statement.  A tag can contain any character except for
whitespace and a comma.
.PP
If you supply the \fB\-y\fR option to \fBRemind\fR, then any
reminder that lacks a \fBTAG\fR will have one synthesized.  The
synthesized tag consists of the characters "__syn__" followed
by the hexadecimal representation of the MD5 sum of the REM
command line.  This lets you give a more-or-less unique identifier
to each distinct REM command.
.PP
The \fBINFO\fR keyword is similar to \fBTAG\fR but is intended to convey
metadata about an event, such as its location.  Back-ends will have their
own rules about which \fIinfo_string\fRs they recognize, and must ignore
\fIinfo_string\fRs they don't recognize. Note that \fBINFO\fR must
be followed by a quoted string; you can include newlines in the string
by supplying them as "\\n".
.PP
An INFO string \fImust\fR be of the form "Header: Value".  The header
can consist of any printable character, but cannot contain whitespace.
The value can consist of any characters you like.  Space may not
appear before the colon, but can appear afterwards; such space is not
considered to be part of the value.  If there is more than one INFO
string for a given reminder, there cannot be any duplicate headers.
Case is ignored when determining if a header is a duplicate of an
existing one.
.PP
For example, a hypothetical back-end might let you set the location
and description of a reminder like this:
.PP
.nf
        REM 26 Feb 2025 INFO "Location: Boardroom #2" \\
                        INFO "Description: Go over latest pull requests" \\
                        MSG Engineering meeting
.fi
.PP
While back-ends can choose which INFO strings to support, all back-ends
should endeavor to support three standard ones: \fBLocation:\fR,
\fBDescription:\fR and \fBUrl:\fR.  TkRemind supports all three of these,
turning reminders with a \fBUrl:\fR INFO string into hyper-links, and
popping up information windows for the \fBLocation:\fR and \fBDescription:\fR
INFO strings.  \fBLocation:\fR and \fBUrl:\fR are self-explanatory;
\fBDescription:\fR is meant for a longer, more in-depth description
of the reminder than the summary that is normally displayed.
.PP
The \fBDURATION\fR keyword makes sense only for timed reminders; it
specifies the duration of an event.  For example, if you have a
90-minute meeting starting at 1:00pm, you could use any of the following:
.PP
.nf
        REM 5 March 2021 AT 13:00 DURATION 1:30 MSG Meeting
        REM 5 March 2021 AT 13:00 DURATION 90 MSG Meeting
        REM 5 March 2021 AT 1:00pm DURATION 1:30 MSG Meeting
        REM 5 March 2021 AT 1:00pm DURATION 90 MSG Meeting
.fi
.PP
For long-duration reminders, it is convenient to use expressions
to simplify writing the DURATION.  For example, if you are away
from 20 Feb 2023 through 23 Feb 2023 (a total of 4 days) you
could write:
.PP
.nf
        REM 20 Feb AT 00:00 DURATION [4*24]:00 MSG away
        REM 20 Feb AT 00:00 DURATION [4*24*60] MSG away
.fi
.PP
Note that \fIduration\fR is specified either as
\fIhours\fR:\fIminutes\fR or just as \fIminutes\fR specified as an
\fIinteger\fR.
.PP
If you specify a duration of 00:00 or 0, then \fBRemind\fR behaves
exactly as if no \fBDURATION\fR at all had been present.  Although
durations specified as \fIhours\fR:\fIminutes\fR look superficially like a
time-of-day, they are not; the \fIhours\fR component is not limited
to the range 00-23.

.PP
.SH SYNTACTIC SUGAR FOR REM
.PP
The REM command has syntactic sugar to let you express common
reminders.  The following pairs of reminders are equivalent:
.PP
.nf
        REM First Monday April MSG Foo
        REM Mon 1 April        MSG Foo

        REM Second Monday May  MSG Bar
        REM Mon 8 May          MSG Bar

        REM Third Monday MSG Third Monday of every month
        REM Mon 15 MSG Third Monday of every month

        REM Fourth Sunday June 2025 MSG Fourth Sunday in June 2025
        REM Sun 22 June 2025 MSG Fourth Sunday in June 2025

        REM Last Monday MSG Last Monday of every month
        REM Mon 1 --7 MSG Last Monday of every month

        REM Last Monday April MSG Last Monday of every April
        REM Mon 1 May --7 MSG  Last Monday of every April

        REM Last Monday December 2025 MSG Last Monday of Dec 2025
        REM Monday 1 Jan 2026 --7 MSG Last Monday of Dec 2025
.fi
.PP
Note that \fBLast\fR effectively adjusts the month and year, if necessary, to
make the reminder trigger on the correct date.
.PP
The keyword \fBIN\fR is completely ignored, so you can write (for example):
.PP
.nf
        REM Second Monday in May MSG foo
        REM Last Monday in December 2025 MSG Bar
.fi
.PP
An alternate form of \fIback\fR makes writing reminders easier.
The following groups of reminders are equivalent:
.PP
.nf
        REM ~~1 MSG Last day of every month
        REM Lastday MSG  Last day of every month
        REM 1 --1 MSG Last day of every month

        REM May ~~1 MSG Last day of May
        REM Lastday May MSG Last day of May
        REM 1 June --1 MSG Last day of May

        REM Dec 2025 ~~1 MSG Last day of December 2025
        REM Lastday Dec 2025 MSG Last day of December 2025
        REM 1 Jan 2026 --1 MSG Last day of December 2025

        REM Apr ~1 OMIT SAT SUN MSG Last workday of April
        REM Lastworkday April OMIT SAT SUN MSG Last workday of April
        REM 1 May -1 OMIT SAT SUN MSG Last workday of April

        REM Apr ~~7 MSG Seventh-last day of April
        REM 1 May --7 MSG Seventh-last day of April

        REM Apr ~2 OMIT SAT SUN MSG Second-last workday of April
        REM 1 May -2 OMIT SAT SUN MSG Second-last workday of April
.fi
.PP
As we see, "Lastday" is equivalent to ~~1 and "Lastworkday" to ~1.
.PP
Note that the First/Second/Third/Fourth/Last keywords and the ~ and ~~ form
of \fIback\fR imply a value for the day of the month; as such, they cannot
be combined with a day.  Additionally, First/Second/Third/Fourth/Last
must have at least one weekday name.  The following are illegal:
.PP
.nf
        REM First Monday 3 June MSG Huh?
        REM April 3 ~~1 MSG What?
        REM Second June MSG Where's the weekday???
.fi
.PP
.SH THE SUBSTITUTION FILTER
.PP
Before being processed, the body of a
.B REM
command is passed through a substitution filter.  The filter scans for
sequences "%x" (where "x" is any letter and certain other characters)
and performs substitutions as
shown below.  (All dates refer to the trigger date of the reminder.)
.TP
.B %a
is replaced with "on \fIweekday, day month, year\fR"
.RS
For example, consider the reminder:
.PP
REM 18 Oct 1990 +4 MSG Meeting with Bob %a.
.PP
On 16 October 1990, it would print "Meeting with Bob on Thursday, 18 October,
1990."
.PP
On 17 October 1990, it would print "Meeting with Bob tomorrow."
.PP
On 18 October 1990, it would print "Meeting with Bob today."
.RE
.TP
.B %b
is replaced with "in \fIdiff\fR day's time" where
.I diff
is the
.B actual
number of days between the current date and the trigger date.
(\fBOMITs\fR have no effect.)
.RS
For example, consider:
.PP
REM 18 Oct 1990 +4 MSG Meeting with Bob %b.
.PP
On 16 October 1990, it would print "Meeting with Bob in 2 days' time."
.PP
On 17 October 1990, it would print "Meeting with Bob tomorrow."
.PP
On 18 October 1990, it would print "Meeting with Bob today."
.RE
.TP
.B %c
is replaced with "on \fIweekday\fR"
.RS
Example: REM 18 Oct 1990 +4 MSG Meeting with Bob %c.
.PP
On 16 October 1990, it would print "Meeting with Bob on Thursday."
.PP
On 17 October 1990, it would print "Meeting with Bob tomorrow."
.PP
On 18 October 1990, it would print "Meeting with Bob today."
.RE
.TP
.B %d
is replaced with "\fIday\fR", the day of the month.
.TP
.B %e
is replaced with "on \fIdd-mm-yyyy\fR"
.TP
.B %f
is replaced with "on \fImm-dd-yyyy\fR"
.TP
.B %g
is replaced with "on \fIweekday, day month\fR"
.TP
.B %h
is replaced with "on \fIdd-mm\fR"
.TP
.B %i
is replaced with "on \fImm-dd\fR"
.TP
.B %j
is replaced with "on \fIweekday, month day-th, year\fR"  This form appends the
characters "st", "nd", "rd" or "th" to the day of the month, as appropriate.
.TP
.B %k
is replaced with "on \fIweekday, month day-th\fR"
.TP
.B %l
is replaced with "on \fIyyyy-mm-dd\fR"
.TP
.B %m
is replaced with "\fImonth\fR", the name of the month.
.TP
.B %n
is replaced with the number (1 to 12) of the month.
.TP
.B %o
is replaced with " (today)" if and only if the current system date is the same
as the date being used by
.B Remind
as the current date.  Recall that you can specify a date for
.B Remind
to use on the command line.  This substitution is not generally useful in a
.B REM
command, but is useful in a
.B BANNER
command.  (See "The BANNER Command.")
.TP
.B %p
is replaced with "s" if the
.I diff
between the current date and the trigger date is not 1.  You can use this
to construct reminders like:
.RS
REM 1 Jan +4 MSG %x day%p to go before New Year!
.RE
.TP
.B %q
is replaced with "'s" if the
.I diff
between the trigger date and the current date is 1.  Otherwise, it is replaced
with "s'"  This can be used as follows:
.RS
REM 1 Jan +4 MSG New Year in %x day%q time!
.RE
.TP
.B %r
is replaced with the day of the month (01 to 31) padded with a leading zero
if needed to pad to two digits.
.TP
.B %s
is replaced with "st", "nd", "rd" or "th" depending on the day of the month.
.TP
.B %t
is replaced with the number of the month (01 to 12) padded to two digits
with a leading zero.
.TP
.B %u
is replaced with "on \fIweekday, day-th month, year\fR"  This is similar
to
.B %a
except that "st", "nd", "rd" or "th" is added to the
.I day
as appropriate.
.TP
.B %v
is replaced with "on \fIweekday, day-th month\fR"
.TP
.B %w
is replaced with "\fIweekday\fR", the name of the day of the week.
.TP
.B %x
is replaced with the
.I diff
between the current date and the trigger date.  The
.I diff
is defined as the actual number of days between these two dates;
.B OMITs
are not counted.  (Strict date subtraction is performed.)
.TP
.B %y
is replaced with "\fIyear\fR", the year of the trigger date.
.TP
.B %z
is replaced with "\fIyy\fR", the last two digits of the year.
.TP
.B %(\fIany_text\fR\fB)
is replaced with the lookup of \fIany_text\fR in the translation table.
It is the equivalent of [_("any_text")] but is more convenient to type.
.TP
.B %<\fIany_text\fR\fB>
is replaced with the INFO value associated with the header \fIany_text\fR
or the empty string if no such INFO value exists.  It is the
equivalent of [triginfo("any_text")] but is more convenient to type.
.TP
.B %_
(percent-underscore) is replaced with a newline.  You can use this to
achieve multi-line reminders.  Note that calendar back-ends vary in
how they handle multi-line reminders:
.RS
.TP
.B o
Running \fBremind -c\fR preserves newlines in the terminal calendar output.
.TP
.B o
\fBrem2pdf\fR preserves newlines if \fBremind\fR is invoked with the \fB\-pp\fR
or \fB\-ppp\fR option.
.TP
.B o
\fBrem2html\fR preserves newlines if \fBremind\fR is invoked with the
\fB\-pp\fR option.
.TP
.B o
\fBtkremind\fR preserves newlines.\fR
.TP
.B o
\fBrem2ps\fR converts newlines to spaces.  But \fBrem2ps\fR is deprecated;
use \fBrem2pdf\fR instead.
.TP
.B o
The "simple calendar" formats (i.e., \fBremind\fR's \fB\-s\fR, \fB\-n\fR and
\fB\-p\fR options) convert newlines to spaces.
.PP
All calendar back-ends collapse multiple spaces to a single space and
multiple newlines to a single newline.
.RE
.TP
.B %1
is replaced with "now", "\fIm\fR minutes from now", "\fIm\fR minutes ago",
"\fIh\fR hours from now", "\fIh\fR hours ago", "\fIh\fR hours and \fIm\fR
minutes from now" or "\fIh\fR hours and \fIm\fR minutes ago", as appropriate
for a timed reminder.  Note that unless you specify the \fB\-a\fR option,
timed reminders will be triggered like normal reminders, and thus a timed
reminder that occurred earlier in the day may be triggered.  This
causes the need for the "...ago" forms.
.TP
.B %2
is replaced with "at \fIhh\fR:\fImm\fRam" or "..pm" depending on the
.B AT
time of the reminder.
.TP
.B %3
is replaced with "at \fIhh\fR:\fImm\fR" in 24-hour format.
.TP
.B %4
is replaced with "\fImm\fR" where \fImm\fR is the number of minutes between
"now" and the time specified by \fBAT\fR.  If the \fBAT\fR time is
earlier than the current time, then the result is negative.
.TP
.B %5
is replaced with "\fIma\fR" where \fIma\fR is the absolute value of the number
produced by \fB%4\fR.
.TP
.B %6
is replaced with "ago" or "from now", depending on the relationship between
the \fBAT\fR time and the current time.
.TP
.B %7
is replaced with the number of hours between the \fBAT\fR time and the
current time.  It is always non-negative.
.TP
.B %8
is replaced with the number of minutes between the \fBAT\fR time and
the current time, after the hours (\fB%7\fR) have been subtracted out.
This is a number ranging from 0 to 59.
.TP
.B %9
is replaced with "s" if the value produced by \fB%8\fR is not 1.
.TP
.B %0
is replaced with "s" if the value produced by \fB%7\fR is not 1.
.TP
.B %!
is replaced with "is" if the current date and time is before the
trigger date and the \fBAT\fR time, or "was" if it is after.  The \fB%!\fR
sequence may be used in a non-timed reminder, in which case only dates
are compared.
.TP
.B %?
is replaced with "are" if the current date and time is before the
trigger date and the \fBAT\fR time, or "were" if it is after.  The \fB%?\fR
sequence may be used in a non-timed reminder, in which case only dates
are compared.
.TP
.B %@
is similar to \fB%2\fR but displays the current time.
.TP
.B %#
is similar to \fB%3\fR but displays the current time.
.TP
.B %:
is replaced with " (done)" for a TODO reminder whose trigger date
is on or after its COMPLETE-THROUGH date.  It is replaced with the empty
string in any other situation.  Note that because \fBRemind\fR does not
display completed TODO reminders in Agenda Mode, this escape sequence
is really only useful in Calendar Mode.
.TP
.B
%"
.\" "
(percent-doublequote) is removed.  This sequence is not
used by the substitution filter,
but is used to tell \fBRemind\fR which text to include in a calendar
entry when the \fB\-c\fR, \fB\-s\fR or \fB\-p\fR option is chosen.
See "CALENDAR MODE"
.PP
Notes:
.TP
o
.B Remind
normally prints a blank line after each reminder; if the last character
of the body is "%", the blank line will not be printed.  You can globally
suppress the extra blank lines by setting \fB$AddBlankLines\fR to 0.
.TP
o
Substitutions a, b, c, e, f, g, h, i, j, k, l, u and v all are replaced
with "today" if the current date equals the trigger date, or "tomorrow"
if the trigger date is one day after the current date.  Thus, they are
.B not
the same as substitutions built up from the simpler %w, %y, etc.
sequences.
.TP
o
The a, c, e, f, g, h, i, j, k, l, u, v, 2, and 3 substitutions may
be preceded by an asterisk (for example, \fB%*c\fR) which causes the word
"at" or "on" that would normally be included in the output to be
omitted.
.TP
o
The ! and ? substitutions may be preceded by an asterisk (\fB%*!\fR or \fB%*?\fR),
in which case the comparison is made between the trigger date and
realtoday() instead of today().
.TP
o
Any of the substitutions dealing with time (0 through 9) produce
undefined results if used in a reminder that does not have an \fBAT\fR
keyword.  Also, if a reminder has a \fIdelta\fR and may be triggered
on several days, the time substitutions ignore the date.  Thus, the
\fB%1\fR substitution may report that a meeting is in 15 minutes, for
example, even though it may only be in 2 days time, because a
\fIdelta\fR has triggered the reminder.  It is recommended that you
use the time substitutions only in timed reminders with no \fIdelta\fR
that are designed to be queued for timed activation.
.TP
o
Capital letters can be used in the substitution sequence, in which case
the first character of the substituted string is capitalized (if it is
normally a lower-case letter.)
.TP
o
All other characters following a "%" sign are simply copied.  In particular,
to get a "%" sign out, use "%%" in the body.  To start the body of a reminder
with a space, use "% ", since
.B Remind
normally scans for the first non-space character after a
.B MSG,
.B CAL
or
.B RUN
token.
.PP
.SH EVENTS AND TODOS
.PP
The \fBREM\fR command is normally used to create an \fIEVENT\fR.  This
is something that happens at a certain time, possibly recurring, and
happens no matter what action you take.  Events include things like
birthdays, holidays, meetings, etc... pretty much everything that occurs
on a particular schedule.  Once the date of an event has passed,
\fBRemind\fR will no longer remind you about the event.
.PP
A \fITODO\fR is different; it is a task that you have to complete by a
specific date or date and time.  If you don't explicitly mark a TODO
as done, \fBRemind\fR will keep reminding you about it \fIeven past
the due date.\fR.
.PP
To mark a \fBREM\fR as a TODO, simply include the TODO keyword.  For example:
.PP
.nf
    REM TODO 15 August 2025 ++5 MSG Buy cat food %b.
.fi
.PP
In Agenda Mode, \fBRemind\fR will start warning you on 10 Aug 2025 that
you have to but cat food in 5 days' time, 4 days' time, etc...
.PP
However, on 16 Aug 2025, \fBRemind\fR will say "Buy cat food yesterday."
and it will keep reminding you of your need to buy cat food until the end
of time, or until you mark the TODO as done.
.PP
.SH MARKING TODOS AS DONE
.PP
There are two ways to mark a TODO as done.  If the TODO is not recurring,
the simplest way is simply to remove the TODO designator from the REM
command (or indeed, to completely delete it.)  The former keeps the
reminder on the calendar while the latter completely removes it.
.PP
If a TODO is recurring, use the \fBCOMPLETE-THROUGH\fR clause to mark
which recurrences have been completed.  For example:
.PP
.nf
    REM TODO 30 April ++15 COMPLETE-THROUGH 2025-04-30 MSG File taxes
.fi
.PP
Canadian income taxes must be filed every 30 April.  The above command
will remind you to pay taxes in 2026.  If you don't update the
COMPLETE-THROUGH date, then after 30 April 2026, \fBRemind\fR will
keep reminding you until the end of time that your taxes were due on 30
April 2026.  To indicate that you've paid them, simply update the
COMPLETE-THROUGH date to 2026-04-30 and then \fBRemind\fR will start
reminding you of your 2027 taxes (starting 15 days before the due
date.)
.PP
It is an error to specify COMPLETE-THROUGH without also specifying TODO.
The keyword COMPLETED-THROUGH may be used as a synonym for COMPLETE-THROUGH.
.PP
.SH LIMITING REMINDERS ABOUT OVERDUE TODOS
.PP
Although \fBRemind\fR is happy to keep reminding you about overdue
TODOs for hundreds of years, for some things this may be pointless.
If you want \fBRemind\fR to \fIstop\fR nagging you about an overdue
TODO after a certain number of days, use the MAX-OVERDUE \fIn\fR clause.
In this case, \fBRemind\fR stops reminding you of a TODO that is overdue
by more than \fIn\fR days.  Here is an example.
.PP
.nf
    REM TODO 2025-08-13 ++5 MAX-OVERDUE 5 MSG Task: %b.
.fi
.PP
\fBRemind\fR \fIstarts\fR reminding you of the task on 2025-08-08,
because of the ++5 back value.  It keeps reminding you of the task
after the due date.  However, the last time it will remind you
will be on 2025-08-18, because of the MAX-OVERDUE clause.  Starting
on 2025-08-19, \fBRemind\fR will no longer remind you of the task
since it's probably pointless---it has passed the MAX-OVERDUE period.
.PP
.SH MORE DETAILS ABOUT TODOS
.PP
TODOs are treated specially only in Agenda Mode.  In Calendar Mode,
they appear in the calendar exactly as a normal event would.
.PP
TODOs are implemented internally by using the COMPLETE-THROUGH date
plus one day as the starting point for \fBRemind\fR's date-scanning
algorithm.  If you have a recurring TODO without a COMPLETE-THROUGH
clause, then \fBRemind\fR starts scanning from the beginning of time,
which we all know is 1 January 1990.  Consider this command:
.PP
.nf
    REM TODO Wed +7 MSG Take out the trash %a (%b)
.fi
.PP
Running that command in Agenda Mode on 2025-08-13 yields the following output:
.PP
.nf
    Take out the trash on Wednesday, 3 January, 1990 (13006 days ago)
.fi
.PP
\fBRemind\fR is very persistent about reminding you of tasks!  If you take
out the trash and mark it done:
.PP
.nf
    REM TODO Wed +7 COMPLETE-THROUGH 2025-08-13 MSG Take out the trash %a (%b)
.fi
.PP
then you get this:
.PP
.nf
    Take out the trash on Wednesday, 20 August, 2025 (in 7 days' time)
.fi
.PP
You can use \fBFROM\fR and \fBUNTIL\fR to limit the recurrence interval of
tasks just as you can with events.  For example, if you are house-sitting
for the month of August and need to water plants every Wednesday:
.PP
.nf
    REM TODO Wed +7 FROM 2025-08-06 UNTIL 2025-08-27 MSG Plants %b.
.fi
.PP
Running that command on 13 Aug yields: "Plants 7 days ago." because you
have not told \fBRemind\fR that you completed the first watering.  If you finish
your duties and add a COMPLETE-THROUGH date of 2025-08-27, then \fBRemind\fR
never reminds you of that task in the future.
.PP
In Purge Mode, \fBRemind\fR will not purge TODOs unless they have been marked
as complete.  In the case of a recurring TODO, \fBRemind\fR will not purge
it until the last occurrence is marked as complete.
.PP
.SH THE OMIT COMMAND
.PP
In addition to being a keyword in the \fBREM\fR command,
\fBOMIT\fR is a command in its own right.  Its syntax is:
.PP
.RS
\fBOMIT\fR \fIweekday\fR [\fIweekday\fR...]
.PP
or:
.PP
\fBOMIT\fR [\fIday\fR] \fImonth\fR [\fIyear\fR]
.PP
or:
.PP
\fBOMIT\fR [\fIday1\fR] \fImonth1\fR [\fIyear1\fR] \fBTHROUGH\fR [\fIday2\fR] \fImonth2\fR [\fIyear2\fR]
.RE
.PP
The \fBOMIT\fR command is used to "globally" omit certain days
(usually holidays).  These globally-omitted days are skipped by the
"\-" and "+" forms of \fIback\fR and \fIdelta\fR, but not by the
"\-\-" and "++" forms.  Some examples:
.PP
.nf
    OMIT Saturday Sunday
    OMIT 1 Jan
    OMIT 7 Sep 1992
    OMIT 15 Jan THROUGH 14 Feb
    OMIT May     # Equivalent to OMIT May 1 THROUGH May 31
    OMIT 25 Dec THROUGH 4 Jan
    OMIT 2023-05-03 THROUGH 2023-05-12
    OMIT Jun THROUGH July  # Equivalent to OMIT Jun 1 THROUGH July 31
.fi
.PP
The first example omits every Saturday and Sunday.  This is useful for
reminders that shouldn't trigger on weekends.
.PP
The second example specifies a holiday that occurs on the same date each
year - New Year's Day.
.PP
The third example specifies a holiday that
changes each year - Labour Day.  For these types of holidays, you
must create an \fBOMIT\fR command for each year.  (Later, in the
description of expressions and some of the more advanced features of
\fBRemind\fR, you will see how to automate this for some cases.)
.PP
As with the REM command, you can use shorthand specifiers for dates;
the following are equivalent:
.PP
.nf
	OMIT 7 Sep 1992
	OMIT 1992-09-07
.fi
.PP
For convenience, you can use a \fIdelta\fR and \fBMSG\fR or \fBRUN\fR
keyword in the \fBOMIT\fR command.  The following sequences are
equivalent:
.PP
.nf
	OMIT 1 Jan
	REM 1 Jan +4 MSG New year's day is %b!

	and

	OMIT 1 Jan +4 MSG New year's day is %b!
.fi
.PP
The \fBTHROUGH\fR keyword lets you conveniently OMIT a range of days.
For example, the following sequences are equivalent:
.PP
.nf
	OMIT 3 Jan 2011
	OMIT 4 Jan 2011
	OMIT 5 Jan 2011

	and

	OMIT 3 Jan 2011 THROUGH 5 Jan 2011
.fi
.PP
Note that \fBRemind\fR has a compiled-in limit to the number of full
OMITs.  If you omit a range of \fIN\fR fully-specified (i.e., year
included) days, then \fIN\fR full OMITs are used up.  Trying to omit a
very large range may result in the error "Too many full OMITs"
.PP
You can make a THROUGH \fBOMIT\fR do double-duty as a \fBREM\fR command as
long as both dates are fully specified
.PP
.nf
	OMIT 6 Sep 2010 THROUGH 10 Sep 2010 MSG Vacation
.fi
.PP
If you use a THROUGH clause, then either the year must be supplied before
and after the THROUGH, or it must be missing before and after the THROUGH.
The following are legal:
.PP
.nf
    OMIT 25 Dec THROUGH 6 Jan
    OMIT 25 Dec 2024 THROUGH 6 Jan 2025
.fi
.PP
But the following are not:
.PP
.nf
    OMIT 25 Dec THROUGH 6 Jan 2025
    OMIT 25 Dec 2024 THROUGH 6 Jan
.nf
.PP
You can debug your global OMITs with the following command:
.PP
.nf
	OMIT DUMP
.fi
.PP
The OMIT DUMP command prints the current global omits to standard output.
.PP
.B THE BEFORE, AFTER AND SKIP KEYWORDS
.PP
Normally, days that are omitted, whether by a global \fBOMIT\fR
command or the local \fBOMIT\fR or \fBOMITFUNC\fR keywords in a
\fBREM\fR statement, only affect the counting of the \-\fIback\fR or
the +\fIdelta\fR.  For example, suppose you have a meeting every
Wednesday.  Suppose, too, that you have indicated 11 Nov as a holiday:
.PP
.nf
	OMIT 11 Nov +4 MSG Remembrance Day
	REM Wed +1 MSG Code meeting %b.
.fi
.PP
The above sequence will issue a reminder about a meeting for 11 November 1992,
which is a Wednesday.  This is probably incorrect.  There are three
options:
.TP
.B BEFORE
This keyword moves the reminder to before any omitted days.  Thus, in
the above example, use of \fBBEFORE\fR would cause the meeting reminder
to be triggered on Tuesday, 10 November 1992.
.TP
.B AFTER
This keyword moves the reminder to after any omitted days.  In the above
example, the meeting reminder would be triggered on Thursday, 12 November
1992.
.TP
.B SKIP
This keyword causes the reminder to be skipped completely on any omitted
days.  Thus, in the above example, the reminder would not be triggered
on 11 November 1992.  However, it would be triggered as usual on the following
Wednesday, 18 November 1992.
.PP
The \fBBEFORE\fR and \fBAFTER\fR keywords move the trigger date of a
reminder to before or after a block of omitted days, respectively.
Suppose you normally run a backup on the first day of the month.  However,
if the first day of the month is a weekend or holiday, you run the backup
on the first working day following the weekend or holiday.  You could use:
.PP
.nf
	REM 1 OMIT Sat Sun AFTER RUN do_backup
.fi
.PP
Let's examine how the trigger date is computed.  The \fB1\fR specifies
the first day of the month.  The local \fBOMIT\fR keyword causes the
\fBAFTER\fR keyword to move the reminder forward past weekends.
Finally, the \fBAFTER\fR keyword will keep moving the reminder forward
until it has passed any holidays specified with global \fBOMIT\fR
commands.
.PP
.SH TIMEZONE SUPPORT
.PP
The \fBREM\fR command supports an optional \fBTZ\fR keyword, which should
be followed by the \fIcase-sensitive\fR time zone name in which the
command is to be interpreted.  Note that if you use the \fBTZ\fR keyword,
then you \fImust also\fR use an \fBAT\fR clause.  Here are some examples:
.PP
.nf
    REM Wednesday AT 14:00 TZ America/Toronto MSG 2PM Eastern (%2).
    REM Wednesday AT 23:59 TZ America/Los_Angeles SATISFY [$Td == 13] MSG Foo %b %2.
.fi
.PP
Within a \fBSATISFY\fR clause and an \fBOMITFUNC\fR function, all
trigger functions and the trigger date are interpreted \fIin the time
zone specified in the \fBREM\fI command\fR.  Outside the \fBREM\fR
command, however, trigger functions are adjusted to the local time
zone.  If the local time zone is UTC and we feed \fBRemind\fR the
following file on 2025-09-04 UTC:
.PP
.nf
    SET $AddBlankLines 0
    BANNER %
    REM Wednesday AT 14:00 TZ America/Toronto MSG 2PM Eastern (%2).
    set a $T
    set b $Tt
    REM MSG a = [a], b = [b]
    REM Wednesday AT 23:59 TZ America/Los_Angeles SATISFY [$Td == 13] MSG Foo %b %2.
    set c $T
    set d $Tt
    REM MSG c = [c], d = [d]
.fi
.PP
Then the output is as follows:
.PP
.nf
    a = 2025-09-10, b = 18:00
    c = 2026-05-14, d = 06:59
.fi
.PP
That is because the trigger date of the first (Wednesday, 2025-09-10
at 14:00 Eastern time) is 2025-09-10 at 18:00 UTC.  In the second case,
Wednesday, 13 May 2026 is the SATISFied trigger date, which is
adjusted to Thursday, 14 May 2026 at 06:59 UTC because of the
time zone adjustment.
.PP
If you use an invalid time zone name after the \fBTZ\fR keyword,
results are undefined.  As mentioned previously, time zone names
\fIare\fR case-sensitive; America/Toronto is valid, but
america/toronto is not.
.PP
If you are on a system that stores time zone data in
/usr/share/zoneinfo, then \fBRemind\fR will attempt to validate the
time zone name and will warn you if it appears to be invalid.  If you
want to specify a time zone that lacks a file under
/usr/share/zoneinfo anyway, and want to suppress the warning, prefix
the time zone name with "!".  For example:
.PP
.nf
    REM Thursday AT 14:45 TZ !EST+5EDT,M3.2.0/2,M11.1.0/2 MSG Old TZ format
.fi
.PP
In a reminder with the \fBTZ\fR keyword, OMIT dates are evaluated in
the specified time zone.  Here's an example: Suppose the local time zone
is America/Toronto and you have this script:
.PP
.nf
    # A Friday
    OMIT 2025-09-05

    # A Saturday
    OMIT 2025-09-13

    REM Saturday AT 01:00 TZ Europe/Amsterdam SKIP MSG Early Sat AM
.fi
.PP
On 2025-09-05 in the America/Toronto time zone, the reminder \fIwill\fR
trigger.  Even though 2025-09-05 has been OMITted, the SKIP keyword
evaluates the date in the Europe/Amsterdam time zone, and 2025-09-06
(the trigger date) is \fInot\fR omitted.
.PP
Conversely, on 2025-09-12 in the America/Toronto time zone, the
reminder will \fInot\fR trigger.  Even though 2025-09-12 is not OMITted,
2025-09-13 is, and that is the trigger date in the Europe/Amsterdam
time zone.
.PP
.SH THE DO, INCLUDE AND SYSINCLUDE COMMANDS
.PP
\fBRemind\fR allows you to include other files in your reminder script,
similar to the C preprocessor #include directive.  For example, you
might organize different reminders into different files like this:
.PP
.nf
        INCLUDE holidays.rem
        INCLUDE birthdays.rem
        INCLUDE "quote files with spaces.rem"
.fi
.PP
\fBINCLUDE\fR files can be nested up to a depth of 8.  As shown above, if a
filename has spaces in it (not recommended!) you can use double-quotes
around the filename.
.PP
If you specify a filename of "-" in the \fBINCLUDE\fR command, \fBRemind\fR
will begin reading from standard input.
.PP
If you specify a \fIdirectory\fR as the argument to \fBINCLUDE\fR,
then \fBRemind\fR will process all files (but not subdirectories!) in
that directory that match the shell pattern "*.rem".  The files are
processed in sorted order; the sort order matches that used by the
shell when it expands "*.rem".
.PP
Note that the file specified by an \fBINCLUDE\fR command is interpreted
relative to the \fIcurrent working directory of the \fBRemind\fR process\fR.
If you want to include a file relative to the directory containing the
currently-processing file, use \fBDO\fR instead.  For example,
if the current file is \fB/home/user/.reminders/foo.rem\fR and Remind's
working directory is \fB/home/user\fR, then:
.PP
.nf
    # Read /home/user/.reminders/bar.rem
    DO bar.rem

    # Read /usr/share/bar.rem - absolute path
    DO /usr/share/bar.rem

    # Read /home/user/bar.rem
    INCLUDE bar.rem

    # Read /usr/share/bar.rem - absolute path
    INCLUDE /usr/share/bar.rem
.fi
.PP
Arguably, the \fBINCLUDE\fR command should have worked the way \fBDO\fR
does right from the start, but changing it would have broken
backward-compatibility, hence the introduction of \fBDO\fR.
.PP
Note that if the currently-processing reminders file was specified as
a symbolic link to a file that is not in the same directory as the
symbolic link itself, \fBDO\fR will fail.  \fBRemind\fR does \fInot\fR
resolve the real path of symbolic links, so you should avoid using
symbolic links to files.
.PP
The \fBSYSINCLUDE\fR command is similar to \fBDO\fR, but it looks for
relative pathnames under the system directory containing standard reminder
scripts.  For this installation of \fBRemind\fR, the system directory is
"@prefix@/share/remind".
.PP
.SH THE RETURN COMMAND
.PP
The \fBRETURN\fR command causes \fBRemind\fR to ignore the remaining
contents of the file currently being processed.  It can be used as a
quick way to "exit" from an included file (though it also works at
the top-level.)
.PP
Here is an example of how \fBRETURN\fR might be used:
.PP
.nf
        IF already_done
            RETURN
        ENDIF
        set already_done 1
        preserve already_done
        # Do expensive processing here
.fi
.PP
.SH THE RUN COMMAND
.PP
If you include other files in your reminder script, you may not always
entirely trust the contents of the other files.  For example, they
may contain \fBRUN\fR-type reminders that could be used to access your
files or perform undesired actions.  The \fBRUN\fR command can restrict
this:  If you include the command \fBRUN OFF\fR in your top-level reminder
script, any reminder or expression that would normally execute a system
command is disabled.  \fBRUN ON\fR will re-enable the execution of
system commands.  Note that the \fBRUN ON\fR command can \fIonly\fR be used
in your top-level reminder script; it will \fInot\fR work in any files
accessed by the \fBINCLUDE\fR command.  This is to protect you from someone
placing a \fBRUN ON\fR command in an included file.  However, the
\fBRUN OFF\fR command can be used at top level or in an included file.
.PP
If you run \fBRemind\fR with the \fB\-r\fR command-line option,
\fBRUN\fR-type reminders and the \fBshell()\fR function will be disabled,
regardless of any \fBRUN\fR commands in the reminder script.  However,
any command supplied with the \fB\-k\fR option will still be executed.
.PP
In addition, \fBRemind\fR contains a few other security
features.  It will not read a file that is group- or world-writable.
It will not run set-uid.  If it reads a file you don't own, it will
disable RUN and the shell() function.  And if it is run as \fIroot\fR,
it will only read files owned by \fIroot\fR.
.PP
Note that if \fBRemind\fR reads standard input, it does \fInot\fR
attempt to check the ownership of standard input, even if it is
coming from a file, and hence does \fInot\fR disable RUN and shell()
in this situation.

.PP
.SH THE EXPR COMMAND
.PP
\fBRemind\fR lets you completely disable expression evaluation.  This
could be useful if you are running \fBRemind\fR on a somewhat-untrustworthy
file that is not expected to contain expressions.  To disable
expression evaluation, use:
.PP
.nf
        EXPR OFF
.fi
.PP
If \fBRemind\fR encounters an expression while EXPR OFF is in effect, it
returns an error
.PP
To re-enable expression evaluation, use:
.PP
.nf
        EXPR ON
.fi
.PP
As with \fBRUN ON\fB, \fBEXPR ON\fR can be used only in the top-level
script, not in an included file.
.PP
.SH THE INCLUDECMD COMMAND
.PP
\fBRemind\fR allows you to execute a shell command and evaluate the
output of that command as if it were an included file.  For example,
you could have scripts that extract reminders out of a database and print
them on stdout as REM commands.  Here is an example:
.PP
.nf
	INCLUDECMD extract_reminders_for dfs
.fi
.PP
We assume that the command "extract_reminders_for" extracts reminders out
of a central database for the named user.  Another use-case of INCLUDECMD
is if you have your reminders stored in a file in some non-Remind format;
you can write a command that transforms them to \fBRemind\fR format and then
\fBRemind\fR can "include" the file with an appropriate INCLUDECMD command.
.PP
Note that if RUN is disabled, then INCLUDECMD will fail with the error
message "RUN disabled"
.PP
\fBRemind\fR arranges so that when the command specified by INCLUDECMD is
executed, its standard input is opened to /dev/null.
.PP
INCLUDECMD passes the rest of the line to \fBpopen\fR(3), meaning that
the command is executed by the shell.  As such, shell meta-characters
may need escaping or arguments quoting, depending on what you're trying
to do.  \fBRemind\fR itself does not perform any modification of the command
line (apart from the normal [expr] expression-pasting mechanism).
.PP
If the command passed to INCLUDECMD begins with an exclamation mark "!",
then \fBRemind\fR disables \fBRUN\fR for the output of the command.  If you are
running a command whose output you don't quite trust, you should
prefix it with "!" so that any RUN commands it emits fail.
.PP
An \fBINCLUDECMD\fR command counts towards the INCLUDE nesting depth.
For any given \fBRemind\fR run, a given INCLUDECMD command is only executed
once and the results are cached.  For example, if you generate a
calendar, each unique INCLUDECMD command is run just once, not once
for each day of the produced calendar.  "Uniqueness" is determined by
looking at the command that will be passed to the shell, so if (for example)
your INCLUDECMD uses expression-pasting that results in differences depending
on the value of \fBtoday()\fR, then each \fIunique\fR version of the
command will be executed once.
.PP
If a given reminder file contains more than one identical
\fBINCLUDECMD\fR, only the first one will actually be executed.  All
subsequent identical ones will use the cached output from the first one.
.PP

.SH THE BANNER COMMAND
.PP
When \fBRemind\fR first issues a reminder, it prints a message like this:
.PP
.nf
	Reminders for Friday, 30th October, 1992 (today):
.fi
.PP
(The banner is not printed if any of the calendar-producing options
is used, or if the \fB\-k\fR option is used.)
.PP
The \fBBANNER\fR command lets you change the format.  It should appear
before any \fBREM\fR commands.  The format is:
.PP
.RS
\fBBANNER\fR \fIformat\fR
.RE
.PP
The \fIformat\fR is similar to the \fIbody\fR of a \fBREM\fR command.  It
is passed through the substitution filter, with an implicit trigger of
the current system date.  Thus, the default banner is equivalent to:
.PP
.nf
	BANNER Reminders for %w, %d%s %m, %y%o:
.fi
.PP
You can disable the banner completely with BANNER %.  Or you can create
a custom banner:
.PP
.nf
	BANNER Hi - here are your reminders for %y-%t-%r:
.fi
.SH CONTROLLING THE OMIT CONTEXT
.PP
Sometimes, it is necessary to temporarily change the global \fBOMITs\fR
that are in force for a few reminders.  Three commands allow you to do
this:
.TP
.B PUSH-OMIT-CONTEXT
This command saves the current global \fBOMITs\fR on an internal stack.
.TP
.B CLEAR-OMIT-CONTEXT
This command clears all of the global \fBOMITs\fR, starting you off with
a "clean slate."
.TP
.B POP-OMIT-CONTEXT
This command restores the global \fBOMITs\fR that were saved by the most
recent \fBPUSH-OMIT-CONTEXT\fR.
.PP
For example, suppose you have a block of reminders that require a clear
\fBOMIT\fR context, and that they also introduce unwanted global \fBOMITs\fR
that could interfere with later reminders.  You could use the following
fragment:
.PP
.nf
	PUSH-OMIT-CONTEXT	# Save the current context
	CLEAR-OMIT-CONTEXT	# Clean the slate
	# Block of reminders goes here
	POP-OMIT-CONTEXT	# Restore the saved omit context
.fi
.SH EXPRESSIONS
.PP
In certain contexts, to be described later, \fBRemind\fR will accept
expressions for evaluation.  \fBRemind\fR expressions resemble C
expressions, but operate on different types of objects.
.PP
.B DATA TYPES
.PP
\fBRemind\fR expressions operate on five types of objects:
.TP
.B INT
The \fBINT\fR data type consists of the integers representable in one machine
word.  The \fBINT\fR data type corresponds to the C "int" type.
.TP
.B STRING
The \fBSTRING\fR data type consists of strings of characters.  It is
somewhat comparable to a C character array, but more closely resembles
the string type in BASIC.
.RS
.PP
\fBRemind\fR normally expects to be running in a UTF-8 environment.
In this environment, there is a difference between \fIbytes\fR and
\fIcharacters\fR since in UTF-8, a character may be represented by
a sequence of more than one byte.  For example, in a UTF-8 environment,
the string "🙂" contains one character but four bytes.  And the string
"één" contains three characters but five bytes.
.PP
\fBRemind\fR has a set of functions
that work on \fIbytes\fR, namely \fBindex\fR, \fBstrlen\fR and \fBsubstr\fR.
These are not safe to use on multi-byte strings; instead use
\fBmbindex\fR, \fBmbstrlen\fR and \fBmbsubstr\fR.  If you know \fIfor sure\fR
that a string contains only single-byte characters, then the byte-oriented
versions may be used and are faster than the multi-byte versions.
.PP
Some ancient or embedded systems may lack the C library functions needed
to deal with multi-byte strings.  In that case, the \fBmb\fIxxx\fR functions
all return an error.
.RE
.TP
.B TIME
The \fBTIME\fR data type is used for two different purposes:  To represent
a time of day with one-minute precision or to represent a duration
with one-minute precision.  The context of where a \fBTIME\fR is used
determines whether it is interpreted as a time of day or a duration.
.RS
.PP
In contexts where a \fBTIME\fR represents a time of day, it may range
from 00:00 to 23:59 and is stored internally as an integer from 0 to
1439 representing the number of minutes since midnight.
.PP
In contexts where a \fBTIME\fR represents a duration, there is no
upper limit on the hour component (beyond that imposed by the
restriction that a duration expressed in minutes must fit into the
signed integer type of your CPU architecture.)  Internally, a duration
is stored as an integer number of minutes.
.RE

.TP
.B DATE
The \fBDATE\fR data type consists of dates (later than 1 January 1990.)
Internally, \fBDATE\fR objects are stored as the number of days since
1 January 1990.
.TP
.B DATETIME
The \fBDATETIME\fR data type consists of a date and time together.
Internally, \fBDATETIME\fR objects are stored as the number of minutes
since midnight, 1 January 1990.  You can think of a \fBDATETIME\fR object
as being the combination of \fBDATE\fR and \fBTIME\fR parts.
.PP
.B CONSTANTS
.PP
The following examples illustrate constants in \fBRemind\fR expressions:
.TP
.B INT constants
12, 36, \-10, 0, 1209, 0x1F, 0xfe00 (the last two demonstrate the use of hexadecimal constants)
.TP
.B STRING constants
"Hello there", "This is a test", "\\nHello\\tThere", ""
.PP
.RS
Note that the empty string is represented by "".  \fBRemind\fR supports
the escape sequences "\\a", "\\b", "\\f", "\\n", "\\r", "\\t"
and "\\v" which have the same meanings as their counterparts in C.
It also supports "\\xAB" where A and B are hexadecimal digits;
this operates just as in C.  The "\\x" must be followed by one or
two hex digits; the escape sequence "\\x00" is not permitted.
.PP
To include a quote in a string, use "\\"".  Any other character
preceded by a backslash is inserted into the string as-is, but the
backslash itself is removed.  To include a backslash in a string,
use "\\\\".
.RE
.TP
.B TIME constants
12:33, 0:01, 14:15, 16:42, 12.16, 13.00, 1.11, 4:30PM, 12:20am
.PP
.RS
Note that \fBTIME\fR constants may be written in 24-hour format or in
common "AM/PM" format.  If you use "AM/PM" format, then the hour can
range from 1 to 12.  Either a period or colon can be used to separate
the minutes from the hours.  However, \fBRemind\fR will consistently output
times in 24-hour format using only one separator character.  (The
output separator character is chosen at compile-time.)
.PP
If the \fBTIME\fR is used where \fBRemind\fR expects a time-of-day
(for example, in an \fBAT\fR clause), then it can be written in
24-hour format (ranging from 00:00 to 23:59) or 12-hour format
(ranging from 12:00am to 11:59pm).  If the \fBTIME\fR is used where
\fBRemind\fR expects a duration, it must not have an \fIam\fR or
\fIpm\fR suffix and the hour can be as large as you want, so long
as the total number of minutes in the duration fits in a signed integer
variable.
.PP
For convenience, a \fBTIME\fR constant may be surrounded by single
quotes to match \fBDATE\fR and \fBDATETIME\fR constants, but these
quotes are optional.  That is, 12:56 and '12:56' represent the same
\fBTIME\fR constant.
.RE
.TP
.B DATE constants
\fBDATE\fR constants are expressed as 'yyyy/mm/dd' or 'yyyy-mm-dd',
and the single
quotes \fImust\fR be supplied.  This distinguishes date constants
from division or subtraction of integers.  Examples:
.PP
.RS
\(aq1993/02/22', '1992-12-25', '1999/01/01'
.PP
Note that \fBDATE\fR values are \fIprinted\fR
without the quotes.  Although either '-' or '/' is accepted as a date
separator on input, when dates are printed, only one will be used.  The
choice of whether to use '-' or '/' is made at compile-time.
Note also that versions
of \fBRemind\fR prior to 03.00.01 did not support date constants.  In those
versions, you must create dates using the \fBdate()\fR function.  Also,
versions prior to 03.00.02 did not support the '-' date separator.
.RE
.TP
.B DATETIME constants
\fBDATETIME\fR constants are expressed similarly to \fBDATE\fR
constants with the addition of an "@HH:MM" part, optionally followed
by "am" or "pm".  For example:
.PP
.RS
\(aq2008-04-05@23:11', '1999/02/03@14:06', '2001-04-07@08:30', '2020-01-01@3:20pm'
.PP
\fBDATETIME\fR values are printed without the quotes.  Notes about date
and time separator characters for \fBDATE\fR and \fBTIME\fR constants apply
also to \fBDATETIME\fR constants.
.RE
.PP
.B ZERO VALUES AND TRUE/FALSE
.PP
All types have an associated \fIzero value\fR, which is treated as
\fIfalse\fR by the IF command, the IIF function, and the logical
operators.  The zero values are:
.PP
.RS
.PP
\fBINT\fR - 0
.PP
\fBDATE\fR - '1990-01-01'
.PP
\fBTIME\fR - 00:00
.PP
\fBDATETIME\fR - '1990-01-01@00:00'
.PP
\fBSTRING\fR - "" (the empty string)
.RE
.PP
Any value other than the \fIzero value\fR is treated as \fItrue\fR.
.PP
.B OPERATORS
.PP
\fBRemind\fR has the following operators.  Operators on the same line
have equal precedence, while operators on lower lines have lower precedence
than those on higher lines.  The operators approximately correspond to
C operators.
.PP
.nf
	!  -            (unary logical negation and arithmetic negation)
	*  /  %         (multiplication, division, modulus)
	+  -            (addition/concatenation, subtraction)
	<  <=  >  >=    (comparisons)
	==  !=          (equality and inequality tests)
	&&              (logical AND)
	||              (logical OR)
.fi
.PP
.B DESCRIPTION OF OPERATORS
.PP
.TP
.B !
Logical negation.  Can be applied to any type.  If the operand
is non-zero, returns 0.  Otherwise, returns 1.
.TP
.B \-
Unary minus.  Can be applied to an \fBINT\fR.  Returns the negative
of the operand.
.TP
.B *
Multiplication.  Returns the product of two \fBINT\fRs.  Alternatively, if
one argument is a \fBSTRING\fR and the other an \fBINT\fR, returns a
\fBSTRING\fR consisting of the INT number of repeats of the original STRING.
In this case, the INT argument cannot be negative.
.TP
.B /
Integer division.  Returns the quotient of two \fBINT\fRs, discarding the
remainder.
.TP
.B %
Modulus.  Returns the remainder upon dividing one \fBINT\fR by another.
.TP
.B +
Has several uses.  These are:
.PP
.RS
\fBINT\fR + \fBINT\fR - returns the sum of two \fBINT\fRs.
.PP
\fBINT\fR + \fBTIME\fR or \fBTIME\fR + \fBINT\fR - returns a \fBTIME\fR
obtained by adding
\fBINT\fR minutes to the original \fBTIME\fR.  The result will always
range from 00:00 through 23:59.
.PP
\fBTIME\fR + \fBTIME\fR treats the second \fBTIME\fR parameter as a
duration, converting it to an integer number of minutes past midnight,
and then performs addition as with \fBTIME\fR + \fBINT\fR.
.PP
\fBINT\fR + \fBDATE\fR or \fBDATE\fR + \fBINT\fR - returns a \fBDATE\fR
obtained by adding \fBINT\fR days to the original \fBDATE\fR.
.PP
\fBINT\fR + \fBDATETIME\fR or \fBDATETIME\fR + \fBINT\fR - returns a
\fBDATETIME\fR obtained by adding \fBINT\fR minutes to the original
\fBDATETIME\fR.
.PP
\fBDATETIME\fR + \fBTIME\fR or \fBTIME\fR + \fBDATETIME\fR
treats the \fBTIME\fR parameter as a
duration, converting it to an integer number of minutes past midnight,
and then performs addition as with \fBDATETIME\fR + \fBINT\fR.
.PP
\fBSTRING\fR + \fBSTRING\fR - returns a \fBSTRING\fR that is the
concatenation of the two original
\fBSTRING\fRs.
.PP
\fBSTRING\fR + anything or anything + \fBSTRING\fR -
converts the non-\fBSTRING\fR
argument to a \fBSTRING\fR, and then performs concatenation.  See
the \fBcoerce()\fR function.
.RE
.TP
.B \-
Has several uses.  These are:
.PP
.RS
\fBINT\fR - \fBINT\fR - returns the difference of two \fBINT\fRs.
.PP
\fBDATE\fR - \fBDATE\fR - returns (as an \fBINT\fR) the difference in days
between two \fBDATE\fRs.
.PP
\fBTIME\fR - \fBTIME\fR - returns (as an \fBINT\fR) the difference in minutes
between two \fBTIME\fRs.
.PP
\fBDATETIME\fR - \fBDATETIME\fR - returns (as an \fBINT\fR) the
difference in minutes between two \fBDATETIME\fRs.
.PP
\fBDATE\fR - \fBINT\fR - returns a \fBDATE\fR that is \fBINT\fR days
earlier than
the original \fBDATE\fR.
.PP
\fBTIME\fR - \fBINT\fR - returns a \fBTIME\fR that is \fBINT\fR minutes
earlier
than the original \fBTIME\fR.
.PP
\fBDATETIME\fR - \fBINT\fR - returns a \fBDATETIME\fR that is
\fBINT\fR minutes earlier than the original \fBDATETIME\fR.
.PP
\fBDATETIME\fR - \fBTIME\fR - coerces the \fBTIME\fR to an \fBINT\fR
and then performs subtraction as above.
.RE
.TP
.B <, <=, >, and >=
These are the comparison operators.  They can take operands of any type,
but both operands must be of the same type.  The comparison operators
return 1 if the comparison is true, or 0 if it is false.  Note that
string comparison is done following the lexical ordering of
characters on your system, and that upper and lower case \fIare\fR
distinct for these operators.
.TP
.B ==, !=
== tests for equality, returning 1 if its operands are equal, and
0 if they are not.  != tests for inequality.
.PP
.RS
If the operands are not of the same type, == returns 0 and != returns
1.  Again, string comparisons are case-sensitive.
.RE
.TP
.B &&
This is the logical AND operator.  Returns the second operand if both
operands are non-zero.  Otherwise, returns whichever operand is zero.
Operands can be any type and "zero" is interpreted as appropriate for
each operand's type.
.TP
.B ||
This is the logical OR operator.  It returns the first operand that is
non-zero; if both operands are zero, then returns the second operand.
Operands can be any type and "zero" is interpreted as appropriate for
each operand's type.
.PP
.B NOTES
.PP
If the result of an addition, subtraction or multiplication operation
would not fit in a C "int" type, \fBRemind\fR issues a "Number too
high" error.  Unlike C, integer operations will not simply give the
wrong answer in case of overflow.
.PP
Operators of equal precedence are \fIalways\fR evaluated from left
to right, except where parentheses dictate otherwise.  This is important,
because the enhanced "+" operator is not necessarily associative.
For example:
.PP
.nf
	1 + 2 + "string" + 3 + 4  yields "3string34"
	1 + (2 + "string") + (3 + 4)  yields "12string7"
	12:59 + 1 + "test"  yields "13:00test"
	12:59 + (1 + "test")  yields "12:591test"
.fi
.PP
The logical operators are so-called short-circuit operators, as
they are in C.  This means that if the first operand of || is true,
then the second operand is \fInot\fR evaluated.  Similarly, if the first
operand of && is false, then the second operand is \fInot\fR evaluated.
.PP
.B VARIABLES
.PP
\fBRemind\fR allows you to assign values to variables.  The \fBSET\fR
command is used as follows:
.PP
\fBSET\fR \fIvar\fR \fIexpr\fR
.PP
\fIVar\fR is the name of a variable.  It must start with a letter or
underscore, and consist only of letters, digits and underscores.  Only
the first 64 characters of a variable name are significant.  Variable
names are \fInot\fR case sensitive; thus, "Afoo" and "afOo" are the same
variable.  Examples:
.PP
.nf
	SET a 10 + (9*8)
	SET b "This is a test"
	SET mydir getenv("HOME")
	SET time 12:15
	SET date today()
.fi
.PP
Note that variables themselves have no type.  They take on the type of
whatever you store in them.
.PP
Variables set with SET or on the command-line with \fB\-i\fR\fIvar\fB=\fR\fIexpr\fR
have global scope.
.PP
To delete a variable, use the \fBUNSET\fR command:
.PP
\fBUNSET\fR \fIvar\fR [\fIvar\fR...]
.PP
For example, to delete all the variables declared above, use:
.PP
.nf
	UNSET a b mydir time date
.fi
.PP
.SH SYSTEM VARIABLES
.PP
In addition to the regular user variables, \fBRemind\fR has several
"system variables" that are used to query or control the operating
state of \fBRemind\fR.  System variables are available starting from
version 03.00.07 of \fBRemind\fR.
.PP
All system variables begin with a dollar sign '$'.  They can be used
in \fBSET\fR commands and expressions just as regular variables can.
All system variables always hold values of a specified type.  In
addition, some system variables cannot be modified, and you cannot
create new system variables.  System variables can be initialized on
the command line with the \fB\-i\fR option, but you may need to quote
them to avoid having the shell interpret the dollar sign.  System
variable names are not case-sensitive.
.PP
The following system variables are defined.  Those marked
"read-only" cannot be changed with the \fBSET\fR command.
All system variables hold values of type \fBINT\fR, unless otherwise
specified.
.TP
.B $AddBlankLines
If set to 1 (the default), then \fBRemind\fR normally prints a blank
line after the banner and each reminder.  (This can be suppressed by
ending the reminder or banner with a single percent sign.)  If
$AddBlankLines is set to 0, then \fBRemind\fR does not print the blank line.
In this case, ending a reminder with % has no effect.  If you \fIdo\fR
want a blank line after a reminder, end it with \fB%_\fR to insert a
newline.

.TP
.B $CalcUTC
If 1 (the default), then \fBRemind\fR uses C library functions
to calculate the number of minutes between local and Universal Time
Coordinated.
This affects astronomical calculations (\fBsunrise()\fR for example.)
If 0, then you must supply the number of minutes between local and
Universal Time Coordinated in the \fB$MinsFromUTC\fR system variable.
.TP
.B $CalMode (read-only)
If non-zero, then the \fB\-c\fR option was supplied on the command line.
.TP
.B $CalType (read-only, STRING type)
If the \fB\-c\fR, \fB\-s\fR or \fB\-p\fR command-line options were
used, then this variable has the value "monthly".  If \fB\-c+\fR,
\fB\-s+\fR or \fB\-p+\fR were used, then "weekly".  Otherwise, "none".
.TP
.B $Daemon (read-only)
If "daemon mode" \fB\-z\fR was invoked, contains the number of
minutes between wakeups.  If not running in daemon mode, contains
0.  In server mode (either \fB-z0\fR or \fB-zj\fR), contains -1.
.TP
.B $DateSep (STRING type)
This variable can be set only to "/" or "-".  It holds the character
used to separate portions of a date when \fBRemind\fR prints a DATE or
DATETIME value.
.TP
.B $DedupeReminders
If this variable is set to 1, then \fBRemind\fR will suppress duplicate
reminders.  A given reminder is considered to be a duplicate of a
previous one if it has the \fIexact\fR same trigger date, trigger
time, and body.  By default, this variable is set to 0 and \fBRemind\fR does
not suppress duplicate reminders.
.RS
.PP
As an example, consider the following reminder file:
.PP
.nf
        SET $DedupeReminders 1
        REM Wednesday MSG Phooey
        REM 20 MSG Phooey
.fi
.PP
On Wednesday, 20 November 2024, only \fIone\fR "Phooey" will be issued.
In December of 2024, "Phooey" will be issued every Wednesday as well
as on Friday, 20 December 2024
.PP
If you set $DedupeReminders to 0, then \fBRemind\fR does not even track
reminders to detect duplicates.  Consider the following example:
.PP
.nf
        SET $DedupeReminders 0
        REM Wednesday MSG Hello
        SET $DedupeReminders 1
        REM Wednesday MSG Hello
.fi
.PP
Every Wednesday, \fBRemind\fR will issue \fItwo\fR "Hello" reminders.
Because $DedupeReminders was 0 when the first "Hello" was issued, it
won't be tracked for potential duplicates.
.PP
Duplicates are detected after all variable expansion and substitutions
have been done.  Consider the following:
.PP
.nf
        SET $DedupeReminders 1
        set a "foo"
        REM MSG [a]
        set a "bar"
        REM MSG [a]
        set a "foo"
        REM MSG [a]
.fi
.PP
The first REM will trigger and print "foo".  The second will trigger and
print "bar".  The third will not trigger because it's a duplicate of the
first "foo".
.RE
.TP
.B $DefaultColor (STRING type)
This variable can be set to a string that has the form of three
space-separated numbers.  Each number must be an integer from 0 to
255, or all three numbers must be -1.  The default value of
\fB$DefaultColor\fR is "-1 -1 -1", which suppresses default coloring
of MSG-type reminders.  If you set \fB$DefaultColor\fR to any other
value, then all MSG-, MSF- and CAL-type reminders are effectively
converted into SPECIAL COLOR reminders whose color value is specified
by \fB$DefaultColor\fR.
.RS
.PP
Unlike other system variables, the value of \fB$DefaultColor\fR is
\fInot\fR preserved between calendar iterations; rather, it is reset
to "-1 -1 -1" at the start of each iteration.
.RE
.TP
.B $DefaultPrio
The default priority assigned to reminders without a \fBPRIORITY\fR
clause.  You can set this as required to adjust the priorities of
blocks of reminders without having to type priorities for individual
reminders.  At startup, \fB$DefaultPrio\fR is set to 5000; it can range
from 0 to 9999.
.TP
.B $DefaultDelta
You can set this variable to a number from 0 through 10000.  If set to
a non-zero number, then \fBRemind\fR triggers any \fBREM\fR statement
that lacks a delta as if it had a delta of \fB++$DefaultDelta\fR.
By default, \fB$DefaultDelta\fR is zero.
.TP
.B $DefaultTDelta
The default time delta used if no +N is given in an AT clause.  This
is normally 0, but can be set with the \fB\-tt\fR option or explicitly
set in your script.  If \fB$DefaultDelta\fR is non-zero, you can use an
explicit delta of +0 in an AT clause to countermand the default delta.
.TP
.B $DeltaOverride (read-only)
If non-zero, corresponds to the \fIn\fR argument given to a
\fB\-t\fR\fIn\fR command-line option.
.TP
.B $DontFork (read-only)
If non-zero, then the \fB\-c\fR option was supplied on the command line.
.TP
.B $DontTrigAts (read-only)
The number of times that the \fB\-a\fR option was supplied on the
command line.
.TP
.B $DontQueue (read-only)
If non-zero, then the \fB\-q\fR option was supplied on the command line.
.TP
.B $EndSent (STRING type)
Contains a list of characters that end a sentence.  The \fBMSF\fR
keyword inserts two spaces after these characters.  Initially,
\fB$EndSent\fR is set to ".!?" (period, exclamation mark, and
question mark.)
.TP
.B $EndSentIg (STRING type)
Contains a list of characters that should be ignored when \fBMSF\fR
decides whether or not to place two spaces after a sentence.  Initially,
is set to "'>)]}"+CHAR(34) (single-quote, greater-than, right
parenthesis, right bracket, right brace, and double-quote.)
.PP
.RS
For example, the default values work as follows:
.PP
.nf
	MSF He said, "Huh! (Two spaces will follow this.)"  Yup.
.fi
.PP
because the final parenthesis and quote are ignored (for the purposes
of spacing) when they follow a period.
.RE
.TP
.B $ExpressionTimeLimit
If set to a non-zero value \fIn\fR, than any expression that takes longer than
\fIn\fR seconds to evaluate will be aborted and an error returned.  This is
to prevent maliciously-crafted expressions for creating a denial-of-service.
In an included file, $ExpressionTimeLimit can only be lowered from its
current value.  In the top-level file, it can be set to any value, including
zero to disable the time limit.
.TP
.B $FirstIndent
The number of spaces by which to indent the first line of a \fBMSF\fR-type
reminder.  The default is 0.
.TP
.B $FoldYear
The standard Unix library functions may have difficulty dealing with dates
later than 2037.  If this variable is set to 1, then the UTC calculations
"fold back" years later than 2037 before using the Unix library functions.
For example, to find out whether or not daylight saving time is in
effect in June, 2077, the year is "folded back" to 2027, because both
years begin on a Friday, and both are non-leapyears.  The rules for
daylight saving time are thus presumed to be identical for both
years, and the Unix library functions can handle 2027.  By default,
this variable is 0.  Set it to 1 if the sun or UTC functions misbehave
for years greater than 2037.  See also the section "MACHINES WITH A
32-BIT TIME_T TYPE"
.TP
.B $FormWidth
The maximum width of each line of text for formatting \fBMSF\fR-type
reminders.  The default is the width of the terminal in columns, minus
8, but clamped at a minimum of 20 and a maximum of 500.  If standard
output is not a terminal, then the default is 72.If an \fBMSF\fR-type
reminder contains a word too long to fit in this width, it will not be
truncated - the width limit will be ignored.
.TP
.B $HideCompletedTodos (read-only)
If non-zero, then the \fB\-\-hide-completed-todos\fR option was supplied
on the command line.
.TP
.B $HushMode (read-only)
If non-zero, then the \fB\-h\fR option was supplied on the command line.
.TP
.B $IgnoreOnce (read-only)
If non-zero, then the \fB\-o\fR option was supplied on the command
line, or implicitly enabled for some other reason.  In this case,
\fBONCE\fR directives will be ignored.
.TP
.B $InfDelta (read-only)
If non-zero, then the \fB\-t\fR option was supplied on the command line,
with no \fIn\fR argument.
.TP
.B $IntMax (read-only)
The largest representable \fBINT\fR.  On a machine with 32-bit signed integers
using twos-complement representation, this will be 2147483647.
.TP
.B $IntMin (read-only)
The smallest representable \fBINT\fR.  On a machine with 32-bit signed integers
using twos-complement representation, this will be -2147483648.
.TP
.B $Latitude (STRING type)
The latitude of your location, expressed as a string that is a floating-point
number.  Because \fBRemind\fR does not have a native floating-point type,
we need to express it as a string.  $Latitude can range from "-90.0" to
"90.0", with positive numbers representing points north of the equator
and negative numbers representing south.  Note that regardless of your
locale, $Latitude is always interpreted in the "C" locale and as such,
the decimal point must be a period (".").
.TP
.B $Longitude (STRING type)
The longitude of your location, expressed as a string that is a floating-point
number.  Because \fBRemind\fR does not have a native floating-point type,
we need to express it as a string.  $Longitude can range from "-180.0" to
"180.0", with positive numbers representing points east of the Greenwich
Meridian and negative numbers representing west.  Note that regardless of your
locale, $Longitude is always interpreted in the "C" locale and as such,
the decimal point must be a period (".").
.RS
.PP
For example, the coordinates of the Statue of Liberty in New York City
are approximately set by:
.PP
.nf
    SET $Latitude   "40.68933"
    SET $Longitude "-74.04454"
.fi
.RE
.TP
.B $LatDeg, $LatMin, $LatSec (DEPRECATED)
These specify the latitude of your location.  \fB$LatDeg\fR can
range from \-90 to 90, and the others from \-59 to 59.  Northern latitudes
are positive; southern ones are negative.  For southern latitudes, all
three components should be negative.  These three variables
are deprecated; you should use \fB$Latitude\fR instead.
.TP
.B $Location (STRING type)
This is a string specifying the name of your location.  It is usually
the name of your town or city.  It can be set to whatever you like,
but good style indicates that it should be kept consistent with
the latitude and longitude system variables.
.TP
.B $LongDeg, $LongMin, $LongSec (DEPRECATED)
These specify the longitude of your location.  \fB$LongDeg\fR can
range from \-180 to 180.  Western longitudes are positive; eastern
ones are negative.  Note that all three components should have the
same sign: All positive for western longitudes and all negative for
eastern longitudes.  Note that for historical reasons, the sign for
longitude is \fIdifferent\fR from the usual convention!  If you find
the longitude of your location from a search engine, you will most
likely \fIneed to invert the sign to have it work correctly with
Remind.\fR These three variables are deprecated; you should use
\fB$Longitude\fR instead.  Note also that \fB$Longitude\fR uses the
standard convention of negative for western longitudes and positive
for eastern ones.
.RS
.PP
The latitude and longitude information is required for the functions
\fBsunrise()\fR and \fBsunset()\fR.  Default values can be compiled
into \fBRemind\fR, or you can \fBSET\fR the correct values at the
start of your reminder scripts.
.PP
Note that setting any of \fB$LongDec\fR, \fB$LongMin\fR and \fB$LongSec\fR
updates \fB$Longitude\fR correspondingly, and setting \fB$Longitude\fR
updates \fB$LongDeg\fR, \fB$LongMin\fR and \fB$LongSec\fR.  Similar
rules apply to \fB$Latitude\fR, \fB$LatDeg\fR, \fB$LatMin\fR and \fB$LatSec\fR.
.RE
.TP
.B $JSONMode (read-only)
If non-zero, then the \fB\-\-json\fR command-line option was supplied.
.TP
.B $MaxLateMinutes
This variable controls how \fBRemind\fR reacts to a computer being suspended
and then woken.  Normally, if a timed reminder is queued and then the
computer suspended, and then the computer is woken \fIafter\fR the
timed reminder's trigger time, \fBRemind\fR will trigger the timer anyway,
despite the fact that the trigger time has already passed.
.RS
.PP
If you set \fB$MaxLateMinutes\fR to a non-zero integer between 1 and 1440,
then \fBRemind\fR will \fInot\fR trigger a timed reminder whose trigger
time is more than \fB$MaxLateMinutes\fR minutes in the past.
.PP
Note that \fBRemind\fR uses the value of \fB$MaxLateMinutes\fR that is in
effect when it has finished reading the reminder file and puts itself in
the background.  Generally, you should set \fB$MaxLateMinutes\fR once
near the beginning of the file and not change it after that.
.RE
.TP
.B $MaxSatIter
The maximum number of iterations for the \fBSATISFY\fR clause
(described later.)  Must be at least 10.  The default value is 10,000.
.TP
.B $MaxStringLen
A limit on the longest string that \fBRemind\fR will allow you
to create.  The default is 65535.  If you set \fB$MaxStringLen\fR to 0
or to -1, then \fBremind\fR will allow you to create arbitrarily-long
strings, at least until it runs out of memory.  We do not recommend
setting \fB$MaxStringLen\fR to 0 or -1 because it is very easy to write
code that DOSes \fBRemind\fR in that case.
.TP
.B $MinsFromUTC
The number of minutes between Universal Time Coordinated and local time.  If
\fB$CalcUTC\fR is non-zero, this is calculated upon startup of \fBRemind\fR.
Otherwise, you must set it explicitly.  If \fB$CalcUTC\fR is zero,
then \fB$MinsFromUTC\fR is used in the astronomical calculations.  You
must adjust it for daylight saving time yourself.  Also, if you
want to initialize \fB$MinsFromUTC\fR
using the \fB\-i\fR command-line option, you
must also set \fB$CalcUTC\fR to 0 with the \fB\-i\fR option.
.TP
.B $NextMode (read-only)
If non-zero, then the \fB\-n\fR option was supplied on the command line.
.TP
.B $MaxFullOmits (read-only)
The maximum number of full OMITs allowed (a compiled-in constant.)
.TP
.B $MaxPartialOmits (read-only)
The maximum number of partial OMITs allowed (a compiled-in constant.)
.TP
.B $NumFullOmits (read-only)
The number of full OMITs in the current OMIT context.
.TP
.B $NumPartialOmits (read-only)
The number of partial OMITs in the current OMIT context.
.TP
.B $NumQueued (read-only)
Contains the number of reminders queued so far for background
timed triggering.
.TP
.B $NumTrig (read-only)
Contains the number of reminders triggered for the current date.  One
use for this variable is as follows:  Suppose you wish to shade in
the box of a PostScript calendar whenever a holiday is triggered.  You
could save the value of \fB$NumTrig\fR in a regular variable
prior to executing a block of
holiday reminders.  If the value of \fB$NumTrig\fR after the holiday
block is greater than the saved value, then at least one holiday
was triggered, and you can execute the command to shade in the
calendar box.  (See the section "Calendar Mode".)
.PP
.RS
Note that \fB$NumTrig\fR is affected \fIonly\fR
by \fBREM\fR commands; triggers in \fBIFTRIG\fR commands do
not affect it.
.RE
.TP
.B $OnceFile (STRING type)
If you set this variable to a non-empty string, then rather than using
the file access date to determine whether or not to run a ONCE-type
reminder, \fBRemind\fR will maintain a timestamp in the file \fB$OnceFile\fR.
This is more reliable than using the access date of the reminder file.
.RS
.PP
If \fB$OnceFile\fR does not exist, then it will be created the first time
a \fBONCE\fR keyword is processed.  The file must be writable by the
current user.  If you try to set \fB$OnceFile\fR \fIafter\fR a \fBONCE\fR
reminder has already been processed, \fBRemind\fR will issue a warning
and ignore the attempt to set \fB$OnceFile\fR.
.RE
.TP
.B $ParseUntriggered
A flag indicating whether or not \fBRemind\fR should fully parse
\fBREM\fR statements that are not triggered.  0 (the default) means to
skip parsing them and 1 means to parse them.
.PP
.RS
For example, if we have the following \fBREM\fR statement:
.PP
.nf
            REM 2020-01-01 MSG ["bad_expression" / 2]
.fi
.PP
Then if \fB$ParseUntriggered\fR is set to 1, \fBRemind\fR will fully
parse the line and issue a "Type mismatch" error even if the reminder
is not triggered.  However, if \fB$ParseUntriggered\fR is set to 0,
the default, then \fBRemind\fR will not issue the error except on
2020-01-01, when the reminder is triggered.
.PP
Keeping \fB$ParseUntriggered\fR at 0 may slightly improve performance,
at the risk of not catching errors until a reminder is triggered.  We recommend
leaving it set to 0.
.RE
.TP
.B $PrefixLineNo (read-only)
If non-zero, then the \fB\-l\fR option was supplied on the command line.
.TP
.B $PSCal (read-only)
If non-zero, then the \fB\-p\fR option was supplied on the command line.
.TP
.B $RunOff (read-only)
If non-zero, the \fBRUN\fR directives are disabled.
.TP
.B $SimpleCal (read-only)
Set to a non-zero value if \fIeither\fR of the \fB\-p\fR or \fB\-s\fR
command-line options was supplied.
.TP
.B $SortByDate (read-only)
Set to 0 if no \fB\-g\fR option is used, 1 if sorting by date in ascending
order, or 2 if sorting by date in descending order.
.TP
.B $SortByPrio (read-only)
Set to 0 if no \fB\-g\fR option is used, 1 if sorting by priority in ascending
order, or 2 if sorting by priority in descending order.
.TP
.B $SortByTime (read-only)
Set to 0 if no \fB\-g\fR option is used, 1 if sorting by time in ascending
order, or 2 if sorting by time in descending order.
.TP
.B $SubsIndent
The number of spaces by which all lines (except the first) of an
\fBMSF\fR-type reminder should be indented.  The default is 0.
.TP
.B $SuppressImplicitWarnings
Normally, \fBRemind\fR issues a warning if a line begins with an unknown
token and is treated as a \fBREM\fR command, or if a \fBREM\fR command
is missing a type and is treated as a \fBMSG\fR-type reminder.  Setting
\fB$SuppressImplicitWarnings\fR to 1 suppresses these warnings.  The default
is 0 and we do not recommend disabling the warnings.
.TP
.B $SuppressLRM
Normally, when \fBRemind\fR is run with the \fB\-c\fR option in a UTF-8 locale,
it emits a left-to-right mark sequence after printing day names or
reminders.  Some terminals render this incorrectly, so you can use:
.RS
.PP
.nf
    SET $SuppressLRM 1
.fi
.PP
at the top of your reminder file to suppress the LRM sequences, or you
can invoke \fBRemind\fR with the option \fB'\-i$SuppressLRM=1'\fR.
.RE
.TP
.B $SysInclude (read-only, STRING type)
A directory path containing standard reminder scripts.  Currently,
\fBRemind\fR ships with some standard holiday files and language packs.
The value of \fB$SysInclude\fR is "@prefix@/share/remind" on
this installation.
.TP
.B $T (read-only, DATE or INT type)
Equivalent to \fBtrigdate()\fR.  (See BUILT-IN FUNCTIONS.)
.TP
.B $Tb (read-only, DATE or INT type)
Equivalent to \fBtrigbase()\fR.
.TP
.B $Td (read-only)
Equivalent to \fBday(trigdate())\fR.
.TP
.B $Tm (read-only)
Equivalent to \fBmonnum(trigdate())\fR.
.TP
.B $Tu (read-only, DATE or INT type)
Equivalent to \fBtriguntil()\fR.
.TP
.B $Tw (read-only)
Equivalent to \fBwkdaynum(trigdate())\fR.
.TP
.B $Ty (read-only)
Equivalent to \fByear(trigdate())\fR.
.TP
.B $Tt (read-only, TIME or INT type)
Equivalent to \fBtrigtime()\fR.
.TP
.B $TimeSep (STRING type)
This variable can be set only to ":" or ".".  It holds the character
used to separate portions of a time when \fBRemind\fR prints a TIME or
DATETIME value.
.TP
.B $TimetIs64bit (read-only)
This variable returns 1 if the internal C \fBtime_t\fR type is at least
64 bits long.  If it returns 0, then the internal C library is unable
to represent dates after about 2038, and \fBRemind\fR will use a workaround to avoid
problems.  See also the section "MACHINES WITH A 32-BIT TIME_T TYPE"
.TP
.B $TodoFilter (read-only)
If 0, then both events and TODOs are being output.  If 1, then the
\fB\-\-only-todos\fR command-line option was supplied.  If 2, then
the \fB\-\-only-events\fR command-line option was supplied.
.TP
.B $UntimedFirst (read-only)
Set to 1 if the \fB\-g\fR option is used with a fourth sort character
of "d"; set to 0 otherwise.
.TP
.B $U (read-only, DATE type)
Exactly equivalent to \fBtoday()\fR.  (See BUILT-IN FUNCTIONS.)
.TP
.B $Ud (read-only)
Equivalent to \fBday(today())\fR.
.TP
.B $Um (read-only)
Equivalent to \fBmonnum(today())\fR.
.TP
.B $Uw (read-only)
Equivalent to \fBwkdaynum(today())\fR.
.TP
.B $Uy (read-only)
Equivalent to \fByear(today())\fR.
.TP
.B $UseVTColors (read-only)
Set to 1 if the \fB\-@\fR or \fB\-cc\fR options were used; 0 otherwise.
.TP
.B $UseBGVTColors (read-only)
Set to 1 if the \fB\-@,,1\fR option was used; 0 otherwise.
.TP
.B $Use256Colors (read-only)
Set to 1 if the \fB\-@1\fR option was used; 0 otherwise.
.TP
.B $UseTrueColors (read-only)
Set to 1 if the \fB\-@2\fR option was used; 0 otherwise.
.TP
.B $TerminalBackground (read-only)
Returns -1 if the terminal background color could not be determined, 0
if it was found to be dark (or was specified as dark with the
\fB\-@,0\fR option) or 1 if it was found to be light (or specified as
light with the \fB\-@,1\fR option.)  The terminal background is considered
to be "dark" if the average of the red, green and blue components is
at most 85 out of 255, and if the maximum of any component is at most
128 out of 255.
.TP
.B $TerminalHyperlinks (INT type)
If your terminal supports escape sequences to allow HTML-like
anchors around text (see https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda), then you can set this variable to 1.  \fBRemind\fR will then
make any reminder with a "Url:" info string into a hyperlink in your
terminal.  By default, \fB$TerminalHyperlinks\fR is set to 1 if \fBRemind\fR's
standard output is a terminal, or to 0 if it is not.
.TP
.B $WarningLevel (STRING type)
As new versions of \fBRemind\fR are released, new warnings may be added.
If your formerly-fine scripts suddenly start issuing warnings when you
upgrade \fBRemind\fR, then as a \fIstopgap\fR measure, you may set
\fB$WarningLevel\fR to a string of the form \fIAB\fR.\fICD\fR.\fIEF\fR where
\fIAB\fR, \fICD\fR and \fIEF\fR are pairs of decimal digits.  This will
suppress any warnings that were introduced \fIafter\fR \fBRemind\fR
version \fIAB\fR.\fICD\fR.\fIEF\fR.  If you do not set \fB$WarningLevel\fR, then
it defaults to the current version of \fBRemind\fR, meaning all warnings
will be issued.
.RS
.PP
For example, if you want the warnings you receive limited to what
Remind 05.00.00 would have produced, use:
.PP
.nf
    SET $WarningLevel "05.00.00"
.fi
.PP
We do \fInot\fR recommend setting \fB$WarningLevel\fR as a matter
of course; you should use it to suppress warnings only for as long as
it takes for you to fix your remind scripts so they no longer cause
warnings to be emitted.
.RE
.PP
Note:  If any of the calendar modes are in effect, then the
values of $Daemon, $DontFork, $DontTrigAts, $DontQueue, $HushMode,
$IgnoreOnce, $InfDelta, and $NextMode are not meaningful.
.PP
.SH SAVING AND RESTORING VARIABLES
.PP
Just as with the OMIT context, you can save and restore the values of
global variables and all (modifiable) system variables.  For example:
.PP
.nf
        SET a 1
        UNSET b

        # Save variables
        PUSH-VARS $DefaultColor $AddBlankLines a b

        SET $DefaultColor "255 0 0"
        SET $AddBlankLines 0
        SET a 3
        SET b 4
        REM MSG Hello

        # Restore all the variables we pushed earlier
        POP-VARS

        # Now the changes to $DefaultColor and $AddBlankLines
        # have been undone.  Additionally, a is restored to 1
        # and b is unset
.fi
.PP
As you see from the example, PUSH-VARS takes a list of global variable
names and/or system variable names.  You can save the values of any
\fImodifiable\fR system variables and any global variable.  You can
even push global variables that are not set.
.PP
The POP-VARS command restores the values of all system variables and
global variables that were pushed by the most recent PUSH-VARS
command.  If you push an undefined global variable, then that variable
is unset by the POP-VARS command.
.PP
.SH BUILT-IN FUNCTIONS
.PP
\fBRemind\fR has a plethora of built-in functions.  The syntax for a function
call is the same as in C - the function name, followed a comma-separated list
of arguments in parentheses.  Function names are not case-sensitive.  If
a function takes no arguments, it must be followed by "()" in the function
call.  Otherwise, \fBRemind\fR will interpret it as a variable name,
and probably not work correctly.
.PP
In the descriptions below, short forms are used to denote acceptable
types for the arguments.  The characters "i", "s", "d", "t" and "q" denote
\fBINT\fR, \fBSTRING\fR, \fBDATE\fR, \fBTIME\fR and \fBDATETIME\fR arguments,
respectively.  If an argument can be one of several types, the characters
are concatenated.  For example, "di_arg" denotes an argument that can be
a \fBDATE\fR or an \fBINT\fR.  "x_arg" denotes an argument that can be
of any type.  The type of the argument is followed by
an underscore and an identifier naming the argument.
.PP
The built-in functions are:
.TP
.B _(s_message)
Returns the translation table entry for \fImessage\fR.  If there is no
such translation table entry, then returns \fImessage\fR unmodified.
For example, consider this sequence:
.RS
.PP
.nf
        TRANSLATE "Goodbye" "Tot ziens"
        SET a _("Goodbye")
.fi
.PP
After those two lines have been executed, the variable \fBa\fR will be
set to "Tot ziens".  See the section THE TRANSLATION TABLE for more
information.
.PP
In the body of a reminder, the substitution sequence
\fB%(\fItext\fR\fB)\fR is (almost) the equivalent of
\fB[_("\fItext\fR\fB")]\fR.  Therefore, the following reminders are
almost equivalent:
.PP
.nf

        REM MSG %(Goodbye)
        REM MSG [_("Goodbye")]
.fi
.PP
The only difference is that if _("Goodbye") contains a \fB%\fR sign,
then that result will be run through the substitution filter, whereas
in the first reminder, it will not.  That is because the second
\fBREM\fR command performs expression pasting followed by a
substitution filter pass, while the first one performs the translation
as part of the substitution filter (and does not make a second
substitution filter pass.)
.RE
.TP
.B abs(i_num)
Returns the absolute value of \fInum\fR.
.TP
.B access(s_file, si_mode)
Tests the access permissions for the file \fIfile\fR.  \fIMode\fR can
be a string, containing a mix of the characters "rwx" for read,
write and execute permission testing.  Alternatively, \fImode\fR can
be a number as described in the UNIX \fBaccess\fR(2) system call.  The
function returns 0 if the file can be accessed with the specified \fImode\fR,
and \-1 otherwise.
.TP
.B adawn([dq_date])
Returns the time of "astronomical dawn" on the specified \fIdate\fR.  If
\fIdate\fR is omitted, defaults to \fBtoday()\fR.  If a \fIdatetime\fR object
is supplied, only the date component is used.
.TP
.B adusk([dq_date])
Returns the time of "astronomical twilight" on the specified \fIdate\fR.  If
\fIdate\fR is omitted, defaults to \fBtoday()\fR.
.TP
.B ampm(tq_time [,s_am [,s_pm [,i_lz]]])
Returns a \fBSTRING\fR that is the result of converting \fItime\fR
(which is either a \fBTIME\fR or a \fBDATETIME\fR object) to "AM/PM"
format.  The optional arguments \fIam\fR and \fIpm\fR are the strings
to append in the AM and PM case, respectively; they default to "AM"
and "PM".  The optional argument \fIlz\fR specifies whether or not
the hour should be padded to two digits with a leading zero.  If \fIlz\fR is
zero, then a leading 0 is not added; otherwise, the hour is padded out to
two digits with a leading zero.  If not supplied, \fIlz\fR defaults to zero.
.RS
.PP
The function obeys the system variables $DateSep, $TimeSep and
$DateTimeSep when formatting its output.  Here are some examples of
its output:
.PP
.nf
        ampm(0:22)                 returns "12:22AM"
        ampm(17:45, "am", "pm")    returns "5:45pm"
        ampm(17:45, "am", "pm", 1) returns "05:45pm"
        ampm('2020-03-14@21:34')   returns "2020-03-14@9:34PM"
.fi
.PP
.RE
.TP
.B ansicolor(i_red, i_green, i_blue [,i_bg [,i_clamp]])
Returns a \fBSTRING\fR that contains an ANSI escape sequence for changing
the terminal text color.  The parameters \fIred\fR, \fIgreen\fR and \fIblue\fR
are integers from 0 to 255 specifying the value of the respective color
component.  As a special case, all three values can be -1, in which case
the ANSI sequence "ESC[0m" is returned, which resets all text attributes
to normal.
.RS
.PP
The string returned by \fBansicolor\fR depends on the color mode that
\fBRemind\fR is running in, as specified by the \fB\-@\fR option.  If color
mode is not enabled, then \fBansicolor\fR always returns the empty string.
Otherwise, it returns the escape sequence that best approximates the color
according to the \fB\-@\fR color mode.
.PP
The optional \fIbg\fR argument is either 0 or 1.  If 0 (the default), then
the foreground color is set.  If 1, then the background color is set.  Note
that setting the background color only works in 256-color or true-color
mode.
.PP
The optional \fIclamp\fR argument is either 0 or 1.  If 0 (the default),
then colors are not adjusted based on the terminal background color.  If
1, then \fBRemind\fR attempts to adjust dark or bright colors so they have
enough contrast to be visible in the terminal.
.PP
The first three arguments may alternatively be specified as a string
consisting of three space-separated numbers, as in this example: "128 128 0"
.PP
As a special case, \fBansicolor("")\fR is equivalent to
\fBansicolor(-1,-1,-1)\fR and returns the ANSI sequence to reset all text
attributes to normal.
.PP
Note that inserting ANSI color sequences in calendar mode \fIwill
produce garbled results\fR.  Therefore, we recommend defining
functions such as the ones below that return the empty string in
calendar mode:
.PP
.nf
        IF $CalMode
            FSET fg(r,g,b) ""
            FSET bg(r,g,b) ""
        ELSE
            FSET fg(r,g,b) ansicolor(r,g,b)
            FSET bg(r,g,b) ansicolor(r,g,b,1)
        ENDIF
        REM [fg(255,0,0)][bg(64,64,64)]Red on Gray[fg(-1,-1,-1)] in agenda mode
        REM SPECIAL COLOR 0 255 0 Green in agenda and calendar mode
.fi
.PP
If you use the \fBansicolor\fR function, don't forget to reset the color
back to normal with \fBansicolor(-1,-1,-1)\fR or subsequent reminders
will continue to be colored.
.RE
.TP
.B args(s_fname)
Returns the number of arguments expected by the user-defined function
\fIfname\fR, or \-1 if no such user-defined function exists.  Note that
this function examines only user-defined functions, not built-in functions.
Its main use is to determine whether or not a particular user-defined
function has been defined previously.  The \fBargs()\fR function is
available only in versions of \fBRemind\fR from 03.00.04 and up.
.TP
.B asc(s_string)
Returns an \fBINT\fR that is the ASCII code of the first byte in
\fIstring\fR.  As a special case, \fBasc("")\fR returns 0.  For UTF-8
strings, this will return the UTF-8 byte with which the string begins,
which is not likely to be very useful.
.TP
.B codepoint(s_string)
Returns an \fBINT\fR that is the code point of the first character
in \fIstring\fR, treating multi-byte characters correctly.  As a special case,
\fBcodepoint("")\fR returns 0.
.TP
.B baseyr()
Returns the "base year" that was compiled into \fBRemind\fR (normally
1990.)  All dates are stored internally as the number of days since
1 January of \fBbaseyr()\fR.
.TP
.B catch(x_arg1, x_arg2)
Evaluates \fBarg1\fR and if no error occurs, returns the resulting value.
If an error occurs during the evaluation of \fBarg1\fR, evaluates and
returns \fBarg2\fR.  Note that \fBcatch()\fR can only catch
run-time \fIevaluation\fR errors.  It cannot catch \fIsyntax\fR errors.
.RS
.PP
Here are some examples:
.PP
.nf
catch(4/2, 33)  => 2, because 4/2 evaluates without error
catch(4/0, 33)  => 33, because 4/0 gives a divide-by-zero error
catch(2, 1/0)   => 2, and the second argument is not evaluated
catch(4/0, 1/0) results in a divide-by-zero error
.fi
.PP
Note in the last example that catch does \fInot\fR protect you from errors
in the evaluation of \fBarg2\fR.
.RE
.TP
.B catcherr()
Returns a string representing the error message from the most
recently-evaluated \fBcatch()\fR function whose first argument yielded
an error.  Note that the error message is always in English even if
\fBRemind\fR has been localized; this lets you reliably test the return
value.  Here are some examples:
.RS
.PP
.nf
    # No "catch" invocations yet:  sets a to "Ok"
    set a catcherr()

    # Sets b to "oops" and a to "Division by zero"
    set b catch(1/0, "oops")
    set a catcherr()

    # Sets b to 1 and a to "Division by zero".  The catch error
    # is never cleared by a non-error catch()
    set b catch(4-3, "not-evaluated")
    set a catcherr()
.fi
.RE
.TP
.B char(i_i1 [,i_i2...])
This function can take any number of \fBINT\fR arguments.  It returns
a \fBSTRING\fR consisting of the bytes specified by the arguments.
It is easy to create invalid UTF-8 sequences; \fBchar\fR does not check
for this.  Note that none of the arguments can be 0, unless there is only one
argument.  As a special case, \fBchar(0)\fR returns "".
.TP
.B mbchar(i_i1 [,i_i2...])
This function can take any number of \fBINT\fR arguments.  It returns
a \fBSTRING\fR consisting of the characters specified by the
arguments.  Any codepoint may be supplied and a correct multi-byte
character string will be returned.  Note that none of the arguments
can be 0, unless there is only one argument.  As a special case,
\fBmbchar(0)\fR returns "".  Additionally, no argument may be a
negative number.
.TP
.B choose(i_index, x_arg1 [,x_arg2...])
\fBChoose\fR must take at least two arguments, the first of which is
an \fBINT\fR.  If \fIindex\fR is \fIn\fR, then the \fIn\fRth subsequent
argument is returned.  If \fIindex\fR is less than 1, then \fIarg1\fR
is returned.  If \fIindex\fR is greater than the number of subsequent
arguments, then the last argument is returned.  Examples:
.PP
.nf
		\fBchoose(0, "foo", 1:13, 1000)\fR returns "foo"
		\fBchoose(1, "foo", 1:13, 1000)\fR returns "foo"
		\fBchoose(2, "foo", 1:13, 1000)\fR returns 1:13
		\fBchoose(3, "foo", 1:13, 1000)\fR returns 1000
		\fBchoose(4, "foo", 1:13, 1000)\fR returns 1000
.fi
.RS
.PP
Note that only the first argument and the chosen result are
evaluated.  Any non-chosen arguments will not be evaluated.
.RE
.TP
.B coerce(s_type, x_arg)
This function converts \fIarg\fR to the specified \fItype\fR, if such
conversion is possible.  \fIType\fR must be one of "INT", "STRING",
"DATE", "TIME" or "DATETIME" (case-insensitive).
The conversion rules are as follows:
.RS
.PP
If \fIarg\fR is already of the \fItype\fR specified, it is returned
unchanged.
.PP
If \fItype\fR is "STRING", then \fIarg\fR is converted to a string
consisting of its printed representation.
.PP
If \fItype\fR is "DATE", then an \fBINT\fR \fIarg\fR is converted
by interpreting it as the number of days since 1 January \fBbaseyr()\fR.
A \fBSTRING\fR \fIarg\fR is converted by attempting to read it as if
it were a printed date.  A \fBDATETIME\fR is converted to a date by
dropping the time component.  A \fBTIME\fR \fIarg\fR cannot be converted to
a date.
.PP
If \fItype\fR is "TIME", then an \fBINT\fR \fIarg\fR is converted
by interpreting it as the number of minutes since midnight.
A \fBSTRING\fR \fIarg\fR is converted by attempting to read it as if
it were a printed time.  A \fBDATETIME\fR is converted to a time by
dropping the date component.  A \fBDATE\fR \fIarg\fR cannot be converted to
a time.
.PP
If \fItype\fR is "DATETIME", then an \fBINT\fR \fIarg\fR is converted
by interpreting it as the number of minutes since midnight, 1 January
\fBbaseyr()\fR.  A \fBSTRING\fR is converted by attempting to read it as if
it were a printed datetime.  Other types cannot be converted to a datetime.
.PP
If \fItype\fR is "INT", then \fBDATE\fR, \fBTIME\fR and \fBDATETIME\fR
arguments are converted using the reverse of procedures described
above.  A \fBSTRING\fR \fIarg\fR is converted by parsing it as an
integer.
.RE
.TP
.B columns([s_arg])
If called with no arguments, \fBcolumns()\fR behaves as follows:
If either standard output or standard error is a TTY, returns the
width of the terminal in columns.  If neither standard output nor
standard error is a TTY, attempts to open "/dev/tty" to obtain the
terminal size.  If this fails, returns -1.
.RS
.PP
If called with a single string argument, \fBcolumns(str)\fR returns
the number of columns \fBstr\fR will occupy if printed to a terminal.
ANSI color-changing sequences occupy zero columns whereas some Unicode
characters occupy two columns.  \fBcolumns(str)\fR takes all of that
into account.  Note that if \fBRemind\fR was compiled without Unicode support,
\fBcolumns(str)\fR returns a type mismatch error.
.PP
The result of \fBcolumns(str)\fR may be less than, equal to, or
greater than the result of \fBmbstrlen(str)\fR.  This is because some
Unicode characters are so-called combining characters that add one to the
character length, but don't occupy any columns on their own.  And other
Unicode characters are double-width characters that add one to the
character length, but two to the number of display columns.
.RE
.TP
.B const(x_arg)
Evaluates \fIarg\fR and returns it, but also ensures that the result
is marked "constant".  Use with caution; incorrect use could result
in unwanted reminders being purged in Purge Mode.  See also the section
"NON-CONSTANT EXPRESSIONS"
.TP
.B current()
Returns the current date and time as a DATETIME object.  This may be the
actual date and time, or may be the date and time supplied on the command line.
.TP
.B date(i_y, si_m, i_d)
The \fBdate()\fR function returns a \fBDATE\fR object with the year,
month and day components specified by \fIy\fR, \fIm\fR and \fId\fR.
The month can be specified as an integer from 1 to 12, or a string
that is the name of a month.
.TP
.B datepart(dq_datetime)
Returns a \fBDATE\fR object representing the date portion of
\fIdatetime\fR.
.TP
.B datetime(args)
The \fBdatetime()\fR function can take anywhere from two to five arguments.
It always returns a DATETIME generated from its arguments.
.RS
.PP
If you supply two arguments, the first must be a DATE and the second a TIME.
.PP
If you supply three arguments, the first
must be a DATE and the second and third must be INTs.  The second and
third arguments are interpreted as hours and minutes and converted to a TIME.
.PP
If you supply four arguments, they are interpreted as year, month, day
and time.  Year and day must be INTs.  Month may be an INT from 0 to 12
or a string naming a month.  Time must be a TIME.
.PP
Finally, if you supply five arguments, they must all be INTs and are
interpreted as year, month, day, hour and minute.  (Actually, month
can also be a string that is the name of a month.)
.RE
.TP
.B dawn([dq_date])
Returns the time of "civil dawn" on the specified \fIdate\fR.  If \fIdate\fR
is omitted, defaults to \fBtoday()\fR.  If a \fIdatetime\fR object is
supplied, only the date component is used.
.TP
.B day(dq_date)
This function takes a \fBDATE\fR or \fBDATETIME\fR as an argument, and
returns an \fBINT\fR that is the day-of-month component of
\fIdate\fR.
.TP
.B daysinmon(si_m, i_y)\fR or \fB daysinmon(dq_date)\fR
Returns the number of days in month \fIm\fR (1-12) of the year
\fIy\fR.  The first argument can either be an integer from 1 to 12, or
a string that is the name of a month.  If given a single DATE or
DATETIME argument, returns the number of days in the month containing
the argument.
.TP
.B defined(s_var)
Returns 1 if the variable named by \fIvar\fR is defined, or 0 if it is not.
.RS
Note that \fBdefined()\fR takes a \fBSTRING\fR argument; thus, to check
if variable X is defined, use:
.PP
.nf
		defined("X")
.fi
.PP
and not:
.PP
.nf
		defined(X)
.fi
.PP
The second example will attempt to evaluate X, and will return an
error if it is undefined or not of type \fBSTRING\fR.
.RE
.TP
.B dosubst(s_str [,d_date [,t_time]]) \fRor\fB dosubst(s_str [,q_datetime])
Returns a \fBSTRING\fR that is the result of passing \fIstr\fR
through the substitution filter described earlier.  The parameters
\fIdate\fR and \fItime\fR (or \fIdatetime\fR) establish the effective
trigger date and time used by the substitution filter.  If \fIdate\fR
and \fItime\fR are omitted, they default to \fBtoday()\fR and
\fBnow()\fR.
.RS
.PP
Note that if \fIstr\fR does not end with "%", a newline character will be
added to the end of the result.  Also, calling \fBdosubst()\fR with a
\fIdate\fR that is in the past (i.e., if \fIdate\fR < \fBtoday()\fR)
will produce undefined results.
.PP
\fBDosubst()\fR is only available starting from version 03.00.04 of
\fBRemind\fR.
.RE
.TP
.B dusk([dq_date])
Returns the time of "civil twilight" on the specified \fIdate\fR.  If
\fIdate\fR is omitted, defaults to \fBtoday()\fR.
.TP
.B easterdate([dqi_arg])
If \fIarg\fR is an \fBINT\fR, then returns the date of Easter Sunday
for the specified year.  If \fIarg\fR is a \fBDATE\fR or
\fBDATETIME\fR, then returns the date of the next Easter Sunday on or
after \fIarg\fR.  (The time component of a datetime is ignored.)  If \fIarg\fR
is omitted, then it defaults to \fBtoday()\fR.
.RS
.PP
Note that \fBeasterdate\fR computes the Western Easter.  For the Orthodox
Easter date, see \fBorthodoxeaster\fR.
.RE
.TP
.B escape(s_string [,i_add_quotes])
Returns a \fBSTRING\fR that is the same as the input string, but with
all special characters backslashed-escaped.  For example, the following
command:
.RS
.PP
.nf
        set a escape("foo" + char(10) + "bar")
.fi
.PP
will set a to "foo\\nbar" where "\\n" is the literal sequence "\\" followed
by "n".  This is useful if you want to compute a string in a pasted-in
expression that \fBRemind\fR will then parse as a quoted string again,
such as in a TRANSLATE command or an INFO clause.
.PP
If the optional \fIadd_quotes\fR argument is supplied and is non-zero, then
the return value from \fBescape\fR will include surrounding double-quotes.
.RE
.TP
.B eval(s_arg)
Parses the string \fIarg\fR as an expression and evaluates it, returning
the result.  Note that any variable names in the parsed expression refer
to global variables, not any local variables.  For example, consider this:
.PP
.RS
.nf
        SET x 2
        FSET f(x) x + eval("1 + x")
        REM MSG F is [f(9)]
.fi
.PP
The result will be "F is 12" because the reference to \fIx\fR inside the
\fBeval()\fR argument refers to the \fIglobal\fR variable \fIx\fR and
not the function argument.
.PP
Note that for safety, \fBRUN\fR is disabled during the evaluation of
\fBeval()\fR, which means you can't use the \fBshell()\fR function from
within an \fBeval()\fR.
.PP
.RE
.TP
.B evaltrig(s_trigger [,dq_start])
Evaluates \fItrigger\fR as if it were a REM or IFTRIG trigger specification
and returns the trigger date as a \fBDATE\fR (or as a \fBDATETIME\fR if
there is an \fBAT\fR clause.)  Returns a negative \fBINT\fR if no trigger
could be computed.
.RS
.PP
Normally, \fBevaltrig\fR finds a trigger date on or after today.  If
you supply the \fIstart\fR argument, then it scans starting from there.
.PP
For example, the expression:
.PP
.nf
  evaltrig("Mon 1", '2008-10-07')
.fi
.PP
returns '2008-11-03', since that is the first date on or after
7 October 2008 that satisfies "Mon 1".
.PP
If you want to see how many days it is from the first Monday in October, 2008
to the first Monday in November, 2008, use:
.PP
.nf
  evaltrig("Mon 1", '2008-11-01') - evaltrig("Mon 1", '2008-10-01')
.fi
.PP
and the answer is 28.  The trigger argument to \fBevaltrig\fR can have
all the usual trigger clauses (\fBOMIT\fR, \fBAT\fR, \fBSKIP\fR, etc.) but
\fIcannot\fR have a \fBSATISFY\fR, \fBMSG\fR, etc. reminder-type clause.
.RE
.TP
.B filedate(s_filename)
Returns the modification date of \fIfilename\fR.  If \fIfilename\fR
does not exist, or its modification date is before the year
\fBbaseyr()\fR, then 1 January of \fBbaseyr()\fR is returned.
.TP
.B filedatetime(s_filename)
Returns the modification date and time of \fIfilename\fR.  If \fIfilename\fR
does not exist, or its modification date is before the year
\fBbaseyr()\fR, then midnight, 1 January of \fBbaseyr()\fR is returned.
.TP
.B filedir()
Returns the directory that contains the current file being
processed.  It may be a relative or absolute pathname, but
is guaranteed to be correct for use in an \fBINCLUDE\fR command as
follows:
.PP
.nf
		INCLUDE [filedir()]/stuff
.fi
.PP
.RS
This includes the file "stuff" in the same directory as the
current file being processed.  Note that this workaround is
no longer necessary because \fBDO stuff\fR will achieve the
same goal.
.PP
Note that if the currently-processing reminders file was specified as
a symbolic link, then \fBfiledir()\fR returns the directory containing
the symbolic link and \fInot\fR the directory containing the target
of the symbolic link.  You should avoid using
symbolic links to files unless both the symbolic link and its target
happen to be in the same directory.
.RE
.TP
.B filename()
Returns (as a \fBSTRING\fR) the name of the current file being processed
by \fBRemind\fR.  Inside included files, returns the name of the
included file.
.TP
.B getenv(s_envvar)
Similar to the \fBgetenv\fR(2) system call.  Returns a string representing
the value of the specified environment variable.  Returns "" if the
environment variable is not defined.  Note that the names of environment
variables are generally case-sensitive; thus, getenv("HOME") is not
the same as getenv("home").
.TP
.B hebdate(i_day, s_hebmon [,idq_yrstart [,i_jahr [,i_aflag]]])
Support for Hebrew dates - see the section "THE HEBREW CALENDAR"
.TP
.B hebday(dq_date)
Support for Hebrew dates - see the section "THE HEBREW CALENDAR"
.TP
.B hebmon(dq_date)
Support for Hebrew dates - see the section "THE HEBREW CALENDAR"
.TP
.B hebyear(dq_date)
Support for Hebrew dates - see the section "THE HEBREW CALENDAR"
.TP
.B hex(i_n)
Returns a \fBSTRING\fR that is the hexadecimal representation of \fIn\fR.
There is no "0x" prefix and any letters in the returned value
are uppper-case.
.TP
.B hour(tq_time)
Returns the hour component of \fItime\fR.
.TP
.B htmlescape(s_str)
Returns a modified copy of \fIstr\fR where "<" is replaced with
"&lt;"; ">" is replaced with "&gt;" and "&" is replaced with "&amp;"
.TP
.B htmlstriptags(s_str)
Returns a modified copy of \fIstr\fR where HTML tags are stripped
out.  The stripping algorithm is fairly naive; the function starts
stripping characters when it encounters a "<" and it stops stripping
when it encounters a ">".
.TP
.B iif(x_test1, x_arg1, [x_test2, x_arg2,...], x_default)
If \fItest1\fR is true, returns \fIarg1\fR.  Otherwise, if \fItest2\fR
is true, returns \fIarg2\fR, and so on.  If all of the \fItest\fR
arguments are false, returns \fIdefault\fR.  Note that only
those arguments needed to determine the final result are
evaluated.  This function accepts an odd number of
arguments - note that prior to version 03.00.05 of \fBRemind\fR, it
accepted 3 arguments only.  The 3-argument version of \fBiif()\fR is
compatible with previous versions of \fBRemind\fR.
.TP
.B index(s_search, s_target [,i_start)
Returns an \fBINT\fR that is the location of \fItarget\fR in the
string \fIsearch\fR.  Note that \fBindex\fR uses \fIbyte\fR positions,
not character positions, so should not be used on non-ASCII strings.  Use
\fBmbindex\fR for non-ASCII strings.
.RS
.PP
The first byte of a string is numbered 1.  If \fItarget\fR does not
exist in \fIsearch\fR, then 0 is returned.
.PP
The optional parameter \fIstart\fR specifies the position in
\fIsearch\fR at which to start looking for \fItarget\fR.
.RE
.TP
.B mbindex(s_search, s_target [,i_start])
Similar to \fBindex()\fR but returns the \fIcharacter\fR position rather
than the \fIbyte\fR position.  Also, \fIstart\fR is interpreted as a
1-based character index rather than a byte index.
.TP
.B isany(arg1 [,arg2, ..., argN]);
Returns 1 if the first argument \fIarg1\fR is equal to any of the
subsequent arguments \fIarg2\fR through \fIargN\fR; returns 0 otherwise.
Also returns 0 if called with only one argument.
.RS
.PP
As an example, the following two expressions are equivalent:
.PP
.nf
        (a == b) || (a == c) || (a == d) || (a == e)

        isany(a, b, c, d, e)
.fi
.RE
.TP
.B isconst(x_any)
Evaluates its argument and then \fIthrows away\fR the value, returning
1 if the expression is constant or 0 if it is non-constant.  Note that
\fBisconst\fR does not take into account the context; if \fIarg\fR is
a constant expression but evaluated in a non-constant context,
\fBisconst\fR will still return 1.  For details about constant vs.
non-constant expressions, see the section "NON-CONSTANT EXPRESSIONS"
.TP
.B isdst([d_date [,t_time]]) \fRor\fB isdst(q_datetime)
Returns a positive number if daylight saving time is in
effect on the specified date and time.  \fIDate\fR
defaults to \fBtoday()\fR and \fItime\fR defaults to midnight.
.RS
.PP
Note that this function is only as reliable as the C run-time library
functions.  It is available starting with version 03.00.07 of \fBRemind\fR.
.RE
.TP
.B isleap(idq_arg)
Returns 1 if \fIarg\fR is a leap year, and 0 otherwise.  \fIArg\fR can
be an \fBINT\fR, \fBDATE\fR or \fBDATETIME\fR object.  If a \fBDATE\fR
or \fBDATETIME\fR is supplied, then the year component is used in the test.
.TP
.B isomitted(dq_date)
Returns 1 if \fIdate\fR is omitted, given the current global \fBOMIT\fR
context.  Returns 0 otherwise.  (If a datetime is supplied, only the
date part is used.)  Note that any local \fBOMIT\fR or \fBOMITFUNC\fR
clauses are \fInot\fR taken into account by this function.
.TP
.B language()
Returns a \fBSTRING\fR naming the compiled-in language supported by
\fBRemind\fR.  \fBRemind\fR used to support compiled-in support for other
languages, but now all localization is done at run-time.  As such,
this function always returns "English".  However, the expression
\fB_("LANGID")\fR returns the two-character ISO 639 language code
of any language pack in effect, assuming the language pack author has
written the localization correctly!
.TP
.B localtoutc(q_datetime)
Given a \fBDATETIME\fR object interpreted in the local time zone, return
a \fBDATETIME\fR object that expresses the same time in UTC.
.TP
.B lower(s_string)
Returns a \fBSTRING\fR with all upper-case characters in \fIstring\fR
converted to lower-case.
.TP
.B max(x_arg1 [,x_arg2...)
Can take any number of arguments, and returns the maximum.  The arguments
can be of any type, but must all be of the same type.  They are compared
as with the > operator.
.TP
.B min(x_arg1 [,x_arg2...)
Can take any number of arguments, and returns the minimum.  The arguments
can be of any type, but must all be of the same type.  They are compared
as with the < operator.
.TP
.B minsfromutc([d_date [,t_time]]) \fRor\fB minsfromutc(q_datetime)
Returns the number of minutes from Universal Time Coordinated
(formerly GMT) to
local time on the specified date and time.  \fIDate\fR defaults to
\fBtoday()\fR and \fItime\fR defaults to midnight.  If local time
is before UTC, the result is negative.  Otherwise, the result is
positive.
.RS
.PP
Note that this function is only as reliable as the C run-time library
functions.  It is available starting with version 03.00.07 of \fBRemind\fR.
.RE
.TP
.B minute(tq_time)
Returns the minute component of \fItime\fR.
.TP
.B mon(dqis_arg)
If \fIarg\fR is of \fBDATE\fR or \fBDATETIME\fR type, returns a string
that names the month component of the date.  If \fIarg\fR is an
\fBINT\fR from 1 to 12, returns a string that names the month.  If \fIarg\fR
is a \fBSTRING\fR, returns the name of the month.  This last case might
sound silly, but for example:
.RS
.PP
.nf
             mon("Mar")
.fi
.PP
will return "March", the full name of the month.
.RE
.TP
.B monnum(dq_date)\fR or \fBmonnum(s_str)\fR
Returns an \fBINT\fR from 1 to 12, representing the month component of
\fIdate\fR.  If a \fBSTRING\fR is supplied rather than a \fBDATE\fR or
\fBDATETIME\fR, then if \fIstr\fR is a valid month name (or minimum
3-character abbreviation of a month name) then the corresponding month
number is returned.  If \fIstr\fR is not a valid month name, then an
error occurs.
.TP
.B moondate(i_phase [,d_date [,t_time]]) \fRor\fB moondate(i_phase, q_datetime)
This function returns the date of the first occurrence of the phase
\fIphase\fR of the moon on or after \fIdate\fR and \fItime\fR.
\fIPhase\fR can range from 0 to 3, with 0 signifying new moon, 1 first
quarter, 2 full moon, and 3 third quarter.  If \fIdate\fR is omitted,
it defaults to \fBtoday()\fR.  If \fItime\fR is omitted, it defaults
to midnight.
.RS
.PP
For example, the following returns the date of the next full moon:
.PP
.nf
		SET fullmoon moondate(2)
.fi
.PP
.RE
.TP
.B moontime(i_phase [,d_date [,t_time]]) \fRor\fB moontime(i_phase, q_datetime)
This function returns the time of the first occurrence of the phase
\fIphase\fR of the moon on or after \fIdate\fR and \fItime\fR.
\fIPhase\fR can range from 0 to 3, with 0 signifying new moon, 1 first
quarter, 2 full moon, and 3 third quarter.  If \fIdate\fR is omitted,
it defaults to \fBtoday()\fR.  If \fItime\fR is omitted, it defaults
to midnight.  \fBMoontime()\fR is intended to be used in conjunction
with \fBmoondate()\fR.  The \fBmoondate()\fR and \fBmoontime()\fR
functions are accurate to within a couple of minutes of the
times in "Old Farmer's Almanac" for Ottawa, Ontario.
.RS
.PP
For example, the following returns the date and time of the next full moon:
.PP
.nf
		MSG Next full moon at [moontime(2)] on [moondate(2)]
.fi
.PP
.RE
.TP
.B moondatetime(i_phase [,d_date [,t_time]]) \fRor\fB moondatetime(i_phase, q_datetime)
This function is similar to \fBmoondate\fR and \fBmoontime\fR, but returns
a DATETIME result.
.TP
.B moonphase([d_date [,t_time]]) \fRor\fB moonphase(q_datetime)
This function returns the phase of the moon on \fIdate\fR and \fItime\fR,
which default to \fBtoday()\fR and midnight, respectively.  The returned
value is an integer from 0 to 359, representing the phase of the moon
in degrees.  0 is a new moon, 180 is a full moon, 90 is first-quarter, etc.
.TP
.B moonrise([d_date])
This function returns a DATETIME result giving the date and time of the
first moonrise on or after midnight on \fIdate\fR.  If \fIdate\fR is not
supplied, it defaults to \fBtoday()\fR.
.RS
.PP
Note that it is not uncommon for a day to have no moonrise, so the date
part of the return value may not be the same as the \fIdate\fR argument.
So if you want a calendar of moonrise times, you could use something
like this:
.PP
.nf
    SET mr moonrise()
    IF datepart(mr) == today()
        REM NOQUEUE [mr] MSG Moon rises at %3.
    ELSE
        REM MSG No moonrise today
    ENDIF
.fi
.PP
.RE
.TP
.B moonrisedir([d_date])
This function returns an INT result giving the direction from which
the moon will rise on the first moonrise on or after midnight on
\fIdate\fR.  If \fIdate\fR is not supplied, it defaults to
\fBtoday()\fR.  The return value ranges from 0 to 359, where 0 is North,
90 is East, 180 is South and 270 is West.
.TP
.B moonset([d_date])
This function is analogous to \fBmoonrise()\fR but returns the DATETIME of
the next moonset on or after midnight on \fIdate\fR.
.TP
.B moonsetdir([d_date])
This function is analogous to \fBmoonrisedir()\fR but returns the
direction of moonset.
.TP
.B multitrig(s_trig1 [,s_trig2, [... s_trigN]])
\fBmultitrig\fR evaluates each string as a trigger, similar to \fBevaltrig\fR,
and returns the \fIearliest\fR trigger date that is on or after \fBtoday()\fR.
\fBmultitrig\fR is similar to \fBtrig\fR but has the following difference:
.RS
.PP
\fBtrig\fR returns the \fIfirst\fR trigger date that would have triggered today,
whereas \fBmultitrig\fR returns the \fIearliest\fR trigger date later than
today, regardless of whether it would have triggered today.
.PP
If no trigger can be computed that is later than \fBtoday()\fR, then
\fBmultitrig\fR returns 1990-01-01.
.PP
Consider the following examples, assuming that today is Sunday, 24 March 2024:
.PP
.nf
   # Returns 1990-01-01 because neither would trigger today
   SET a trig("Mon", "Wed")

   # Returns 2024-03-25 because it's the earlier trigger date
   SET a multitrig("Mon", "Wed")

   # Returns 2024-03-27 because it's the first that would trigger today
   SET a trig("Wed +3", "Mon +3")

   # Returns 2024-03-25 because it's the earlier trigger date
   SET a multitrig("Wed +3", "Mon +3")

   # Returns 1990-01-01 because all triggers have expired
   SET a multitrig("2000", "2022", "1998", "2023")
.fi
.PP
In general, \fBmultitrig\fR works better with the \fBRemind\fR algorithm than
\fBtrig\fR and should be used most of the time.  As an example, this
reminder is issued at the end of each quarter:
.PP
.nf
        REM [multitrig("Mar 31", "Jun 30", "Sep 30", "Dec 31")] +7 MSG \\
        %"End of [ord($Tm/3)] quarter%" is %b.
.fi
.PP
If you want the last working day of each quarter, you could use:
.PP
.nf
        PUSH-OMIT-CONTEXT
        OMIT Sat Sun
        REM [multitrig("Mar ~1", "Jun ~1", "Sep ~1", "Dec ~1")] +7 MSG \\
        %"Last working day of [ord($Tm/3)] quarter%" is %b.
        POP-OMIT-CONTEXT
.fi
.PP
Note that unlike \fBevaltrig\fR, \fBmultitrig\fR always returns a \fBDATE\fR
and never a \fBDATETIME\fR.  Including an \fBAT\fR clause in a trigger
supplied to \fBmultitrig\fR will result in an error.
.RE
.TP
.B ndawn([dq_date])
Returns the time of "nautical dawn" on the specified \fIdate\fR.  If
\fIdate\fR is omitted, defaults to \fBtoday()\fR.  If a \fIdatetime\fR object
is supplied, only the date component is used.
.TP
.B ndusk([dq_date])
Returns the time of "nautical twilight" on the specified \fIdate\fR.  If
\fIdate\fR is omitted, defaults to \fBtoday()\fR.
.TP
.B nonomitted(dq_start, dq_end [, i_step] [,s_wkday...])
This function returns the number of \fInon-\fRomitted days between
\fIstart\fR and \fIend\fR.  If \fIstart\fR is non-omitted, then it is
counted.  \fIend\fR is never counted.
.RS
.PP
Note that if \fIend\fR is less than \fIstart\fR, the arguments
are effectively swapped, so counting always begins from the older
date.
.PP
If the third argument to \fBnonomitted\fR is an \fBINT\fR, then it must
be greater than zero, and is considered to be the \fIstep\fR by which
\fBnonomitted\fR counts.  For example the following expression:
.PP
.nf
        nonomitted('2023-07-01', '2023-07-29', 7)
.fi
.PP
returns the number of non-omitted Saturdays from 2023-07-01 up to
(but not including) 2023-07-29.  (Both 2023-07-01 and 2023-07-29 are
Saturdays.)
.PP
If no \fIstep\fR argument is supplied, then a step of 1 is used.
.PP
In addition to using the global OMIT context, you
can supply additional arguments that are names of weekdays to be
omitted.  However, in a \fBREM\fR command, any local \fBOMITFUNC\fR
clause is \fInot\fR taken into account by this function.
.PP
For example, the following line sets a to 11 (assuming no global OMITs):
.PP
.nf
	set a nonomitted('2007-08-01', '2007-08-16', "Sat", "Sun")
.fi
.PP
because Thursday, 16 August 2007 is the 11th working day (not counting
Saturday and Sunday) after Wednesday, 1 August 2007.
.PP
\fBnonomitted\fR has various uses.  For example, many schools
run on a six-day cycle and the day number is not incremented on holidays.
Suppose the school year starts with Day 1 on 4 September 2007.  The following
reminder will label day numbers in a calendar:
.PP
.nf
   IF today() >= '2007-09-04'
       set daynum nonomitted('2007-09-04', today(), "Sat", "Sun")
       REM OMIT SAT SUN SKIP CAL Day [(daynum % 6) + 1]
   ENDIF
.fi
.PP
Obviously, the answer you get from \fBnonomitted\fR depends on the global
OMIT context.  If you use movable OMITs, you may get inconsistent results.
.PP
Here is a more complex use for \fBnonomitted\fR.  My garbage collection
follows two interleaved 14-day cycles: One Friday, garbage and paper
recycling ("Black Box") are collected.  The next Friday, garbage and
plastic recycling ("Blue Box") are collected.  If any of Monday-Friday
is a holiday, collection is delayed until the Saturday.  Here's a way
to encode these rules:
.PP
.nf
   fset _garbhol(x) wkdaynum(x) == 5 && nonomitted(x-4, x+1) < 5
   REM 12 November 1999 *14 AFTER OMITFUNC _garbhol MSG Black Box
   REM 19 November 1999 *14 AFTER OMITFUNC _garbhol MSG Blue Box
.fi
.PP
Here's how it works:  The _garbhol(x) user-defined function returns 1
if and only if (1) \fIx\fR is a Friday and (2) there is at least one
OMITted day from the previous Monday up to and including the Friday.
.PP
The first REM statement sets up the 14-day black-box cycle.  The AFTER
keyword makes it move collection to the Saturday if _garbhol returns 1.
The second REM statement sets up the 14-day blue-box cycle with a similar
adjustment made by AFTER in conjunction with _garbhol.
.RE
.TP
.B nonconst(x_arg)
Returns the argument \fIarg\fR unchanged, but forces the expression
to be considered \fInon-constant\fR.  For details, see the section
"NON-CONSTANT EXPRESSIONS"
.TP
.B now()
Returns the current system time, as a \fBTIME\fR type.  This may be
the actual time, or a time supplied on the command line.  Note that
in Calendar Mode, \fBnow()\fR always returns 00:00.
.TP
.B ord(i_num)
Returns a string that is the ordinal number \fInum\fR.  For example,
\fBord(2)\fR returns "2nd", and \fBord(213)\fR returns "213th".
.RS
.PP
In order to help with localization, if you define a function called
\fBordx\fR that takes a single parameter, then calling
\fBord\fR(\fIn\fR) invokes \fBordx\fR(\fIn\fR) and returns whatever
it does.  During the callback to \fBordx\fR, \fBRUN\fR will be disabled.
.RE
.TP
.B orthodoxeaster([dqi_arg])
If \fIarg\fR is an \fBINT\fR, then returns the date of Orthodox Easter Sunday
for the specified year.  If \fIarg\fR is a \fBDATE\fR or
\fBDATETIME\fR, then returns the date of the next Orthodox Easter Sunday on or
after \fIarg\fR.  (The time component of a datetime is ignored.)  If \fIarg\fR
is omitted, then it defaults to \fBtoday()\fR.
.RS
.PP
Note that \fBorthodoxeaster\fR computes the Orthodox Easter.  For the Western
Easter date, see \fBeasterdate\fR.
.RE
.TP
.B ostype()
Returns "UNIX".  \fBRemind\fR used to run on OS/2 and MS-DOS, but does not
any longer.
.TP
.B pad(x_arg, s_padstr, i_len [, i_right])
Converts the first argument \fIarg\fR to a string if necessary, and
then if it is shorter than \fIlen\fR bytes, pads to to
\fIlen\fR bytes using as many copies (including partial copies)
of \fIpadstr\fR as necessary.  By default, the string is left-padded,
but if \fIright\fR is supplied and non-zero, the string will
be right-padded.
.RS
.PP
Here are some examples:
.PP
.nf
    pad(3, "0", 2)        -->  "03"
    pad(465, "0", 2)      -->  "465"
    pad("foo", " ", 5)    -->  "  foo"
    pad("foo", " ", 5, 1) -->  "foo  "
    pad("foo", "bar", 11) -->  "barbarbafoo"
.fi
.RE

.TP
.B mbpad(x_arg, s_padstr, i_len [, i_right])
This is the multibyte counterpart to \fBpad\fR.  The length is
specified in characters rather than bytes.  Use \fBmbpad\fR rather
than \fBpad\fR if either of the strings contains non-ASCII characters.
.TP
.B plural(i_num [,s_str1 [,s_str2]])
Can take from one to three arguments.  If one argument is supplied, returns
"s" if \fInum\fR is not 1, and "" if \fInum\fR is 1.
.RS
.PP
If two arguments are supplied, returns \fIstr1\fR + "s" if \fInum\fR is
not 1.  Otherwise, returns \fIstr1\fR.
.PP
If three arguments are supplied, returns \fIstr1\fR if \fInum\fR is 1, and
\fIstr2\fR otherwise.
.RE
.TP
.B psmoon(i_phase [,i_size [,s_note [,i_notesize]]])
[DEPRECATED] Returns a \fBSTRING\fR consisting of PostScript code to
draw a moon in the upper-left hand corner of the calendar box.
\fIPhase\fR specifies the phase of the moon, and is 0 (new moon), 1
(first quarter), 2 (full moon) or 3 (third quarter).  If \fIsize\fR is
specified, it controls the radius of the moon in PostScript units
(1/72 inch.)  If it is not specified or is negative, the size of the
day-number font is used.
.PP
.PP
.RS
For example, the following four lines place moon symbols on the PostScript
calendar:
.PP
.nf
		REM [moondate(0)] PS [psmoon(0)]
		REM [moondate(1)] PS [psmoon(1)]
		REM [moondate(2)] PS [psmoon(2)]
		REM [moondate(3)] PS [psmoon(3)]
.fi
.PP
If \fInote\fR is specified, the text is used to annotate the moon
display.  The font is the same font used for calendar entries.  If
\fInotesize\fR is given, it specifies the font size to use for the
annotation, in PostScript units (1/72 inch.)  If \fInotesize\fR is not
given, it defaults to the size used for calendar entries.  (If you annotate
the display, be careful not to overwrite the day number -- \fBRemind\fR
does not check for this.)  For example, if you want the time of each new
moon displayed, you could use this in your reminder script:
.PP
.nf
	REM [moondate(0)] PS [psmoon(0, \-1, moontime(0)+"")]
.fi
.PP
Note how the time is coerced to a string by concatenating the null string.
.RE
.TP
\fBpsshade(i_gray)\fR or \fBpsshade(i_red, i_green, i_blue)\fR
[DEPRECATED] Returns a \fBSTRING\fR that consists of PostScript commands to
shade a calendar box.  \fINum\fR can range from 0 (completely black)
to 100 (completely white.)  If three arguments are given, they specify
red, green and blue intensity from 0 to 100.
Here's an example of how to use this:
.RS
.PP
.nf
		REM Sat Sun PS [psshade(95)]
.fi
.PP
The above command emits PostScript code to lightly shade the boxes
for Saturday and Sunday in a PostScript calendar.
.PP
Note that \fBpsmoon\fR and \fBpsshade\fR are deprecated; instead
you should use the SPECIAL SHADE and SPECIAL MOON reminders
as described in "Out-of-Band Reminders."
.RE
.TP
.B realcurrent()
Returns (as a DATETIME) the true date and time of day as provided by
the operating system.  This is in contrast to \fBcurrent()\fR, which
may return a time supplied on the command line.
.TP
.B realnow()
Returns the true time of day as provided by the operating system.
This is in contrast to \fBnow()\fR, which may return a time supplied
on the command line, or 00:00 in Calendar Mode.
.TP
.B realtoday()
Returns the date as provided by the operating system.  This is in contrast to
\fBRemind\fR's concept of "today", which may be changed if it is running
in calendar mode, or if a date has been supplied on the command line.
.TP
.B rows()
If either standard output or standard error is a TTY, returns the
height of the terminal in rows.  If neither standard output nor
standard error is a TTY, attempts to open "/dev/tty" to obtain the
terminal size.  If this fails, returns -1.
.TP
.B sgn(i_num)
Returns \-1 if \fInum\fR is negative, 1 if \fInum\fR is positive,
and 0 if \fInum\fR is zero.
.TP
.B shell(s_cmd [,i_maxlen])
Executes \fIcmd\fR as a system command, and returns the first 511
characters of output resulting from \fIcmd\fR.  Any whitespace
character in the output is converted to a space.  Note that if \fBRUN
OFF\fR has been executed, or the \fB\-r\fR command-line option has
been used, \fBshell()\fR will result in an error, and \fIcmd\fR will
not be executed.
.RS
.PP
When \fBshell\fR runs \fIcmd\fR, it arranges for \fIcmd\fR's standard
input file descriptor to be connected to /dev/null.
.PP
If \fImaxlen\fR is specified, then \fBshell()\fR returns the first
\fImaxlen\fR characters of output (rather than the first 511).  If
\fImaxlen\fR is specified as a negative number, then it defaults to
the value of the system variable \fB$MaxStringLen\fR.
.RE
.TP
.B shellescape(s_str)
Returns \fIstr\fR with all shell metacharacters such as " ", "*", etc
escaped with a backslash.  For example:
.PP
.nf
        SET a shellescape("a b*? c&d$e")
.fi
.RS
.PP
will set \fBa\fR to:
.RE
.PP
.nf
        "a\\ b\\*\\?\\ c\\&d\\$e"
.fi

.TP
.B slide(d_start, i_amt [, i_step] [,s_wkday...])
This function is the inverse of \fBnonomitted\fR.  It adds \fIamt\fR
(which can be negative) chunks of \fIstep\fR days to \fIstart\fR,
\fInot counting omitted days\fR.  If \fIstep\fR is not supplied, then
it is assumed to be 1.  Note that only every \fIstep\fRth day is
tested to see if it is omitted.  The optional \fIwkday\fR arguments
are additional weekday names to omit.
.RS
.PP
Consider this example:
.PP
.nf
	OMIT 14 May 2009
	SET a slide('2009-05-13', 5, "Sat", "Sun")
.fi
.PP
In this case, \fIa\fR is set to 2009-05-21.  That's because we slide forward
by 5 days, not including Thursday, May 14 or Saturday and Sunday,
May 16 and 17.  You can go backwards, too, so:
.PP
.nf
	OMIT 14 May 2009
	SET a slide('2009-05-21', \-5, "Sat", "Sun")
.fi
.PP
takes \fIa\fR back to 2009-05-13.
.PP
Now consider this example:
.PP
.nf
        OMIT 14 May 2009
        SET a slide('2009-05-07', 2, 7)
.fi
.PP
This sets \fIa\fR to '2009-05-28' because we skip ahead two weeks, not
counting a week where the day we land on happens to be omitted.  Contrast with
this:
.PP
.nf
        OMIT 13 May 2009
        SET a slide('2009-05-07', 2, 7)
.fi
.PP
which sets \fIa\fR to '2009-05-21'.  Although 2009-05-13 is omitted, we
don't "land" on it as we step forward in chunks of 7 days, so we never
see that it is omitted.
.RE
.TP
.B soleq(i_which [, dqi_start])
The \fBsoleq\fR function computes solstices and equinoxes.  The \fIwhich\fR
parameter ranges from 0 to 3, and specifies which event we are interested
in: 0 is the March equinox; 1 is the June solstice; 2 is the September
equinox and 3 is the December solstice.
.RS
.PP
The optional \fIstart\fR parameter can either be an integer specifying the
year of the event we are interested in, or a \fBDATE\fR or \fBDATETIME\fR
object; if the latter, then \fBsoleq\fR returns the first event on or
after the date part of the \fIstart\fR parameter (it ignores the time
component if \fIstart\fR is a \fBDATETIME\fR.)  If \fIstart\fR is
not supplied, then it defaults to \fBtoday()\fR.
.PP
The return value of \fBsoleq()\fR is a \fBDATETIME\fR object specifying
the date and time of the solstice or equinox in the local time zone.  It
should be accurate to within 3 minutes or so in the worst case.
.PP
See the included file \fB$SysInclude/seasons.rem\fR for examples of how
to use \fBsoleq()\fR.
.RE
.TP
.B stdout()
Returns a string representing where Remind's standard output is going.
The return values are one of the following: "TTY" if standard-output
is a terminal, "BLOCKDEV" if it is a block device (very unlikely),
"CHARDEV" if it is a character device (e.g., /dev/null), "DIR" if it
is a directory (very unlikely), "PIPE" if it is a pipe or FIFO,
"SYMLINK" if it is a symlink (very unlikely), "SOCKET" if it is a
socket, or "UNKNOWN" if it could not be determined.
.RS
.PP
The purpose of \fBstdout()\fR is mostly to distinguish between TTY
and non-TTY output; you may wish to change or disable colors if the
output is not going to a TTY.
.RE
.TP
.B strlen(s_str)
Returns the length of \fIstr\fR in bytes.  If the length of \fIstr\fR
is too large to represent as an integer, emits a "Number too high"
error.  Note that \fBstrlen\fR returns the number of \fIbytes\fR in
the string, not the number of \fIcharacters\fR.  These numbers are the
same for ASCII strings, but may be different for UTF-8 strings.
.TP
.B mbstrlen(str)
Similar to \fBstrlen\fR, but returns the length of the string in
\fIcharacters\fR rather than \fIbytes\fR and is thus safe for use
on multi-byte strings.
.TP
.B substr(s_str, i_start [,i_end])
Returns a \fBSTRING\fR consisting of all bytes in \fIstr\fR from
\fIstart\fR up to and including \fIend\fR.  Bytes are numbered
from 1.  If \fIend\fR is not supplied, then it defaults to the length
of \fIstr\fR.  Because \fBsubstr\fR uses \fIbyte\fR indexes rather than
\fIcharacter\fR indexes, it should not be used on multi-byte strings.
.TP
.B mbsubstr(s_str, i_start [,i_end])
Similar to \fBsubstr\fR but uses \fIcharacter\fR indexes rather than
\fIbyte\fR indexes, and is thus safe for use on multi-byte strings.
.TP
.B sunrise([dq_date])
Returns a \fBTIME\fR indicating the time of sunrise on the specified
\fIdate\fR (default \fBtoday()\fR.)  In high latitudes, there
may be no sunrise on a particular day, in which case \fBsunrise()\fR
returns the \fBINT\fR 0 if the sun never sets, or 1440 if it never rises.
.TP
.B sunset([dq_date])
Returns a \fBTIME\fR indicating the time of sunset on the specified
\fIdate\fR (default \fBtoday()\fR.)  In high latitudes, there
may be no sunset on a particular day, in which case \fBsunset()\fR
returns the \fBINT\fR 0 if the sun never rises, or 1440 if it never
sets.
.RS
.PP
The functions \fBsunrise()\fR and \fBsunset()\fR are based on
an algorithm in "Almanac for Computers for the year 1978" by
L. E. Doggett, Nautical Almanac Office, USNO.  They require
the latitude and longitude to be specified by setting the appropriate
system variables.  (See "System Variables".)  The sun functions
should be accurate to within about 4 minutes for latitudes lower
than 60 degrees.  The functions are available starting from version
03.00.07 of \fBRemind\fR.
.RE
.TP
.B time(i_hr, i_min)
Creates a \fBTIME\fR with the hour and minute components specified by
\fIhr\fR and \fImin\fR.
.TP
.B timepart(tq_datetime)
Returns a \fBTIME\fR object representing the time portion of
\fIdatetime\fR.
.TP
.B timezone([dq_datetime])
Returns a string representing the local time zone name of the given
\fBDATETIME\fR.  If no argument is supplied, \fBRemind\fR uses the
value of \fBcurrent()\fR.  If a \fBDATE\fR rather than \fBDATETIME\fR
is supplied, \fBRemind\fR uses a time part of 00:00.
.TP
.B today()
Returns \fBRemind\fR's notion of "today."  This may be the actual
system date, or a date supplied on the command line, or (in Calendar
Mode) 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:
.PP
.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 has 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
Monday.  Because trig("Mon +7") always returns true,
the logical-OR operator does not bother evaluating trig("Fri +7") which
therefore does not set \fBtrig()\fR.
.PP
\fBImportant Note\fR:  Because \fBtrig()\fR always returns an absolute
date, it will \fBnot\fR work properly with a \fBSATISFY\fR clause.
Consider this reminder:
.PP
.nf
    REM [trig("Mar", "Apr")] SATISFY [$Td == 15] MSG 15 Mar or April
.fi
.PP
If we run \fBRemind\fR on 5 March 2022, we might expect the trigger
date to be calculated as 15 March 2022... but that's not what happens.
Instead, the \fBtrig\fR function is evaluated first, and it returns
2022-03-05.  So as far as \fBRemind\fR is concerned, the REM statement
becomes:
.PP
.nf
    REM 2022-03-05 SATISFY [$Td == 15] MSG 15 Mar or April
.fi
.PP
and the SATISFY expression is never true.  So: \fIDo not mix
trig() and SATISFY\fR.
.RE
.TP
.B trigdate()
Returns the calculated trigger date of the last \fBREM\fR
or \fBIFTRIG\fR command.  If used
in the \fIbody\fR of a \fBREM\fR command, returns that command's trigger date.
If the most recent \fBREM\fR command did not yield a computable trigger
date, returns the integer 0.
.TP
.B trigdatetime()
Similar to trigdate(), but returns a \fBDATETIME\fR if the most recent
triggerable \fBREM\fR command had an \fBAT\fR clause.  If there was no
\fBAT\fR clause, returns a \fBDATE\fR.  If no trigger could be computed,
returns the integer 0.  See "MULTI-DAY EVENTS" for more information.
.TP
.B trigeventstart()
Returns a \fBDATETIME\fR representing the start of the most recent
triggerable \fBREM\fR command that had an \fBAT\fR clause.  For events
without a \fBDURATION\fR or that do not span multiple days, returns
the same as \fBtrigdatetime()\fR.  If the \fBREM\fR command did not
have an \fBAT\fR clause, returns the integer -1 (and differs from
\fBtrigdatetime()\fR in this respect.)  See "MULTI-DAY EVENTS" for more
information.
.TP
.B trigeventstarttz()
Similar to \fBtrigeventstart()\fR but returns the DATETIME in the time
zone specified by a TZ clause, if one was present.  If no TZ clause
was present, returns the same value as \fBtrigeventstart()\fR.
.TP
.B trigeventduration()
Returns a \fBTIME\fR representing the duration of the most recent
triggerable \fBREM\fR command that had an \fBAT\fR and a
\fBDURATION\fR clause.  If the event does not span multiple days,
returns the same thing as \fBtrigduration()\fR.  If the \fBREM\fR
command lacked an \fBAT\fR or \fBDURATION\fR clause, returns -1.  See
"MULTI-DAY EVENTS" for more information.
.TP
.B trigback()
Returns the "back" amount of the last \fBREM\fR or \fBIFTRIG\fR command.
Returns a positive integer N if the "back" is of the form -N, or a negative
integer if it is of the form --N.  If there is no "back", then returns 0.
.TP
.B trigbase()
Returns the "base" date of the last \fBREM\fR or \fBIFTRIG\fR command.
If the trigger specification includes \fIall three\fR of day, month
and year, then the base date is the date formed from those components.
If the trigger specification lacks one of those components, then 0 is
returned.
.RS
.PP
Here is an example of how \fBtrigbase()\fR might be used:
.PP
.nf
        REM 2025-05-05 *7 UNTIL 2025-05-26 \\
           MSG Meeting: week #[(trigdate() - trigbase())/trigrep()+1]
.fi
.PP
On 2025-05-05, it would print: "Meeting: week #1".  On 2025-05-12,
it would print: "Meeting: week #2" and so on.
.RE
.TP
.B trigdelta()
Returns the "delta" amount of the last \fBREM\fR or \fBIFTRIG\fR command.
Returns a positive integer N if the "delta" is of the form +N, or a negative
integer if it is of the form ++N.  If there is no "delta", then returns 0.
.TP
.B trigtimedelta()
Similar to \fBtrigdelta()\fR, but returns the delta used in the
\fBAT\fR clause of a timed reminder.
.TP
.B trigrep()
Returns the "repeat" amount of the last \fBREM\fR or \fBIFTRIG\fR
command.  Returns a positive integer N if the "repeat" is of the form
*N.  If there is no "repeat", then returns 0.
.TP
.B trigtimerep()
Similar to \fBtrigrep()\fR, but returns the repeat used in the \fBAT\fR clause
of a timed reminder.
.TP
.B trigtz()
If a \fBTZ\fR clause was used in the last \fBREM\fR or \fBIFTRIG\fR
command, returns the time zone name.  Otherwise returns the empty
string.
.TP
.B trigduration()
Returns (as a TIME type) the \fBDURATION\fR parameter of a timed
reminder.  If there is no \fBDURATION\fR parameter, returns the
integer -1.  See "MULTI-DAY EVENTS" for more information.
.TP
.B trigpriority()
Returns the \fBPRIORITY\fR of the last \fBREM\fR or \fBIFTRIG\fR command.
.TP
.B triguntil()
Returns (as a \fBDATE\fR type) the \fBUNTIL\fR parameter of the last
\fBREM\fR or \fBIFTRIG\fR command.  If there was no \fBUNTIL\fR
parameter, returns the integer -1.  If there is a \fBTHROUGH\fR parameter,
that will be returned by \fBtriguntil()\fR since "THROUGH yyyy-mm-dd" is simply
syntactic sugar for "*1 UNTIL yyyy-mm-dd".
.TP
.B trigscanfrom()
Returns (as a \fBDATE\fR type) the \fBSCANFROM\fR parameter of the last \fBREM\fR
or \fBIFTRIG\fR command.  If there was no \fBSCANFROM\fR parameter, returns
the integer -1.  Note that \fBFROM\fR and \fBSCANFROM\fR interact; a reminder that
has a "FROM yyyy-mm-dd" parameter will act as if it has a \fBSCANFROM\fR parameter
whose value is the maximum of "yyyy-mm-dd" and today.
.TP
.B trigfrom()
Returns (as a \fBDATE\fR type) the \fBFROM\fR parameter of the last \fBREM\fR or
\fBIFTRIG\fR command.  If there was no \fBFROM\fR parameter, returns the integer -1.
.TP
.B triginfo(s_header)
Returns a \fBSTRING\fR that is the INFO item associated with the header
\fIheader\fR.  The header should \fInot\fR contain a colon.  Header name
comparisons are case-insensitive.
.RS
.PP
For example, the following will assign "At home" to the variable a and
the empty string to variable b:
.PP
.nf
        REM INFO "Location: At home" MSG test
        SET a triginfo("location")
        SET b triginfo("no_such_header")
.fi
.PP
.RE
.TP
.B trigistodo()
Returns 1 if the last \fRREM\fR command was a \fBTODO\fR type or 0 if not.
.TP
.B trigcompletethrough()
Returns a \fBDATE\fR object that is the COMPLETE-THROUGH date of the most
recent \fBREM\fR command.  If there was no COMPLETE-THROUGH date,
returns the \fBINT\fR 0.
.TP
.B trigmaxoverdue()
Returns an \fBINT\fR that is the MAX-OVERDUE value of the most recent \fBREM\fR
command.  If there was no MAX-OVERDUE clause, returns -1.
.TP
.B trigger(d_date [,t_time [,i_utcflag]]) \fRor\fB trigger(q_datetime [,i_utcflag])
Returns a string suitable for use in a \fBREM\fR command or a
\fBSCANFROM\fR or UNTIL clause, allowing you to calculate trigger
dates in advance.  Note that in earlier versions of \fBRemind\fR,
\fBtrigger\fR was required to convert a date into something the
\fBREM\fR command could consume.  However, in this version of
\fBRemind\fR, you can omit it.  Normally, the \fIdate\fR and
\fItime\fR are the local date and time; however, if \fIutcflag\fR is
non-zero, the \fIdate\fR and \fItime\fR are interpreted as UTC times,
and are converted to local time.  Examples:
.RS
.PP
     trigger('1993/04/01')
.PP
returns "1 April 1993",
.PP
     trigger('1994/08/09', 12:33)
.PP
returns "9 August 1994 AT 12:33", as does:
.PP
     trigger('1994/08/09@12:33').
.PP
Finally:
.PP
     trigger('1994/12/01', 03:00, 1)
.PP
returns "30 November 1994 AT 22:00" for EST, which is 5 hours behind UTC.
The value for your time zone may differ.
.PP
\fBtrigger()\fR will \fInever\fR return a date earlier than "1 January 1990"
even if the UTC flag dictates that it should.  So do not use it for reminders
before about 2 January 1990 in your local time zone.  I do not anticipate this
restriction being a real problem.
.RE
.TP
.B trigtags()
Returns a comma-separated list of the TAGs associated with the most recent
\fBREM\fR command that was triggered.  Returns the empty string if there
were no TAGs.  If there are multiple tags, they are each separated by
a single comma, not a comma and a space.
.TP
.B trigtime()
Returns the time of the last \fBREM\fR command with an \fBAT\fR clause
\fIin the system default time zone\fR.  If the last \fBREM\fR did not
have an \fBAT\fR clause, returns the integer 0.  If a \fBREM\fR
command has an \fBAT\fR clause with a \fBDURATION\fR, then you can
compute the end time as \fBtrigtime() + trigduration()\fR.
.TP
.B trigtimetz()
Similar to \fBtrigtime()\fR but returns the time in the time zone specified
by a TZ clause, if one was present.  If no TZ clause was present, returns
the same value as \fBtrigtime()\fR.
.TP
.B trigvalid()
Returns 1 if the value returned by \fBtrigdate()\fR is valid for the most
recent \fBREM\fR command, or 0 otherwise.  Sometimes \fBREM\fR commands
cannot calculate a trigger date.  For example, the following \fBREM\fR
command can never be triggered:
.PP
.nf
		REM Mon OMIT Mon SKIP MSG Impossible!
.fi
.PP
.TP
.B typeof(x_arg)
Returns "STRING", "INT", "DATE", "TIME" or "DATETIME", depending on the type of \fIarg\fR.
.TP
.B tzconvert(q_datetime, s_srczone [,s_dstzone])
Converts \fBdatetime\fR from the time zone named by \fBsrczone\fR to
the time zone named by \fBdstzone\fR.  If \fBsrczone\fR is the empty
string, then the default system time zone is used as the source zone.
If \fBdstzone\fR is omitted or is the empty string, the default system
time zone is used as the destination zone.  The return value is a
DATETIME.  Time zone names are system-dependent; consult your
operating system for legal values.  Here is an example:
.RS
.PP
.nf
    tzconvert('2007-07-08@01:14', "Canada/Eastern", "Canada/Pacific")

          returns

    2007-07-07@22:14
.fi
.PP
If your system includes the directory /usr/share/zoneinfo, \fBRemind\fR
will warn you if you use an invalid time zone name for \fBsrczone\fR or
\fBdstzone\fR.  To suppress these warnings, add a "!" to the beginning
of the time zone name.
.RE
.PP
.TP
.B upper(s_string)
Returns a \fBSTRING\fR with all lower-case characters in \fIstring\fR
converted to upper-case.
.TP
.B utctolocal(q_datetime)
Given a \fBDATETIME\fR object interpreted in UTC, return a
\fBDATETIME\fR object that expresses the same time in the local time
zone.
.TP
.B value(s_varname [,x_default])
Returns the value of the specified variable.  For example, value("X"+"Y")
returns the value of variable XY, if it is defined.  If XY is not defined,
an error results.
.RS
.PP
However, if you supply a second argument, it is returned if the \fIvarname\fR
is not defined.  The expression value("XY", 0) will return 0 if XY is not
defined, and the value of XY if it is defined.  Note that \fBvalue\fR
evaluates the second argument lazily; it is \fInot\fR evaluated if
\fIvarname\fR is defined.
.RE
.TP
.B version()
Returns a string specifying the version of \fBRemind\fR.  For version
@VERSION@, returns "@VERSION@".  It is guaranteed that as new versions of
\fBRemind\fR are released, the value returned by \fBversion()\fR will
strictly increase, according to the rules for string ordering.
.TP
.B weekno([dq_date, [i_wkstart, [i_daystart]]])
Returns the week number of the year.  If no arguments are supplied,
returns the ISO 8601 week number for \fBtoday()\fR.  If one
argument \fIdate\fR is supplied, then returns the ISO 8601 week
number for that date.  If two arguments are supplied, then
\fIwkstart\fR must range from 0 to 6, and represents the first
day of the week (with 0 being Sunday and 6 being Saturday.).  If
\fIwkstart\fR is not supplied, then it defaults to 1.  If the
third argument \fIdaystart\fR is supplied, then it specifies
when Week 1 starts.  If \fIdaystart\fR is less than or equal to 7,
then Week 1 starts on the first \fIwkstart\fR on or after
January \fIdaystart\fR.  Otherwise, Week 1 starts on the first
\fIwkstart\fR on or after December \fIdaystart\fR.  If omitted,
\fIdaystart\fR defaults to 29 (following the ISO 8601 definition.)
.TP
.B wkday(dqi_arg)
If \fIarg\fR is a \fBDATE\fR or \fBDATETIME\fR, returns a string
representing the day of the week of the date.  If \fIarg\fR is an
\fBINT\fR from 0 to 6, returns the corresponding weekday ("Sunday" to
"Saturday").
.TP
.B wkdaynum(dq_date)\fR or \fBwkdaynum(s_str)\fR
Returns a number from 0 to 6 representing the day-of-week of the
specified \fIdate\fR.  (0 represents Sunday, and 6 represents
Saturday.)  If a \fBSTRING\fR is supplied, then if \fIstr\fR is a valid
weekday name (or minimum 3-character abbreviation thereof) then the
corresponding weekday number is returned.  If \fIstr\fR is not a valid
weekday name, then an error occurs.
.TP
.B year(dq_date)
Returns a \fBINT\fR that is the year component of \fIdate\fR.

.SH MACHINES WITH A 32-BIT TIME_T TYPE
Internally, the standard C library represents times as a \fBtime_t\fR
type.  This is a signed integer type that counts seconds since
midnight, 1 January 1970 UTC.  If the \fBtime_t\fR type is only
32 bits in size, then the C library cannot represent times after
19 January 2038 at 03:14:07 UTC.
.PP
To work around this limitation, \fBRemind\fR will "fold" years greater than 2037
to a smaller year that begins on the same day and has the same number of
days.  This results in a year that's very likely to have the same
daylight saving rules as the original year, unless the rules have changed
in the interim (in which case the rule change could not even be represented
on a 32-bit machine, so it's moot.)
.PP
\fBRemind\fR then does UTC-to-local or local-to-UTC conversions with the folded
year, and then post-conversion corrects it back.  This should give
correct results for astronomical functions and conversions between
local and UTC time, providing the daylight saving time rules have not
changed between the folded year and the original year.
.PP
Note that the $FoldYear system variable is no longer that useful; \fBRemind\fR
\fIalways\fR folds years if it's necessary on a 32-bit system.  You can
set $FoldYear to 1 to force \fBRemind\fR to fold years even on a 64-bit system,
but that's useful only for testing and not for production.

.SH MULTI-DAY EVENTS

If you specify a start time with \fBAT\fR and a duration with
\fBDURATION\fR, you can create events that span multiple days.
Consider these two REM statements:
.PP
.nf
    REM 1991-02-13 AT 16:00 DURATION 72:00 MSG 72-hour event
    REM 1991-02-13 THROUGH 1991-02-16 AT 16:00 MSG Four events
.fi
.PP
The first statement creates a \fIsingle\fR event that starts on
13 February 1991 at 16:00 and runs through 16 February 1991 at 16:00
.PP
The second statements creates \fIfour separate\fR events that start
at 16:00 on 13, 14, 15 and 16 February 1991 and have indefinite duration.
.PP
\fBRemind\fR handles multi-day events specially.  These are the rules:
.PP
On the \fIfirst\fR day of a multi-day event, \fBtrigdatetime()\fR will
return the starting date and time of the event, and \fBtrigduration()\fR
will return the original DURATION.
.PP
On each \fIsubsequent\fR day of a multi-day event, \fBtrigdatetime()\fR
will return midnight on the day in question, and \fBtrigduration()\fR
will return the \fIremaining\fR duration.  Consider this example:
.PP
.nf
    #!/bin/sh
    remind - 12 feb 1991 '*6' <<'EOF'
    BANNER %
    REM 1991-02-13 AT 16:00 DURATION 72:00 SATISFY 1
    set a trigdatetime()
    set b trigduration()
    set c trigeventstart()
    set d trigeventduration()
    MSG now=[today()] dt=[a] dur=[b] estart=[c] edur=[d]%
    EOF
.fi
.PP
The output is:
.PP
.nf
now=1991-02-12 dt=1991-02-13@16:00 dur=72:00 estart=1991-02-13@16:00 edur=72:00
now=1991-02-13 dt=1991-02-13@16:00 dur=72:00 estart=1991-02-13@16:00 edur=72:00
now=1991-02-14 dt=1991-02-14@00:00 dur=64:00 estart=1991-02-13@16:00 edur=72:00
now=1991-02-15 dt=1991-02-15@00:00 dur=40:00 estart=1991-02-13@16:00 edur=72:00
now=1991-02-16 dt=1991-02-16@00:00 dur=16:00 estart=1991-02-13@16:00 edur=72:00
now=1991-02-17 dt=1991-02-13@16:00 dur=72:00 estart=-1 edur=-1
.fi
.PP
As you see, the \fBtrigdatetime()\fR and \fBtrigduration()\fR functions
return the start time and duration of the \fIremaining\fR portion of
a multi-day event, whereas \fBtrigeventstart\fR and \fBtrigeventduration\fR
always return the original start and duration of the multi-day event.  Note also
that the return value for expired reminders is not reliable; the fact
that \fBtrigeventstart\fR and \fBtrigeventduration\fR return -1 in that case
is an implementation artifact.
.PP
.B SELF-OVERLAPPING EVENTS
.PP
A multi-day event has the possibility of "overlapping itself".  When this
happens, \fBRemind\fR prefers the \fIlater\fR event (only one copy of
an event is ever triggered for a given date.)  Consider this example:
.PP
.nf
   #!/bin/sh
   remind - '*5' 10 Feb 1991 <<'EOF'

   BANNER %
   REM MON at 0:00 DURATION 192:0 MSG [today()] [trigeventstart()] [trigduration()]%

   EOF
.fi
.PP
The output is:
.PP
.nf
   1991-02-10 1991-02-04@00:00 48:00
   1991-02-11 1991-02-11@00:00 192:00
   1991-02-12 1991-02-11@00:00 168:00
   1991-02-13 1991-02-11@00:00 144:00
   1991-02-14 1991-02-11@00:00 120:00
.fi
.PP
Although the event from 1991-02-04 still has 24 hours left on 1991-02-11,
the fresh occurrence on 1991-02-11 takes precedences and is the one that
is triggered.
.PP
I do not recommend constructing self-overlapping multi-day events.
.PP
.SH EXPRESSION PASTING
.PP
An extremely powerful feature of \fBRemind\fR is its macro capability,
or "expression pasting."
.PP
In almost any situation where \fBRemind\fR is not expecting an expression,
you can "paste" an expression in.  To do this, surround the expression
with square brackets.  For example:
.PP
.nf
	REM [mydate] MSG foo
.fi
.PP
This evaluates the expression "mydate", where "mydate" is
presumably some pre-computed variable, and then "pastes" the result
into the command-line for the parser to process.
.PP
If you want a literal "[" character for some reason, simply use "[[".  For
example:
.PP
.nf
        REM MSG Here are [[square] brackets!
.fi

.PP
A formal description of this is:  When \fBRemind\fR encounters a
"pasted-in" expression, it evaluates the expression, and coerces the
result to a \fBSTRING\fR.  It then substitutes the string for the
pasted-in expression, and continues parsing.  Note, however, that
expressions are evaluated only once, not recursively.  Thus, writing:
.PP
.nf
	["[a+b]"]
.fi
.PP
causes \fBRemind\fR to read the token "[a+b]".  It does not interpret
this as a pasted-in expression.
.PP
You can use expression pasting almost anywhere.  However, there are a few
exceptions:
.TP
o
If \fBRemind\fR is expecting an expression, as in the \fBSET\fR command,
or the \fBIF\fR command, you should \fBnot\fR include square brackets.
For example, use:
.PP
.nf
		SET a 4+5
.fi
and not:
.nf
		SET a [4+5]
.fi
.TP
o
You cannot use expression pasting for the first token on a line.
For example, the following will not work:
.PP
.nf
		["SET"] a 1
.fi
.RS
.PP
This restriction is because \fBRemind\fR must be able to unambiguously
determine the first token of a line for the flow-control commands (to
be discussed later.)
.PP
In fact, if \fBRemind\fR cannot determine the first token on a line, it
assumes that it is a \fBREM\fR command.  If expression-pasting is used,
\fBRemind\fR assumes it is a \fBREM\fR command.  Thus, the following
three commands are equivalent:
.PP
.nf
		REM 12 Nov 1993 AT 13:05 MSG BOO!
		12 Nov 1993 AT 13:05 MSG BOO!
		[12] ["Nov " + 1993] AT [12:05+60] MSG BOO!
.fi
.RE
.TP
o
You cannot use expression-pasting to determine the type (\fBMSG\fR,
\fBCAL\fR, etc.) of a \fBREM\fR command.  You can paste expressions
before and after the \fBMSG\fR, etc. keywords, but cannot do something like
this:
.RS
.PP
.nf
        REM ["12 Nov 1993 AT 13:05 " + "MSG" + " BOO!"]
.fi
.PP
However, as an escape hatch, the sequence \fBSPECIAL\fR \fItype\fR
means the same thing as just \fItype\fR where \fItype\fR is one
of MSG, MSF, RUN, CAL, PS and PSFILE.  This lets you do something
like this:
.PP
.nf
        SET type "MSG"
        REM 12 Nov 2024 SPECIAL [type] Hello
.fi
.PP
You can use this to control the types of your reminders based on variables
you set, how \fBRemind\fR is invoked, etc.
.RE
.PP
.B COMMON PITFALLS WITH EXPRESSION PASTING
.PP
Remember that extra spaces are not inserted when an expression is
pasted.  Thus, something like:
.PP
.nf
	REM[expr]MSG[expr]
.fi
.PP
will probably fail.
.PP
If you use an expression to calculate a \fIdelta\fR or \fIback\fR,
ensure that the result is a positive number.  Something like:
.PP
.nf
	REM +[mydelta] Nov 12 1993 MSG foo
.fi
.PP
will fail if \fImydelta\fR happens to be negative.
.PP
.SH FLOW CONTROL COMMANDS
.PP
\fBRemind\fR has commands that control the flow of a reminder script.
Normally, reminder scripts are processed sequentially.  However,
\fBIF\fR and related commands allow you to process files conditionally,
and skip sections that you don't want interpreted.
.PP
.B THE IF COMMAND
.PP
The \fBIF\fR command has the following form:
.PP
.nf
	IF expr
		t-command
		t-command...
	ELSE
		f-command
		f-command...
	ENDIF
.fi
.PP
Note that the commands are shown indented for clarity.  Also, the \fBELSE\fR
portion can be omitted.  \fBIF\fR commands can be nested up to a depth
of 64, across \fIall\fR levels of INCLUDE.
.PP
If the \fIexpr\fR evaluates to a non-zero \fBINT\fR, a \fBDATE\fR that
is not 1990-01-01, a \fBTIME\fR that is not 00:00, a \fBDATETIME\fR
that is not 1990-01-01@00:00, or a non-null \fBSTRING\fR, then the
\fBIF\fR portion is considered true, and the \fIt-commands\fR are
executed.  If \fIexpr\fR evaluates to zero or null, then the
\fIf-commands\fR (if the \fBELSE\fR portion is present) are executed.
.PP
Examples:
.PP
.nf
	IF defined("want_hols")
		INCLUDE /usr/share/remind/holidays
	ENDIF

	IF today() > '1992/2/10'
		set missed_ap "You missed it!"
	ELSE
		set missed_ap "Still have time..."
	ENDIF
.fi
.PP
.B THE IFTRIG COMMAND
.PP
The \fBIFTRIG\fR command is similar to an \fBIF\fR command, except
that it computes a trigger (as in the \fBREM\fR command), and evaluates
to true if a corresponding \fBREM\fR command would trigger.  Examples:
.PP
.nf
	IFTRIG 1 Nov
		; Executed on 1 Nov
	ELSE
		; Executed except on 1 Nov
	ENDIF

	IFTRIG 1 \-1 OMIT Sat Sun +4
		; Executed on last working day of month,
		; and the 4 working days preceding it
	ELSE
		; Executed except on above days
	ENDIF
.fi
.PP
Note that the \fBIFTRIG\fR command computes a trigger date, which can
be retrieved with the \fBtrigdate()\fR function.  You can use all of
the normal trigger components, such as \fBUNTIL\fR, \fIdelta\fR, etc. in the
\fBIFTRIG\fR command.  However, you cannot use a type specifier such
as \fBCAL\fR, \fBMSG\fR or \fBSATISFY\fR; attempting to do so
yields a parse error.
.PP
.SH USER-DEFINED FUNCTIONS
.PP
In addition to the built-in functions, \fBRemind\fR allows you to define
your own functions.  The \fBFSET\fR command does this for you:
.PP
\fBFSET\fR \fIfname\fR(\fIargs\fR) \fIexpr\fR
.PP
\fIFname\fR is the name of the function, and follows the convention for
naming variables.  \fIArgs\fR is a comma-separated list of arguments, and
\fIexpr\fR is an expression.  \fIexpr\fR is not evaluated at the time
the function is defined; instead, it is evaluated each time the function
is called.  \fIArgs\fR can be empty, in which case
you define a function taking no parameters.  Here are some examples:
.PP
.nf
	FSET double(x) 2*x
	FSET yeardiff(date1, date2) year(date1) - year(date2)
	FSET since(x) ord($Ty \- x)
.fi
.PP
The last function is useful in birthday reminders.  For example:
.PP
.nf
	REM 1 Nov +12 MSG Dean's [since(1984)] birthday is %b.
.fi
.PP
Dean was born in 1984.  The above example, on 1 November 1992, would print:
.PP
.nf
	Dean's 8th birthday is today.
.fi
.PP
Similarly, the function is useful in anniversary reminders.  For example:
.PP
.nf
        REM 4 June MSG [since(1989)] anniversary of the Tienanmen Square massacre
.fi
.PP
Notes:
.TP
o
If you access a variable in \fIexpr\fR that is not in the list of arguments,
the global value (if any) is used.
.TP
o
Function and parameter names are significant to 64 characters.
.TP
o
The \fBvalue()\fR function \fIalways\fR accesses the global value of a
variable, even if it has the same name as an argument.  For example:
.RS
.PP
.nf
		fset func(x) value("x")
		set x 1
		set y func(5)
.fi
.PP
The above sequence sets y to 1, which is the global value of x.
.RE
.TP
o
User-defined functions may call other functions, including other user-defined
functions.  Recursive calls are allowed, but they must terminate (for
example, by using a short-circuit operator or function that breaks the
recursion) or an error will result after a certain maximum number of
recursive calls (by default, 1000.)
.TP
o
If a user-defined function has the same name as a built-in function,
it is ignored and the built-in function is used.  To prevent conflicts
with future versions of \fBRemind\fR (which may define more built-in
functions), you may wish to name all user-defined functions beginning
with an underscore.
.TP
o
If a user-defined function is defined in a context where \fBRUN\fR is
disabled, then whenever that function is called, \fBRUN\fR will be disabled
during its evaluation, \fIeven if\fR it is called from a context where
\fBRUN\fR is enabled.

.PP
To delete a user-defined function, use \fBFUNSET\fR.  This takes a
space-separated list of user-defined functions to delete.  For
example, after the command:
.PP
.nf
        FUNSET myfunc1 otherfunc thirdfunc
.fi
.PP
it is guaranteed that no user-defined functions named myfunc1, otherfunc
or thirdfunc will exist.  \fBRemind\fR does not issue an error if you
try to \fBFUNSET\fR a nonexistent user-defined function; it simply
does nothing in that case.
.PP
You can rename a user-defined function with \fBFRENAME\fR.  This takes
two names:  An old name and a new name.  Consider this command:
.PP
.nf
        FRENAME func_a func_b
.fi
.PP
If \fIfunc_a\fR does not exist, the command unsets \fIfunc_b\fR if
it is defined.  However, if \fIfunc_a\fR exists, then it is renamed to
\fIfunc_b\fR, and \fIfunc_a\fR is no longer defined.  If \fIfunc_b\fR
was defined prior to the \fBFRENAME\fR command, then that old
definition is lost.
.PP
If either argument to the \fBFRENAME\fR command is the name of a built-in
function, the command fails with an error message and does nothing.
.PP
If you define a user-defined function and then later on redefine it,
\fBRemind\fR will issue a warning.  If you do not want this warning,
then use \fBFUNSET\fR to remove the existing definition before you
redefine the function.  Alternatively, you can use a "-" token before
the function name to suppress "redefined function" warnings, as in the
following example:
.PP
.nf
        FSET - f(x) 2*x
        # You must have space before and after the "-"
        # This will NOT work:
        # FSET -f(x) 2*x
.fi
.PP
.SH SAVING AND RESTORING FUNCTIONS
.PP
Occasionally, it is useful to redefine a function for a specific block of
reminders, but to restore its original definition at the end of that
block.  Just as with variables, functions can be pushed onto and popped
off an internal stack.  Here is an example:
.PP
.nf
        PUSH-FUNCS msgprefix
        FSET msgprefix(x) "My new prefix: "
        INCLUDE block_of_reminders.rem
        POP-FUNCS
.fi
.PP
The file \fBblock_of_reminders.rem\fR would be executed with the
\fBmsgprefix\fR function defined above.  After the POP-FUNCS
\fBmsgprefix\fR would be restored to its previous definition if
it had one, or simply unset if it was not previously defined.
.PP
The command PUSH-FUNCS takes a space-separated list of function names.
All of the named user-defined functions will be saved to an internal
stack.  You can even push names that are not defined as any function.
.PP
After a function name has been pushed, \fBRemind\fR will not issue a
warning if you redefine it, because presumably the purpose of pushing
it in the first place is to redefine it.
.PP
The command POP-FUNCS restores the definitions of all the user-defined
functions in the corresponding PUSH-FUNCS command.  If undefined functions
were pushed onto the stack, then POP-FUNCS makes those functions undefined
again.  Here's one more example:
.PP
.nf
        FUNSET a
        FSET b(x) 2*x
        REM MSG [b(3)]   # Outputs 6
        PUSH-FUNCS a b
        FSET a(x) 22*x
        FSET b(x) 3*x
        REM MSG [a(3)] [b(3)] # Outputs 66 9
        POP-FUNCS
        REM MSG [a(3)]   # Undefined function "a"
        REM MSG [b(3)]   # Outputs 6
.fi
.PP
.SH PRECISE SCHEDULING
.PP
The \fBWARN\fR keyword allows precise control over advance warning in
a more flexible manner than the \fIdelta\fR mechanism.  It should be
followed by the name of a user-defined function, \fIwarn_function\fR.
.PP
If a \fIwarn_function\fR is supplied, then it must take one argument of
type \fBINT\fR.  \fBRemind\fR ignores any delta, and instead calls
\fIwarn_function\fR successively with the arguments 1, 2, 3, ...
.PP
\fIWarn_function\fR's return value \fIn\fR is interpreted as follows:
.TP
o
If \fIn\fR is positive, then the reminder is triggered exactly \fIn\fR
days before its trigger date.
.TP
o
If \fIn\fR is negative, then it is triggered \fIn\fR days before its
trigger date, \fInot counting\fR \fBOMIT\fRted days.
.PP
As an example, suppose you wish to be warned of American Independence Day
5, 3, and 1 days in advance.  You could use this:
.PP
.nf
	FSET _wfun(x) choose(x, 5, 3, 1, 0)
	REM 4 July WARN _wfun MSG American Independence Day is %b.
.fi
.PP
.B NOTES
.TP
1
If an error occurs during the evaluation of \fIwarn_function\fR, then
\fBRemind\fR stops calling it and simply issues the reminder on its
trigger date.
.TP
2
If the absolute-values of the return values of \fIwarn_function\fR are
not monotonically decreasing, \fBRemind\fR stops calling it and issues
the reminder on its trigger date.
.TP
3
\fIWarn_function\fR should (as a matter of good style) return 0 as the
final value in its sequence of return values.  However, a reminder will
\fIalways\fR be triggered on its trigger date, regardless of what
\fIwarn_function\fR does.
.PP
Similarly to \fBWARN\fR, the \fBSCHED\fR keyword allows precise
control over the scheduling of timed
reminders.  It should be followed by the name of a user-defined function,
\fIsched_function\fR.
.PP
If a scheduling function is supplied, then it must take one argument of
type \fBINT\fR.  Rather than using the \fBAT\fR time, time \fIdelta\fR, and
time \fIrepeat\fR, \fBRemind\fR calls the scheduling function to determine
when to trigger the reminder.  The first time the reminder is queued, the
scheduling function is called with an argument of 1.  Each time the reminder
is triggered, it is re-scheduled by calling the scheduling function again.
On each call, the argument is incremented by one.
.PP
The return value of the scheduling function must be an \fBINT\fR or a
\fBTIME\fR.  If the return value is a \fBTIME\fR, then the reminder is
re-queued to trigger at that time.  If it is a positive integer \fIn\fR,
then the reminder is re-queued to trigger at the previous trigger time
plus \fIn\fR minutes.  Finally, if it is a negative integer or zero, then
the reminder is re-queued to trigger \fIn\fR minutes before the \fBAT\fR
time.  Note that there must be an \fBAT\fR clause for the \fBSCHED\fR
clause to do anything.
.PP
Here's an example:
.PP
.nf
	FSET _sfun(x) choose(x, \-60, 30, 15, 10, 3, 1, 1, 1, 1, 0)
	REM AT 13:00 SCHED _sfun MSG foo
.fi
.PP
The reminder would first be triggered at 13:00-60 minutes, or at 12:00.
It would next be triggered 30 minutes later, at 12:30.  Then, it would
be triggered at 12:45, 12:55, 12:58, 12:59, 13:00, 13:01 and 13:02.
.PP
.B NOTES
.TP
1
If an error occurs during the evaluation of \fIsched_func\fR, then
\fBRemind\fR reverts to using the \fBAT\fR time and the \fIdelta\fR
and \fIrepeat\fR values, and never calls \fIsched_func\fR again.
.TP
2
If processing \fIsched_func\fR yields a time earlier than the current
system time, it is repeatedly called with increasing argument until it
yields a value greater than or equal to the current time.  However, if
the sequence of values calculated during the repetition is not strictly
increasing, then \fBRemind\fR reverts to the default behaviour and
never calls \fIsched_func\fR again.
.TP
3
It is quite possible using \fIsched_func\fR to keep triggering a reminder
even after the \fBAT\fR-time.  However, it is not possible to reschedule
a reminder past midnight \- no crossing of date boundaries is allowed.
Also, it is quite possible to \fBnot\fR trigger a reminder on the \fBAT\fR
time when you use a scheduling function.  However, if your scheduling
function is terminated (for reasons 1 and 2) before the \fBAT\fR time of
the reminder, it \fIwill\fR be triggered at the \fBAT\fR time, because
normal processing takes over.
.TP
4
Your scheduling functions should (as a matter of good style) return
0 when no more scheduling is required.  See the example.
.TP
5
All scheduling functions are evaluated \fIafter\fR the entire Remind
script has been read in.  So whatever function definitions are in effect
at the end of the script are used.
.PP
.SH THE SATISFY CLAUSE
.PP
The form of \fBREM\fR that uses \fBSATISFY\fR is as follows:
.PP
\fBREM\fR \fItrigger\fR \fBSATISFY\fR \fIexpr\fR
.PP
The way this works is as follows:  \fBRemind\fR first calculates a trigger
date, in the normal fashion.  Next, it sets \fBtrigdate()\fR to the
calculated trigger date.  It then evaluates \fIexpr\fR.  If the result
is not the null string or zero, processing
ends.  Otherwise, \fBRemind\fR computes the next trigger date, and re-tests
\fIexpr\fR.  This iteration continues until \fIexpr\fR evaluates to non-zero
or non-null, or until the iteration limit specified with the \fB\-x\fR
command-line option is reached.
.PP
If \fIexpr\fR is not satisfied, then \fBtrigvalid()\fR is set to 0 and
the error message "Can't compute trigger" is issued.  Otherwise,
\fBtrigvalid()\fR is set to 1.
.PP
This is really useful only if \fIexpr\fR involves a call to the
\fBtrigdate()\fR or related functions or system variables; otherwise,
\fIexpr\fR will not change as \fBRemind\fR iterates.  In fact, if
\fIexpr\fR is not a constant and does not call \fBtrigdate()\fR or
related functions or system variables, then \fBRemind\fR will issue a
warning.
.PP
An example of the usefulness of \fBSATISFY\fR:  Suppose you wish to
be warned of every Friday the 13th.  Your first attempt may be:
.PP
.nf
	# WRONG!
	REM Fri 13 +2 MSG Friday the 13th is %b.
.fi
.PP
But this won't work.  This reminder triggers on the first Friday
on or after the 13th of each month.  The way to do it is with a
more complicated sequence:
.PP
.nf
	REM 13 SATISFY wkdaynum(trigdate()) == 5
	IF trigvalid()
		REM [trigdate()] +2 MSG \\
		Friday the 13th is %b.
	ENDIF
.fi
.PP
You can write the REM statement a little more concisely:
.PP
.nf
	REM 13 SATISFY $Tw == 5
.fi
.PP
Let's see how this works.  The \fBSATISFY\fR clause iterates through
all the 13ths of successive months, until a trigger date is found whose
day-of-week is Friday (== 5).  If a valid date was found, we use the
calculated trigger date to set up the next reminder.
.PP
We could also have written:
.PP
.nf
	REM Fri SATISFY day(trigdate()) == 13
.fi
.PP
but this would result in more iterations, since "Fridays" occur more
often than "13ths of the month."
.PP
Here is another example: Suppose you want to be reminded of something
on the 15th of January, April, July, and October.  You could make
four separate reminders, or you could use:
.PP
.nf
        REM 15 SATISFY [isany($Tm, 1, 4, 7, 10)] MSG 15th Reminder!
.fi
.PP
This technique of using one \fBREM\fR command to calculate a trigger date
to be used by another command is quite powerful.  For example, suppose
you wanted to OMIT Labour day, which is the first Monday in September.  You
could use:
.PP
.nf
	# Note: SATISFY 1 is an idiom for "do nothing"
	REM Mon 1 Sept SATISFY 1
	OMIT [trigdate()]
.fi
.PP
\fBCAVEAT:\fR This \fIonly\fR omits the \fInext\fR Labour Day, not
all Labour Days in the future.  This could cause strange results, as
the \fBOMIT\fR context can change depending on the current date.  For
example, if you use the following command after the above commands:
.PP
.nf
	REM Mon AFTER msg hello
.fi
.PP
the result will not be as you expect.  Consider producing a calendar
for September, 1992.  Labour Day was on Monday, 7 September, 1992.
However, when \fBRemind\fR gets around to calculating the trigger
for Tuesday, 8 September, 1992, the \fBOMIT\fR command will now be
omitting Labour Day for 1993, and the "Mon AFTER" command
will not be triggered.  (But see the description of \fBSCANFROM\fR
in the section "DETAILS ABOUT TRIGGER COMPUTATION.")
.PP
It is probably best to stay away from computing \fBOMIT\fR
trigger dates unless you keep these pitfalls in mind.
.PP
For versions of \fBRemind\fR starting from 03.00.07, you can include
a \fBMSG\fR, \fBRUN\fR, etc. clause in a \fBSATISFY\fR clause as
follows:
.PP
.nf
	REM trigger_stuff SATISFY [expr] MSG body
.fi
.PP
Note that for this case only, the \fIexpr\fR after \fBSATISFY\fR
\fImust\fR be enclosed in square brackets.  It must come after all the other
components of the trigger, and immediately before the \fBMSG\fR,
\fBRUN\fR, etc. keyword.  If \fIexpr\fR cannot be satisfied, then
the reminder is not triggered.
.PP
Thus, the "Friday the 13th" example can be expressed more compactly as:
.PP
.nf
	REM 13 +2 SATISFY [$Tw == 5] MSG Friday the 13th is %b.
.fi
.PP
And you can trigger a reminder on Mondays, Wednesdays and Thursdays
occurring on odd-numbered days of the month with the following:
.PP
.nf
	REM Mon Wed Thu SATISFY [$Td %2 ] MSG Here it is!!!
.fi
.PP
Note that \fBSATISFY\fR and \fBOMITFUNC\fR can often be used to solve the
same problem, though in different ways.  Sometimes a \fBSATISFY\fR is cleaner
and sometimes an \fBOMITFUNC\fR; experiment and use whichever seems clearer.
.PP
.SH POSSIBLY-UNCOMPUTABLE TRIGGERS
.PP
Occasionally, you may wish to suppress the "Can't compute trigger" warnings
for reminders for which a trigger date cannot be computed.  For example,
the following reminder is triggered on a Monday that is not a holiday
if the following Tuesday is a holiday:
.PP
.nf
        REM Mon SKIP SATISFY [isomitted($T+1)] MSG Work between holidays
.fi
.PP
However, if there are no Mondays after today's date that satisfy the
condition, \fBRemind\fR will print the "Can't compute trigger" error.  To
suppress this, use the \fBMAYBE-UNCOMPUTABLE\fR keyword:
.PP
.nf
        REM MAYBE-UNCOMPUTABLE Mon SKIP SATISFY [isomitted($T+1)] MSG Work between holidays
.fi
.PP
It's almost never appropriate to use \fBMAYBE-UNCOMPUTABLE\fR, but it is
provided for those rare occasions when it makes sense.  If you use
\fBMAYBE-UNCOMPUTABLE\fR inside the \fBevaltrig()\fR function, then
untriggerable triggers return -1.  For example:
.PP
.nf
        SET a evaltrig("MAYBE-UNCOMPUTABLE Mon SKIP OMIT Mon")
.fi
.PP
will set a to -1.
.SH DEBUGGING REMINDER SCRIPTS
.PP
Although the command-line \fB\-d\fR option is useful for debugging, it
is often overkill.  For example, if you turn on the \fB\-dx\fR option for
a reminder file with many complex expressions, you'll get a huge amount of
output.  The \fBDEBUG\fR command allows you to control the debugging flags
under program control.  The format is:
.PP
\fBDEBUG\fR [+\fIflagson\fR] [\-\fIflagsoff\fR]
.PP
\fIFlagson\fR and \fIflagsoff\fR consist of strings of the characters "shextvlfqnu"
that correspond to the debugging options discussed in the command-line
options section.  If preceded with a "+", the corresponding group of
debugging options is switched on.  Otherwise, they are switched off.
For example, you could use this sequence to debug a complicated expression:
.PP
.nf
	DEBUG +x
	set a very_complex_expression(many_args)
	DEBUG \-x
.fi
.PP
.B THE DUMPVARS COMMAND
.PP
The command \fBDUMPVARS\fR displays the values of variables in memory.  Its
format is:
.PP
\fBDUMPVARS\fR [\fB\-c\fR] [\fIvar\fR...]
.PP
If you supply a space-separated list of variable names, the corresponding
variables are displayed.  If you do not supply a list of variables, then
all variables in memory are displayed.  To dump a system variable,
put its name in the list of variables to dump.  If you put a lone
dollar sign in the list of variables to dump, then all system variables
will be dumped.
.PP
If you supply the \fB\-c\fR flag, then any variable determined to be
constant will have its value followed by "<const>"
.PP
.B THE ERRMSG COMMAND
.PP
The \fBERRMSG\fR command has the following format:
.PP
\fBERRMSG\fR \fIbody\fR
.PP
The \fIbody\fR is passed through the substitution filter (with an
implicit trigger date of \fBtoday()\fR) and printed to the error
output stream.  Example:
.PP
.nf
	IF !defined("critical_var")
		ERRMSG You must supply a value for "critical_var"
		EXIT
	ENDIF
.fi
.PP
.B THE EXIT COMMAND
.PP
The above example also shows the use of the \fBEXIT\fR command.  This
causes an unconditional exit from script processing.  Any queued
timed reminders are discarded.  If you are in calendar mode
(described next), then the calendar processing is aborted.
.PP
If you supply an \fBINT\fR-type expression after the \fBEXIT\fR command,
it is returned to the calling program as the exit status.  Otherwise,
an exit status of 99 is returned.
.PP
.B THE FLUSH COMMAND
.PP
This command simply consists of the word \fBFLUSH\fR on a line by
itself.  The command flushes the standard output and standard error
streams used by \fBRemind\fR.  This is not terribly useful to most
people, but may be useful if you run \fBRemind\fR as a subprocess of
another program, and want to use pipes for communication.
.PP
.SH AGENDA MODE JSON OUTPUT
.PP
If you supply the \fB\-\-json\fR argument, then Remind outputs JSON
instead of the normal text output.  The JSON output consists of
a single JSON array of zero or more objects.  There are three
possible types of objects in the array:
.TP
.B banner
The \fBbanner\fR object, if present, will be the first object in the array.
There will be at most one \fBbanner\fR object.  It contains a single
key, \fBbanner\fR, whose value is the banner that \fBRemind\fR would normally
print in Agenda Mode.
.TP
.B noreminders
The \fBnoreminders\fR object, if present, will be the final object in the
array.  There will be at most one \fBnoreminders\fR object.  It contains
a single keym, \fBnoreminders\fR, whose value is the phrase "No reminders.",
possibly localized into a different language.
.TP
.B event
All other objects in the array are \fBevent\fR objects.  They are JSON
objects that contain all of the keys described in the \fBrem2ps\fR(1)
man page section "CALENDAR ENTRIES".  However, the \fBcalendar_body\fR,
\fBplain_body\fR and \fBraw_body\fR keys will not be present.
.PP
JSON output can be used by a front-end to display an attractive list of
reminders in Agenda Mode.  The "show today's reminders" feature of
\fBtkremind\fR uses the JSON output.
.PP
.SH CALENDAR MODE
.PP
If you supply the \fB\-c\fR, \fB\-s\fR or \fB\-p\fR
command-line option, then \fBRemind\fR
runs in "calendar mode."  In this mode, \fBRemind\fR interprets the script
repeatedly, performing one iteration through the whole file for each day
in the calendar.  Reminders that trigger are saved in internal buffers,
and then inserted into the calendar in the appropriate places.
.PP
If you also supply the \fB\-a\fR option, then \fBRemind\fR will not
include timed reminders in the calendar.
.PP
The \fB\-p\fR option is used in conjunction with the \fBRem2PS\fR
program to produce a calendar in PostScript format.  For example, the
following command will send PostScript code to standard output:
.PP
.nf
	remind \-p .reminders | rem2ps
.fi
.PP
You can print a PostScript calendar by piping this to the \fBlpr\fR command.
.PP
If you have a reminder script called ".reminders", and you
execute this command:
.PP
.nf
	remind \-c .reminders jan 1993
.fi
.PP
then \fBRemind\fR executes the script 31 times, once for each day in
January.  Each time it executes the script, it increments the value
of \fBtoday()\fR.  Any reminders whose trigger date matches \fBtoday()\fR
are entered into the calendar.
.PP
\fBMSG\fR and \fBCAL\fR-type reminders, by default, have their entire
body inserted into the calendar.  \fBRUN\fR-type reminders are not
normally inserted into the calendar.  However, if you enclose a portion of
the body in the %"...%" sequence, only that portion is inserted.  For
example, consider the following:
.PP
.nf
	REM 6 Jan MSG %"Dianne's birthday%" is %b
.fi
.PP
In agenda mode, \fBRemind\fR would print "Dianne's birthday is today"
on 6 January.  However, in the calendar mode, only the text "Dianne's birthday"
is inserted into the box for 6 January.
.PP
If you explicitly use the %"...%" sequence in a \fBRUN\fR-type reminder,
then the text between the delimiters is inserted into the calendar.
If you use the sequence %"%" in a \fBMSG\fR or \fBCAL\fR-type reminder, then
no calendar entry is produced for that reminder.
.PP
.B PRESERVING VARIABLES
.PP
Because \fBRemind\fR iterates through the script for each day in the calendar,
slow operations may severely reduce the speed of producing a calendar.
.PP
For example, suppose you set the variables "me" and "hostname" as follows:
.PP
.nf
	SET me shell("whoami")
	SET hostname shell("hostname")
.fi
.PP
Normally, \fBRemind\fR clears all variables between iterations in calendar
mode.  However, if certain variables are slow to compute, and will
not change between iterations, you can "preserve" their values with the
\fBPRESERVE\fR command.  Also, since function definitions are preserved
between calendar iterations, there is no need to redefine them on each
iteration.  Thus, you could use the following sequence:
.PP
.nf
	IF ! defined("initialized")
		set initialized 1
		set me shell("whoami")
		set hostname shell("hostname")
		fset func(x) complex_expr
		preserve initialized me hostname
	ENDIF
.fi
.PP
The operation is as follows:  On the first iteration through the script,
"initialized" is not defined.  Thus, the commands between \fBIF\fR and
\fBENDIF\fR are executed.  The \fBPRESERVE\fR command ensures that the
values of initialized, me and hostname are preserved for subsequent
iterations.  On the next iteration, the commands are skipped, since
initialized has remained defined.  Thus, time-consuming operations that
do not depend on the value of \fBtoday()\fR are done only once.
.PP
Most system variables (those whose names start with '$') are automatically
preserved between calendar iterations.
.PP
Note that for efficiency, \fBRemind\fR caches the reminder script
(and any \fBINCLUDE\fRd files) in memory when producing a calendar.
.PP
Timed reminders are sorted and placed into the calendar in time order.
These are followed by non-timed reminders.  \fBRemind\fR automatically
places the time of timed reminders in the calendar according to the
\fB\-b\fR command-line option.  Reminders in calendar mode are sorted as
if the \fB\-g\fR option had been used; you can change the sort order
in calendar mode by explicitly using the \fB\-g\fR option to specify
a different order from the default.
.PP
.B REPEATED EXECUTION
.PP
If you supply a \fIrepeat\fR parameter on the command line,
and do not use the \fB\-c\fR, \fB\-p\fR, or \fB\-s\fR options, \fBRemind\fR
operates in a similar manner to calendar mode.  It repeatedly executes
the reminder script, incrementing \fBtoday()\fR with each iteration.
The same rules about preserving variables and function definitions
apply.  Note that using \fIrepeat\fR on the command line also enables
the \fB\-q\fR option and disables any \fB\-z\fR option.
As an example, if you want to see how \fBRemind\fR
will behave for the next week, you can type:
.PP
.nf
	remind .reminders '*7'
.fi
.PP
If you want to print the dates of the next 1000 days, use:
.PP
.nf
	(echo 'banner %'; echo 'msg [today()]%') | remind - '*1000'
.fi
.PP
.SH INITIALIZING VARIABLES ON THE COMMAND LINE
.PP
The \fB\-i\fR option is used to initialize variables on the \fBRemind\fR
command line.  The format is \fB\-i\fR\fIvar\fR\fB=\fR\fIexpr\fR, where
\fIexpr\fR is any valid expression.  Note that you may have to use quotes
or escapes to prevent the shell from interpreting special characters in
\fIexpr\fR.  You can have as many \fB\-i\fR options as you want on the
command line, and they are processed in order.  Thus, if a variable is defined
in one \fB\-i\fR option, it can be referred to by subsequent \fB\-i\fR
options.
.PP
Note that if you supply a date on the command line, it is not parsed until
all options have been processed.  Thus, if you use \fBtoday()\fR in any
of the \fB\-i\fR expressions, it will return the same value as
\fBrealtoday()\fR and not the date supplied on the command line.
.PP
Any variables defined on the command line are \fBpreserved\fR as with the
\fBPRESERVE\fR command.
.PP
You should not have any spaces between the \fB\-i\fR option and the equal
sign; otherwise, strange variable names are created that can only be accessed
with the \fBvalue()\fR or \fBdefined()\fR functions.
.PP
You can also define a function on the command line by using:
.PP
\fB\-i\fR\fIfunc\fR(\fIargs\fR)=\fIdefinition\fR
.PP
Be sure to protect special characters from shell interpretation.
.SH MORE ABOUT POSTSCRIPT
.PP
The \fBPS\fR and \fBPSFILE\fR reminders pass PostScript code directly
to the printer.  They differ in that the \fBPS\fR-type reminder passes
its body directly to the PostScript output (after processing by the
substitution filter) while the \fBPSFILE\fR-type's body should
simply consist of a filename.  The \fBRem2PS\fR program will open the
file named in the \fBPSFILE\fR-type reminder, and include its contents in
the PostScript output.
.PP
The PostScript-type reminders for a particular day are included in the
PostScript output in sorted order of priority.  Note that the order
of PostScript commands has a \fImajor\fR impact on the appearance of the
calendars.  For example, PostScript code to shade a calendar box will
obliterate code to draw a moon symbol if the moon symbol code is placed
in the calendar first.  For this reason, you should not provide \fBPS\fR
or \fBPSFILE\fR-type reminders with priorities; instead, you should
ensure that they appear in the reminder script in the correct order.
PostScript code should draw objects working from the background to the
foreground, so that foreground objects properly overlay background ones.
If you prioritize these reminders and run the script using descending
sort order for priorities, the PostScript output will not work.
.PP
All of the PostScript code for a particular date is enclosed
in a \fBsave\fR-\fBrestore\fR pair.  However, if several PostScript-type
reminders are triggered for a single day, each section of PostScript is
not enclosed in a \fBsave\fR-\fBrestore\fR pair - instead, the entire
body of included PostScript is enclosed.
.PP
PostScript-type reminders are executed by the PostScript printer before any
regular calendar entries.  Thus, regular calendar entries will overlay
the PostScript-type reminders, allowing you to create shaded or graphical
backgrounds for particular days.
.PP
Before executing your PostScript code, the origin of the PostScript coordinate
system is positioned to the bottom left-hand corner of the "box" in the
calendar representing \fBtoday()\fR.  This location is exactly in the middle
of the intersection of the bottom and left black lines delineating the box -
you may have to account for the thickness of these lines when calculating
positions.
.PP
Several PostScript variables are available to the PostScript code you supply.
All distance and size variables are in PostScript units (1/72 inch.)  The
variables are:
.TP
LineWidth
The width of the black grid lines making up the calendar.
.TP
Border
The border between the center of the grid lines and the space used to print
calendar entries.  This border is normally blank space.
.TP
BoxWidth and BoxHeight
The width and height of the calendar box, from center-to-center of the
black gridlines.
.TP
InBoxHeight
The height from the center of the bottom black gridline to the top
of the regular calendar entry area.  The space from here to the top
of the box is used only to draw the day number.
.TP
/DayFont, /EntryFont, /SmallFont, /TitleFont and /HeadFont
The fonts used to draw the day numbers, the calendar entries, the small
calendars, the calendar title (month, year)
and the day-of-the-week headings, respectively.
.TP
DaySize, EntrySize, TitleSize and HeadSize
The sizes of the above fonts.  (The size of the small calendar font
is \fInot\fR defined here.)  For example, if you wanted to print
the Hebrew date next to the regular day number in the calendar, use:
.PP
.nf
	REM PS Border BoxHeight Border sub DaySize sub moveto \\
	   /DayFont findfont DaySize scalefont setfont \\
	   ([hebday(today())] [hebmon(today())]) show
.fi
.PP
.RS
Note how /DayFont and DaySize are used.
.RE
.PP
Note that if you supply PostScript code, it is possible to produce invalid
PostScript files.  Always test your PostScript thoroughly with a PostScript
viewer before sending it to the printer.  You should not use any document
structuring comments in your PostScript code.
.PP
.SH DAEMON MODE
.PP
If you use the \fB\-z\fR command-line option, \fBRemind\fR runs in
"daemon mode".  In this mode, no "normal" reminders are issued.
Instead, only timed reminders are collected and queued, and are then
issued whenever they reach their trigger time.
.PP
In addition, \fBRemind\fR wakes up every few minutes to check the
modification date on the reminder script (the filename supplied on the
command line.)  If \fBRemind\fR detects that the script has changed,
it re-executes itself in daemon mode, and interprets the changed
script.  If \fBRemind\fR was compiled with support for
\fBinotify\fR(7), then if the command-line reminder script is really a
directory, \fBRemind\fR also re-executes itself if any of the files in
the directory is changed.
.PP
In daemon mode, \fBRemind\fR also re-reads the remind script when it
detects that the system date has changed.
.PP
In daemon mode, \fBRemind\fR acts as if the \fB\-f\fR option had been used,
so to run in daemon mode in the background, use:
.PP
.nf
	remind \-z .reminders &
.fi
.PP
If you use \fBsh\fR or \fBbash\fR, you may have to use the "nohup" command
to ensure that the daemon is not killed when you log out.

.PP
.SH PURGE MODE
.PP

If you supply the \fB\-j\fR command-line option, \fBRemind\fR runs
in \fIpurge mode\fR.  In this mode, it tries to purge expired reminders
from your reminder files.
.PP
In purge mode, \fBRemind\fR reads your reminder file and creates a new
file by appending ".purged" to the original file name.  Note that
\fBRemind\fR \fInever\fR edits your original file; it always creates
a new .purged file.
.PP
If you invoke \fBRemind\fR against a directory instead of a file, then
a .purged file is created for each *.rem file in the directory.
.PP
Normally, \fBRemind\fR does not create .purged files for INCLUDed files.
However, if you supply a numeric argument after \fB\-j\fR, then \fBRemind\fR
will create .purged files for the specified level of INCLUDE.  For example,
if you invoke \fBRemind\fR with the argument \fB\-j2\fR, then .purged
files will be created for the file (or directory) specified on the command
line, any files included by them, and any files included by those files.
However, .purged files will not be created for third-or-higher level
INCLUDE files.
.PP
Determining which reminders have expired is extremely tricky.  \fBRemind\fR
does its best, but you should always compare the .purged file to the
original file and hand-merge the changes back in.
.PP
\fBRemind\fR annotates the .purged file as follows:
.PP
An expired reminder is prefixed with:  #!P: Expired:
.PP
In situations where \fBRemind\fR cannot reliably determine that
something was expired, you may see the following comments inserted
before the problematic line:
.PP
.nf
   #!P: Cannot purge SATISFY-type reminders

   #!P: The next IF evaluated false...
   #!P: REM statements in IF block not checked for purging.

   #!P: The previous IF evaluated true.
   #!P: REM statements in ELSE block not checked for purging

   #!P: The next IFTRIG did not trigger.
   #!P: REM statements in IFTRIG block not checked for purging.

   #!P: Next line has expired, but contains expression...  please verify

   #!P: Next line may have expired, but contains non-constant expression
   #!P: or a relative SCANFROM clause

   #!P! Could not parse next line: Some-Error-Message-Here

   #!P! Problem calculating trigger date
.fi
.PP
\fBRemind\fR always annotates .purged files with lines beginning with
"#!P".  If such lines are encountered in the \fIoriginal\fR file,
they are not copied to the .purged file.
.PP
If you use the "Hush" flag \fB\-h\fR in conjunction with the "Purge"
flag \fB\-j\fR, then \fBRemind\fR does \fInot\fR create any
of the diagnostic comments listed above.  Instead, the only change
it makes to the .purged file is to mark expired reminders with
"#!P: Expired".
.PP
.SH NON-CONSTANT EXPRESSIONS
.PP
In Purge Mode, \fBRemind\fR will not mark a REM statement as expired
if its trigger specification contains a non-constant expression.  A
non-constant expression is defined as one whose value might differ
from run to run, usually because it depends on the current date, but
also if it depends on something from the environment (such as the
output of the \fBshell()\fR function.)
.PP
The use of any of the following in an expression causes \fBRemind\fR
to consider it non-constant:
.RS
.TP
.B o
A global variable that has been assigned the result of a non-constant
expression, or that has been assigned a value in a \fInon-constant
context\fR (to be described later.)
.TP
.B o
A system variable
.TP
.B o
Certain built-in functions that depend on the current date
(for example, \fBtoday()\fR) or the environment
(for example, \fBshell()\fR).
.RE
.PP
In addition, for the purposes of safely expiring reminders in Purge
Mode, \fBRemind\fR considers the following to be non-constant:
.RS
.TP
.B o
The use of an OMITFUNC
.TP
.B o
The use of a relative SCANFROM
.RE
.PP
Whenever a variable is assigned a value, \fBRemind\fR tracks whether
or not the expression whose value it was assigned is constant or
non-constant.  Additionally, variables that are assigned in a
non-constant context are always assumed to be non-constant.
A non-constant context is the code in the scope of an \fBIF\fR
statement where the \fBIF\fR expression is non-constant.
.PP
Here are some examples that should make things clear:
.PP
.nf
        SET d '2025-06-01'        # d is constant
        REM [d] MSG Hello!        # eligible for purging

        SET d today() - 3         # d is non-constant
        REM [d] MSG Hello!        # not eligible for purging

        IF wkdaynum(today()) == 3
            set d '2025-06-01'    # d is non-constant
        ELSE
            set d '2026-01-01'    # d is non-constant
        ENDIF

        SET d '2025-06-01'        # d is constant
        IF today() > today() + 3  # This branch is never taken, but...
            SET d '2029-01-01'    # d is still marked non-constant
        ENDIF

        # Although here d is still '2025-06-01', it is marked
        # non-constant because as far as Remind is concerned,
        # the IF body *might* have been executed depending on today()
.fi
.PP
Note that within the \fBIF\fR...\fBENDIF\fR scope, any assignments
are non-constant because the code flow depends on today's date, which
could change in subsequent \fBRemind\fR runs.  If you want to force
a variable to be treated as constant, no matter what, then use the following
just before you use the variable:
.PP
.nf
        SET var const(var)
.fi
.PP
Variables initialized on the command-line with the \fB\-i\fR flag are
\fIalways\fR considered to be non-constant.
.PP
If you have an expired reminder that for some reason you never want
purged, simply use the built-in function \fBnonconst\fR somewhere in
the trigger.  For example:
.PP
.nf
        REM 1992-01-01 MSG This will be purged after Jan 1 1992
        REM [nonconst('1992-01-01')] MSG This will never be purged

        REM Wed UNTIL 1993-12-31 MSG This will be purged after 1993
        REM Wed UNTIL [nonconst('1993-12-31')] MSG Never purged
.fi
.PP
The \fBn\fR debugging flag prints a message to standard error whenever
\fBRemind\fR decides that an expression is non-constant.  This can produce
a large amount of output, so if you want to find out why \fBRemind\fR considers
a specific expression to be non-constant, it's best to use \fBDEBUG +n\fR
before it and \fBDEBUG -n\fR after it to limit the amount of output.
.PP
.SH SORTING REMINDERS
.PP

The \fB\-g\fR option causes \fBRemind\fR to sort reminders by trigger
date, time and priority before issuing them.  Note that reminders are
still calculated in the order encountered in the script.  However,
rather than being issued immediately, they are saved in an internal
buffer.  When \fBRemind\fR has finished processing the script, it
issues the saved reminders in sorted order.  The \fB\-g\fR option can
be followed by up to four characters that must all be "a" or "d".  The
first character specifies the sort order by trigger date (ascending or
descending), the second specifies the sort order by trigger time and
the third specifies the sort order by priority.  If the fourth
character is "d", the untimed reminders are sorted before timed
reminders.  The default is to sort all fields in ascending order and
to sort untimed reminders after timed reminders.
.PP
In ascending order, reminders are issued with the most imminent first.
Descending order is the reverse.  Reminders are always sorted by
trigger date, and reminders with the same trigger date are then sorted
by trigger time.  If two reminders have the same date and time, then
the priority is used to break ties.  Reminders with the same date,
time and priority are issued in the order they were encountered.
.PP
You can define a user-defined function called SORTBANNER that takes one
\fBDATE\fR-type argument.  In sort mode, the following sequence happens:
.PP
If \fBRemind\fR notices that the next reminder to issue has a different
trigger date from the previous one (or if it is the first one to be
issued), then SORTBANNER is called with the trigger date as its argument.
The result is coerced to a string, and passed through the substitution
filter with the appropriate trigger date.  The result is then displayed.
.PP
Here's an example - consider the following fragment:
.PP
.nf
	# Switch off the normal banner
	BANNER %
	REM 11 March 1993 ++1 MSG Not so important
	REM 17 March 1993 ++7 MSG Way in the future
	REM 10 March 1993 MSG Important Reminder
	REM 11 March 1993 ++1 MSG Not so important - B
	FSET sortbanner(x) iif(x == today(), \\
		"***** THINGS TO DO TODAY *****", \\
		"----- Things to do %b -----")
.fi
.PP
Running this with the \fB-gaa\fR option on 10 March 1993
produces the following output:
.PP
.nf
	***** THINGS TO DO TODAY *****

	Important Reminder

	----- Things to do tomorrow -----

	Not so important

	Not so important - B

	----- Things to do in 7 days' time -----

	Way in the future
.fi
.PP
You can use the \fBargs()\fR built-in function to determine whether or
not SORTBANNER has been defined.  (This could be used, for example, to
provide a default definition for SORTBANNER in a system-wide file included
at the end of the user's file.)  Here's an example:
.PP
.nf
	# Create a default sortbanner function if it hasn't already
	# been defined
	if args("sortbanner") != 1
		fset sortbanner(x) "--- Things to do %b ---"
	endif
.fi
.PP
.SH MSGPREFIX() AND MSGSUFFIX()
.PP
You can define two functions in your script called \fBmsgprefix()\fR
and \fBmsgsuffix()\fR.  They should each accept one argument, a number
from 0 to 9999.
.PP
In agenda mode, for \fBMSG\fR- and \fBMSF\fR-type reminders,
the following sequence occurs when
\fBRemind\fR triggers a reminder:
.TP
o
If \fBmsgprefix()\fR is defined, it is evaluated with the priority
of the reminder as its argument.  The result is printed.  It is
\fInot\fR passed through the substitution filter.
.TP
o
The body of the reminder is printed.
.TP
o
If \fBmsgsuffix()\fR is defined, it is evaluated with the priority
of the reminder as its argument.  The result is printed.  It is
\fInot\fR passed through the substitution filter.
.PP
Here's an example:  The following definition causes priority-0
reminders to be preceded by "URGENT", and priority-6000 reminders to
be preceded by "(not important)".
.PP
.nf
	fset msgprefix(x) iif(x==0, "URGENT: ", \\
	     x==6000, "(not important) ", "")
.fi
.PP
In Calendar Mode (with the \fB\-c\fR, \fB\-s\fR or \fB\-p\fR options),
an analogous pair of functions named \fBcalprefix()\fR and
\fBcalsuffix()\fR can be defined.  They work with all reminders that
produce an entry in the calendar (i.e., \fBCAL\fR- and possibly
\fBRUN\fR-type reminders as well as \fBMSG\fR-type reminders.)
.PP
.B NOTES
.PP
Normally, the body of a reminder is followed by a carriage return.
Thus, the results of \fBmsgsuffix()\fR will appear on the next line.
If you don't want this, make sure the output of \fBmsgsuffix\fR begins
with a backspace.  This places the suffix \fIbefore\fR rather than
after the carriage return.  (The backspace character itself is
stripped out.)  Here is an example:
.PP
.nf
        FSET msgsuffix(x) char(8) + " - suffix on same line"
.fi
.PP
.PP
If \fBRemind\fR has problems evaluating \fBmsgprefix()\fR,
\fBmsgsuffix()\fR or \fBsortbanner()\fR, you will see a lot of
error messages.  For an example of this, define the following:
.PP
.nf
	fset msgprefix(x) x/0
.fi
.PP
.SH COMPILE-TIME SUPPORT FOR OTHER LANGUAGES
.PP
\fBRemind\fR used to support compile-time localization to other languages,
but no longer does.  All localization is now done at run-time.
.PP
.SH RUN-TIME SUPPORT FOR OTHER LANGUAGES
.PP
\fBRemind\fR has run-time support for other languages, and
compile-time support has been removed in favour of run-time support.
.PP
A number of system variables let you translate various phrases
to other languages.  These system variables are:
.PP
.TP
.B $Monday, $Tuesday, $Wednesday, $Thursday, $Friday, $Saturday, $Sunday
Set each of these system variables to a string representing the corresponding
day's name in your language.  Strings must be valid UTF-8 strings.
.TP
.B $January, $February, $March, $April, $May, $June, $July, $August, $September, $October, $November, $December
Set each of these system variables to a string representing the corresponding
month's name in your language.  Strings must be valid UTF-8 strings.
.TP
.B $Ago, $Am, $And, $At, $Hour, $Is, $Minute, $Now, $On, $Pm, $Today, $Tomorrow, $Was
Set each of these system variables to the translation of the corresponding
English word into your language.  Note that \fB$Am\fR and \fB$Pm\fR should
be the translations of "AM" and "PM" (morning and afternoon time indicators)
respectively.
.TP
.B $Hplu, $Mplu
Set these to the suffix to add to the word for "hour" and "minute" to
make them plural.  In English, both would be set to "s".
.TP
.B $Fromnow
Set this to the translation of the English phrase "from now"
.PP
Note that if you set any of the language-related system variables,
they should be set in a section of your script that always is
evaluated.  If you set them inside an \fBIF\fR statement, for example,
results are unpredictable.
.PP
Note also that the \fBRem2PS\fR back-end does not support the full
range of UTF-8 characters.  The \fBTkRemind\fR, \fBrem2html\fR and
\fBrem2pdf\fR back-ends all do support the full UTF-8 range.
.PP
.SH RUN-TIME MODIFICATION OF THE SUBSTITUTION FILTER
.PP
The system variables mentioned in the previous section are not typically
sufficient to properly translate Remind's output to another language.
Some languages have complicated rules for AM vs PM times and others have
complex rules for making words plural.  \fBRemind\fR therefore allows
you to define a number of functions that modify the behavior of
the substitution filter at run-time.  The functions are:
.PP
.TP
.B subst_ampm(h)
This function is passed a single integer, namely an hour from 0 to 23.
It should return a string that indicates "AM" or "PM" or even finer
gradations in some languages.
.TP
.B subst_ordinal(d)
This function is passed a single integer, namely a day of the month from
1 to 31.  It should return a string that is suffixed to the day number to
turn it into an ordinal number.  In English, for example, the function
might return "st", "nd", "rd" or "th", depending on \fId\fR.
.TP
.B subst_\fIN\fR\fB(alt, date, time)\fR
This is actually a \fIfamily\fR of functions, where \fIN\fR is a letter
or number.  This function \fIcompletely overrides\fR the substitution
sequence "%N".  The three arguments are an integer \fIalt\fR which,
if non-zero, indicates that the alternate-mode substitution sequence
"%*N" was encountered; \fIdate\fR which is the trigger date of the
reminder and \fItime\fR which is the trigger time.
.TP
.B subst_\fIN\fR\fBx(alt, date, time)\fR
Again, this is a \fIfamily\fR of functions.  It is similar to the
\fBsubst_\fIN\fR family except it is only called if \fIdate\fR is two or
more days away from \fItoday()\fR.  This is useful if you don't want to
override the "today" or "tomorrow" output for most substitution sequences.
.PP
Here's an example of how you might customize your substitution filter.
Suppose you want to change the "%b" sequence to substitute "the day
after tomorrow" for an event two days from now.  You could do this:
.PP
.nf
    FSET subst_bx(a,d,t) iif(d==today()+2, "the day after tomorrow", \\
                             "in " + (d-today()) + " days' time")
    REM [today()+3] ++3 MSG Event 1 is %b%
    REM [today()+2] ++3 MSG Event 2 is %b%
    REM [today()+1] ++3 MSG Event 3 is %b%
    REM [today()]   ++3 MSG Event 4 is %b%
.fi
.PP
The output of this script is:
.PP
.nf
    Event 1 is in 3 days' time
    Event 2 is the day after tomorrow
    Event 3 is tomorrow
    Event 4 is today
.fi
.PP
Note how Event 2's wording was changed from the normal "in 2 days'
time", and note also that the "tomorrow" and "today" events used the
normal substitution---\fBsubst_bx\fR is not called for trigger days of
today or tomorrow.
.PP
As a special case, if a \fBsubst_Nx\fB or \fBsubst_N\fR function
returns the integer zero, then the normal substitution mechanism is
used.  Therefore, the previous example could have been written more simply
as:
.PP
.nf
    FSET subst_bx(a,d,t) iif(d==today()+2, "the day after tomorrow", 0)
.fi
.PP
You can override substitution sequences that are not alphanumeric as follows:
.RS
.PP
Override %: with \fBsubst_colon\fR
.PP
Override %! with \fBsubst_bang\fR
.PP
Override %? with \fBsubst_question\fR
.PP
Override %@ with \fBsubst_at\fR
.PP
Override %# with \fBsubst_hash\fR
.RE
.PP
You can define your own substitution sequences in addition to the built-in
ones as follows:  If you define a function named \fBsubst_\fIname\fB(alt, date, time)\fR, then the sequence \fB%{name}\fR calls the function with \fBalt\fR
set to 0 and \fBdate\fR and \fBtime\fR to the trigger date and time,
respectively.  The \fB%{name}\fR sequence is replaced with whatever the
function returns.  The sequence \fB%*{name}\fR is similar, but calls
the function with \fBalt\fR set to 1.
.PP
If you use a \fB%{name}\fR sequence and the function \fBsubst_\fIname\fR is
not defined or returns an error, then \fB%{name}\fR is replaced with the
empty string.
.PP
Note that when \fBRemind\fR invokes any callback function for a
substitution sequence, \fBRUN\fR will be disabled.
.PP
.SH THE TRANSLATION TABLE
.PP
To assist with localizing reminder files, \fBRemind\fR maintains a
table of translations.  This is simple a lookup table that maps one
string (the original string) to a new string (the translated string.)
When \fBRemind\fR starts executing, the translation table is empty.
.PP
To add a message to the translation table, use the \fBTRANSLATE\fR
command (which may be abbreviated to \fBTRANS\fR.)  The \fBTRANSLATE\fR
command must be followed by two quoted strings, separated from each
other and from the command by whitespace.  For example, a Dutch
language file might contain something like this:
.PP
.nf
        TRANSLATE "New Moon" "Nieuwe maan"
        TRANSLATE "First Quarter" "Eerste kwartier"
        TRANSLATE "Full Moon" "Volle maan"
        TRANSLATE "Last Quarter" "Laatste kwartier"
.fi
.PP
To actually use the translation table, make use of the \fB_\fR built-in
function, as follows:
.PP
.nf
        REM NOQUEUE [moondatetime(0)] MSG [_("New Moon")] (%2)
        REM NOQUEUE [moondatetime(1)] MSG [_("First Quarter")] (%2)
        REM NOQUEUE [moondatetime(2)] MSG [_("Full Moon")] (%2)
        REM NOQUEUE [moondatetime(3)] MSG [_("Last Quarter")] (%2)
.fi
.PP
By using \fBTRANSLATE\fR and \fB_\fR judiciously, you can make your
reminder files easy to translate.
.PP
\fBTRANSLATE\fR has four additional forms:  If it is followed
by \fIone\fR quoted string instead of two, then \fBRemind\fR deletes the
translation table entry for that string.  If it is followed by
the keyword \fBDUMP\fR, then \fBRemind\fR dumps all translation table entries
to standard output.  And if it is followed by \fBCLEAR\fR, then
\fBRemind\fR deletes all of the translation table entries.
.PP
The fourth form, \fBTRANSLATE GENERATE\fR, dumps all of the
strings that can be localized (as a series of TRANSLATE commands) to
standard output.  Strings that are already localized are output
with their localization; strings that are not localized are
output as:
.PP
.nf
        TRANSLATE "untranslated" ""
.nf
.PP
If you want to add a new language, you can obtain a skeleton translation
file by running:
.PP
.nf
        echo "TRANSLATE GENERATE" | remind -h - > /tmp/skeleton.rem
.fi
.PP
If you have an existing language file that is missing some translations,
you can update it by running:
.PP
.nf
        (echo INCLUDE mylang.rem; echo TRANSLATE GENERATE) | \\
            remind -h - > /tmp/mylang-update.rem
.fi
.PP
and then editing \fBmylang-update.rem\fR to add in the missing translations.
.PP
If you have some reminder scripts that use the \fB_()\fR built-in function
or \fB%(...)\fR substitution sequence, you can generate a list of needed
TRANSLATE commands by running:
.PP
.nf
        remind -q -n -dq myscript.rem 2>&1 | grep ^TRANSLATE | sort | uniq
.fi
.PP
Note that if you \fBSET\fR various translation-related system
variables such as \fB$Monday\fR, \fB$December\fR, \fB$Ago\fR, etc,
then \fBRemind\fR \fIalso\fR makes a corresponding translation
table entry automatically.  This is done for all of the translation-related
system variables \fIexcept for\fR \fB$Hplu\fR and \fB$Mplu\fR.
.PP
The converse applies too; creating a translation table for
"December" automatically sets \fB$December\fR.  And if you invoke
\fBTRANSLATE CLEAR\fR, then all translation-related system variables
are set to their default values as well.
.PP
The translation table always contains a special entry \fBLANGID\fR whose
default value is \fBen\fR.  Translators are encouraged to add a \fBLANGID\fR
entry in their language files; the value should be the two-characters
ISO 639 language code.
.PP
For example, if you write a translation file for the Dutch language,
add this line:
.PP
.nf
        TRANSLATE "LANGID" "nl"
.fi
.PP
Scripts can use \fB_("LANGID")\fR to query the translation language that is
in effect.
.PP
The \fB_()\fR function uses the following procedure to obtain the translation
for a string:
.RS
.TP
1
Look for an exact match.  If found, return.
.TP
2
If the original string had an upper-case letter, search for the
all-lower-case equivalent.  If found, make the first letter of the
result upper-case and return.
.TP
3
If the original string started with a lower-case letter, search
for an equivalent whose first letter is upper-case and the rest lower-case.
If found, make the first letter of the result lower-case and return.
.TP
4
No translation was found.  Return the original string.
.RE
.SH LANGUAGE PACKS
.PP
\fBRemind\fR ships with a number of language packs, which are simply reminder
scripts located in \fB[$SysInclude]/lang\fR.  The currently-shipping
language packs are:
.PP
da.rem (Danish), de.rem (German), es.rem (Spanish), fr.rem (French),
is.rem (Icelandic), it.rem (Italian), nl.rem (Dutch), no.rem (Norwegian),
pl.rem (Polish), pt.rem (Portuguese) and ro.rem (Romanian).
.PP
To use a language pack (in this example, de.rem), simply place this at
the top of your reminders file:
.PP
.nf
    SYSINCLUDE lang/de.rem
.fi
.PP
If you want \fBRemind\fR to try to find the language pack appropriate
for your locale settings, use:
.PP
.nf
    SYSINCLUDE lang/auto.rem
.fi
.PP
You are encouraged to study the language packs to see how to translate
\fBRemind\fR into additional languages.
.PP
.SH THE HEBREW CALENDAR
.PP
\fBRemind\fR has support for the Hebrew calendar, which is a luni-solar
calendar.  This allows you to create reminders for Jewish holidays,
jahrzeits (anniversaries of deaths) and smachot (joyous occasions.)
.PP
.B THE HEBREW YEAR
.PP
The Hebrew year has 12 months, alternately 30 and 29 days long.  The
months are: Tishrey, Heshvan, Kislev, Tevet, Shvat, Adar, Nisan, Iyar,
Sivan, Tamuz, Av and Elul.  If you are in a UTF-8 locale, you can
\fIalso\fR use the UTF-8-encoded Hebrew spellings for the month names,
namely:
.PP
תשרי, חשוון, כסלו, טבת, שבט, אדר, ניסן, אייר, סיון, תמוז, אב, אלול.
.PP
In a cycle of 19 years, there are 7 leap years, being years 3, 6, 8, 11,
14, 17 and 19 of the cycle.  In a leap year, an extra month of 30 days
is added before Adar.  The two Adars are called Adar A and Adar B,
or in Hebrew, 'אדר א and 'אדר ב.
.PP
\fBRemind\fR also permits the following alternative spellings for
Hebrew month names:
.TP
.B Tishrey
Can also be spelled Tishri or Tishrei
.TP
.B Heshvan
Can also be spelled Cheshvan or Kheshvan
.TP
.B Shvat
Can also be spelled Shevat
.TP
.B Tamuz
Can also be spelled Tammuz
.TP
.B Adar A
Can also be spelled Adar 1, Adar I, אדר א or אדר 1.
.TP
.B Adar B
Can also be spelled Adar 2, Adar II, אדר ב or אדר 2.
.TP
.B Iyar
Can also be spelled Iyyar.

.PP
For certain religious reasons, the year cannot start on a Sunday, Wednesday
or Friday.  To adjust for this, a day is taken off Kislev or added to Heshvan.
Thus, a regular year can have from 353 to 355 days, and a leap year from
383 to 385.
.PP
When Kislev or Heshvan is short, it is called \fIchaser\fR, or lacking.  When
it is long, it is called \fIshalem\fR, or full.
.PP
The Jewish date changes at sunset.  However, \fBRemind\fR will change the date
at midnight, not sunset.  So in the period between sunset and midnight,
\fBRemind\fR will be a day earlier than the true Jewish date.  This should not be
much of a problem in practice.
.PP
The computations for the Jewish calendar were based on the program "hdate"
written by Amos Shapir of the Hebrew University of Jerusalem, Israel.  He
also supplied the preceding explanation of the calendar.
.PP
.B HEBREW DATE FUNCTIONS
.TP
.B hebday(d_date)
Returns the day of the Hebrew month corresponding to the \fIdate\fR
parameter.  For example, 12 April 1993 corresponds to 21 Nisan 5753.
Thus, hebday('1993/04/12') returns 21.
.TP
.B hebmon(d_date)
Returns the name of the Hebrew month corresponding to \fIdate\fR.
For example, hebmon('1993/04/12') returns "Nisan".
.TP
.B ivritmon(d_date)
Returns the name of the Hebrew month corresponding to \fIdate\fR,
in UTF-8-encoded Hebrew script. For example, ivritmon('1993/04/12')
returns "ניסן".
.TP
.B hebyear(d_date)
Returns the Hebrew year corresponding to \fIdate\fR.  For example,
hebyear('1993/04/12') returns 5753.
.TP
.B hebdate(i_day, s_hebmon [,id_yrstart [,i_jahr [,i_aflag]]])
The \fBhebdate()\fR function is the most complex of the Hebrew support
functions.  It can take from 2 to 5 arguments.  It returns a \fBDATE\fR
corresponding to the Hebrew date.
.PP
.RS
The \fIday\fR parameter can range from 1 to 30, and specifies the day of
the Hebrew month.  The \fIhebmon\fR parameter is a string that must name
one of the Hebrew months specified above.  Note that the month must be spelled
out in full, and use either the English transliteration shown previously, or
the Hebrew spelling \fIencoded in UTF-8\fR.  You can
also specify "Adar A" and "Adar B."  Month names are not case-sensitive.
.PP
The \fIyrstart\fR parameter can either be a \fBDATE\fR or an \fBINT\fR.  If
it is a \fBDATE\fR, then the \fBhebdate()\fR scans for the first Hebrew
date on or after that date.  For example:
.PP
.nf
		hebdate(15, "Nisan", '1990/01/01')
.fi
.PP
returns 1990/03/30, because that is the first occurrence of 15 Nisan on
or after 1 January 1990.
.PP
If \fIyrstart\fR is an \fBINT\fR, it is interpreted as a Hebrew year.  Thus:
.PP
.nf
		hebdate(22, "Kislev", 5756)
.fi
.PP
returns 1995/12/15, because that date corresponds to 22 Kislev, 5756.  Note
that none of the Hebrew date functions will work with dates outside
\fBRemind's\fR normal range for dates.
.PP
If \fIyrstart\fR is not supplied, it defaults to \fBtoday()\fR.
.PP
The \fIjahr\fR modifies the behaviour of \fBhebdate()\fR as follows:
.PP
If \fIjahr\fR is 0 (the default),
then \fBhebdate()\fR keeps scanning until it
finds a date that exactly satisfies the other parameters.  For example:
.PP
.nf
		hebdate(30, "Adar A", 1993/01/01)
.fi
.PP
returns 1995/03/02, corresponding to 30 Adar A, 5755, because that is the
next occurrence of 30 Adar A after 1 January, 1993.  This behaviour is
appropriate for Purim Katan, which only appears in leap years.
.PP
If \fIjahr\fR is 1, then the date is modified as follows:
.TP
o
30 Heshvan is converted to 1 Kislev in years when Heshvan is \fIchaser\fR
.TP
o
30 Kislev is converted to 1 Tevet in years when Kislev is \fIchaser\fR
.TP
o
30 Adar A is converted to 1 Nisan in non-leapyears
.TP
o
Other dates in Adar A are moved to the corresponding day in Adar in
non-leapyears
.PP
This behaviour is appropriate for smachot (joyous occasions) and for
some jahrzeits - see "JAHRZEITS."
.PP
if \fIjahr\fR is 2, then the date is modified as follows:
.TP
o
30 Kislev and 30 Heshvan are converted to 29 Kislev and 29 Heshvan,
respectively, if the month is \fIchaser\fR
.TP
o
30 Adar A is converted to 30 Shvat in non-leapyears
.TP
o
Other dates in Adar A are moved to the corresponding day in Adar in
non-leapyears
.PP
if \fIjahr\fR is not 0, 1, or 2, it is interpreted as a Hebrew year,
and the behaviour is calculated as described in the next section,
"JAHRZEITS."
.PP
The \fIaflag\fR parameter modifies the behaviour of the function for
dates in Adar during leap years.  The \fIaflag\fR is \fIonly\fR used
if \fIyrstart\fR is a \fBDATE\fR type.
.PP
The \fIaflag\fR only affects date calculations if \fIhebmon\fR is
specified as "Adar".  In leap years, the following algorithm is followed:
.TP
o
If \fIaflag\fR is 0, then the date is triggered in Adar B.  This is
the default.
.TP
o
If \fIaflag\fR is 1, then the date is triggered in Adar A.  This may
be appropriate for jahrzeits in the Ashkenazi tradition; consult a
rabbi.
.TP
o
If \fIaflag\fR is 2, then the date is triggered in both Adar A and Adar
B of a leap year.  Some Ashkenazim perform jahrzeit in both Adar A and
Adar B.
.RE
.PP
.B JAHRZEITS
.PP
A jahrzeit is a yearly commemoration of someone's death.  It normally takes
place on the anniversary of the death, but may be delayed if burial is
delayed - consult a rabbi for more information.
.PP
In addition, because some months change length, it is not obvious which day
the anniversary of a death is.  The following rules are used:
.TP
o
If the death occurred on 30 Heshvan, and Heshvan in the year after the
death is \fIchaser\fR, then the jahrzeit is observed on 29 Heshvan in years
when Heshvan is \fIchaser\fR.  Otherwise, the jahrzeit is observed on 1
Kislev when Heshvan is \fIchaser\fR.
.TP
o
If the death occurred on 30 Kislev, and Kislev in the year after the
death is \fIchaser\fR, then the jahrzeit is observed on 29 Kislev in years
when Kislev is \fIchaser\fR.  Otherwise, the jahrzeit is observed on 1
Tevet when Kislev is \fIchaser\fR.
.TP
o
If the death occurred on 1-29 Adar A, it is observed on 1-29 Adar in
non-leapyears.
.TP
o
If the death occurred on 30 Adar A, it is observed on 30 Shvat in a
non-leapyear.
.PP
Specifying a Hebrew year for the \fIjahr\fR parameter causes the
correct behaviour to be selected for a death in that year.  You may
also have to specify \fIaflag\fR, depending on your tradition.
.PP
The jahrzeit information was supplied by Frank Yellin, who quoted
"The Comprehensive Hebrew Calendar" by Arthur Spier, and "Calendrical
Calculations" by E. M. Reingold and Nachum Dershowitz.
.PP
.SH OUT-OF-BAND REMINDERS
.PP
The \fBSPECIAL\fR keyword is used to transmit "out-of-band" information
to \fBRemind\fR backends, such as \fBtkremind\fR or \fBRem2PS\fR.
They are used only when piping data from a \fBremind \-p\fR line.
(Note that the COLOR special is an exception; it works similarly
to MSG when the \fB\-p\fR option is not supplied.)
.PP
The various \fBSPECIAL\fRs recognized are particular for each
backend; however, there are four \fBSPECIAL\fRs that all backends
should attempt to support.  They are currently supported by
\fBRem2PS\fR, \fBtkremind\fR and \fBrem2html\fR.
.PP
The \fBSHADE\fR special replaces the \fBpsshade()\fR function.
Use it like this:
.PP
.nf
	REM Sat Sun SPECIAL SHADE 128
	REM Mon SPECIAL SHADE 255 0 0
.fi
.PP
The \fBSHADE\fR keyword is followed by either one or three numbers,
from 0 to 255.  If one number is supplied, it is interpreted as
a grey-scale value from black (0) to white (255).  If three numbers
are supplied, they are interpreted as RGB components from minimum (0)
to maximum (255).  The example above shades weekends a fairly dark
grey and makes Mondays a fully-saturated red.  (These shadings appear
in calendars produced by \fBRem2PS\fR, \fBtkremind\fR and \fBrem2html\fR.)
.PP
The \fBMOON\fR special replaces the \fBpsmoon()\fR function.  Use it
like this:
.PP
.nf
	REM [moondate(0)] SPECIAL MOON 0
	REM [moondate(1)] SPECIAL MOON 1
	REM [moondate(2)] SPECIAL MOON 2
	REM [moondate(3)] SPECIAL MOON 3
.fi
.PP
These draw little moons on the various calendars.  The complete syntax
of the \fBMOON\fR special is as follows:
.PP
.nf
	... SPECIAL MOON phase moonsize fontsize msg
.fi
.PP
\fIPhase\fR is a number from 0 to 3, with 0 representing a new moon,
1 the first quarter, 2 a full moon and 3 the last quarter.
.PP
\fImoonsize\fR is the diameter in PostScript units of the moon to
draw.  If omitted or supplied as \-1, the backend chooses an appropriate
size.
.PP
\fIfontsize\fR is the font size in PostScript units of the \fImsg\fR
.PP
\fIMsg\fR is additional text that is placed near the moon glyph.
.PP
Note that only the \fBRem2PS\fR backend supports \fImoonsize\fR
and \fIfontsize\fR; the other backends use fixed sizes.
.PP
The \fBCOLOR\fR special lets you place colored reminders in the
calendar.  Use it like this:
.PP
.nf
	REM ... SPECIAL COLOR 255 0 0 This is a bright red reminder
	REM ... SPECIAL COLOR 0 128 0 This is a dark green reminder
.fi
.PP
You can spell COLOR either the American way ("COLOR") or the British
way ("COLOUR").  This manual will use the American way.

Immediately following COLOR should be three decimal numbers ranging
from 0 to 255 specifying red, green and blue intensities, respectively.
The rest of the line is the text to put in the calendar.
.PP
The COLOR special is "doubly special", because in agenda mode,
\fBremind\fR treats a COLOR special just like a MSG-type reminder.
Also, if you invoke \fBRemind\fR with \fB\-@\fR[\fIn\fR], then it
approximates SPECIAL COLOR reminders on your terminal.
.PP
See also the documentation of the \fB$DefaultColor\fR system variable
in the section "SYSTEM VARIABLES".
.PP
The \fBWEEK\fR special lets you place annotations such as the week
number in the calendar.  For example, this would number each Monday
with the ISO 8601 week number.  The week number is shown like this:
"(W\fIn\fR)" in this example, but you can put whatever text you like
after the WEEK keyword.
.PP
.nf
	REM Monday SPECIAL WEEK (W[weekno()])
.fi
.PP
.SH MISCELLANEOUS
.PP
.B COMMAND AND KEYWORD ABBREVIATIONS
.PP
The following tokens can be abbreviated:
.TP
o
\fBCLEAR-OMIT-CONTEXT\fR --> \fBCLEAR\fR
.TP
o
\fBPUSH-OMIT-CONTEXT\fR --> \fBPUSH\fR
.TP
o
\fBPOP-OMIT-CONTEXT\fR --> \fBPOP\fR
.TP
o
\fBDUMPVARS\fR --> \fBDUMP\fR
.TP
o
\fBBANNER\fR --> \fBBAN\fR
.TP
o
\fBINCLUDE\fR --> \fBINC\fR
.TP
o
\fBMAYBE-UNCOMPUTABLE\fR --> \fBMAYBE\fR
.TP
o
\fBSCANFROM\fR --> \fBSCAN\fR
.PP
.B NIFTY EXAMPLES
.PP
This section is a sampling of what you can do with \fBRemind\fR.
.PP
.nf
	REM 5 Feb 1991 AT 14:00 +45 *30 \\
	RUN mail \-s "Meeting at %2" $LOGNAME </dev/null &
.fi
.PP
On 5 February, 1991, this reminder will mail
you reminders of a 2:00pm meeting at 1:15,
1:45 and 2:00.  The subject of the mail message will be "Meeting at 2:00pm"
and the body of the message will be blank.
.PP
.nf
	REM AT 17:00 RUN echo "5:00pm - GO HOME!" | xless \-g +0+0 &
.fi
.PP
This reminder will pop up an xless window at 5:00pm every day.  The xless
window will contain the line "5:00pm - GO HOME!"
.PP
.nf
	REM AT 23:59 RUN (sleep 120; remind \-a [filename()]) &
.fi
.PP
This reminder will run at one minute to midnight.  It will cause a new
\fBRemind\fR process to start at one minute past midnight.  This allows you to
have a continuous reminder service so you can work through the night and
still get timed reminders for early in the morning.  Note that this
trick is no longer necessary, providing you run \fBRemind\fR in
daemon mode.
.PP
.nf
	remind \-c12 /dev/null Jan 1993
.fi
.PP
This invocation of \fBRemind\fR will cause it to print a calendar for
1993, with all entries left blank.
.PP
.nf
	REM CAL [trigdate()\-date(year(trigdate()), 1, 1)+1]
.fi
.PP
This example puts an entry in each box of a calendar showing the number
(1-365 or 366) of the day of the year.
.PP
.nf
	REM Tue 2 Nov SATISFY (year(trigdate())%4) == 0
	IF trigvalid()
		REM [trigdate()] ++5 MSG \\
		U.S. Presidential Election!!
	ENDIF
.fi
.PP
This example warns you 5 days ahead of each American presidential
election.  The first \fBREM\fR command calculates the first Tuesday after
the first Monday in November.  (This is equivalent to the first
Tuesday on or after 2 November.)  The \fBSATISFY\fR clause ensures
that the trigger date is issued only in election years, which are
multiples of 4.  The second \fBREM\fR command actually issues the
reminder.
.PP
.B DETAILS ABOUT TRIGGER COMPUTATION
.PP
Here is a \fIconceptual\fR description of how triggers are calculated.
Note that \fBRemind\fR actually uses a much more efficient procedure,
but the results are the same as if the conceptual procedure had been
followed.
.PP
\fBRemind\fR starts from the current date (that is, the value of
\fBtoday()\fR) and scans forward, examining each day one at a time
until it finds a date that satisfies the trigger, or can prove that
no such dates (on or later than \fBtoday()\fR) exist.
.PP
If \fBRemind\fR is executing a \fBSATISFY\fR-type reminder, it evaluates
the expression with \fBtrigdate()\fR set to the date found above.  If
the expression evaluates to zero or the null string, \fBRemind\fR continues
the scanning procedure described above, starting with the day after the
trigger found above.
.PP
The \fBSCANFROM\fR clause (having a syntax similar to \fBUNTIL\fR)
can modify the search strategy used.  In this case, \fBRemind\fR begins the
scanning procedure at \fIscan_date\fR, which is the date specified in
the \fBSCANFROM\fR clause.  For example:
.PP
.nf
	REM Mon 1 SCANFROM 17 Jan 1992 MSG Foo
.fi
.PP
The example above will always have a trigger date of Monday, 3 February 1992.
That is because \fBRemind\fR starts scanning from 17 January 1992, and
stops scanning as soon as it hits a date that satisfies "Mon 1."
.PP
The main use of \fBSCANFROM\fR is in situations where you want to
calculate the positions of floating holidays.  Consider the Labour
Day example shown much earlier.  Labour Day is the first Monday
in September.  It can move over a range of 7 days.  Consider the
following sequence:
.PP
.nf
	REM Mon 1 Sept SCANFROM [today()\-7] ADDOMIT MSG Labour Day
	REM Mon AFTER MSG Hello
.fi
.PP
The \fBSCANFROM\fR clause makes sure that \fBRemind\fR begins scanning
from 7 days before the current date.  This ensures that Labour Day for
the current year will continue to be triggered until 7 days after it has
occurred.  This allows you to safely use the AFTER keyword as shown.
.PP
As a special case, you can simply use a negative number after SCANFROM;
a negative number \-N is interpreted as N days before today.  Thus,
the previous example could also be written like this:
.PP
.nf
	REM Mon 1 Sept SCANFROM \-7 ADDOMIT MSG Labour Day
	REM Mon AFTER MSG Hello
.fi
.PP
A SCANFROM that specifies a full date is called an \fIabsolute SCANFROM\fR
and a SCANFROM that specifies a negative number is called a
\fIrelative SCANFROM\fR.
.PP
In general, use \fBSCANFROM\fR as shown for safe movable \fBOMITs\fR.  The
amount you should scan back by (7 days in the example above) depends on
the number of possible consecutive \fBOMITted\fR days that may occur, and
on the range of the movable holiday.  Generally, a value of 7 is safe.
.PP
The \fBFROM\fR clause operates almost like the counterpoint to
\fBUNTIL\fR.  It prevents the reminder from triggering before the
\fBFROM\fR date.  For example, the following reminder:
.PP
.nf
	REM Mon Thu FROM 23 Jul 2007 UNTIL 2 Aug 2007 MSG Test
.fi
.PP
will trigger on Mondays and Thursdays between 23 July 2007 and
2 August 2007 inclusive.
.PP
\fBFROM\fR is really just syntactic sugar; you could implement
the reminder above as follows:
.PP
.nf
	REM Mon Thu SCANFROM [max(today(), '2007-07-23')] \\
            UNTIL 2 Aug 2007 MSG Test
.fi
.PP
but that's a lot harder to read.  Internally, \fBRemind\fR
treats \fBFROM\fR exactly as illustrated using \fBSCANFROM\fR.  For
that reason, you cannot use both \fBFROM\fR and \fBSCANFROM\fR.
.PP
Note that if you use one \fBREM\fR command to calculate a trigger date,
perform date calculations (addition or subtraction, for example) and
then use the modified date in a subsequent \fBREM\fR command, the results
\fImay not be what you intended.\fR  This is because you have circumvented
the normal scanning mechanism.  You should try to write \fBREM\fR commands
that compute trigger dates that can be used unmodified in subsequent
\fBREM\fR commands.  The file "defs.rem" that comes with the \fBRemind\fR
distribution contains examples.
.PP
.B DETAILS ABOUT TRIGVALID()
.PP
The \fBtrigvalid()\fR function returns 1 if \fBRemind\fR could find a trigger
date for the previous \fBREM\fR or \fBIFTRIG\fR command.  More specifically,
it returns 1 if \fBRemind\fR finds a date \fInot before the starting
date of the scanning\fR that
satisfies the trigger.  In addition, there is one special case in which
\fBtrigvalid()\fR returns 1 and \fBtrigdate()\fR returns a meaningful result:
.PP
If the \fBREM\fR or \fBIFTRIG\fR command did not contain an
\fBUNTIL\fR or \fBSATISFY\fR clause, and contained all of the
\fIday\fR, \fImonth\fR and \fIyear\fR components, then \fBRemind\fR
will correctly compute a trigger date, even if it happens to be before
the start of scanning.  Note that this behaviour is not true for
versions of \fBRemind\fR prior to 03.00.01.

.SH FILES
.PP
The traditional location of your reminders file or directory is:
.PP
.nf
        $HOME/.reminders
.fi
.PP
where \fB$HOME\fR is your home directory.
.PP
\fBRemind\fR ships with some preinstalled files for holidays and language
packs.  These are located in the following directory:
.PP
.nf
        @prefix@/share/remind/
.fi
.PP
Do not hard-code the above directory in your reminder files.  Instead,
use the value of the $SysInclude system variable.
.SH AUTHOR
.PP
Dianne Skoll <dianne@skoll.ca> wrote \fBRemind\fR.  The moon phase
code was copied largely unmodified from "moontool" by John Walker.
The moonrise/moonset code comes from
https://github.com/signetica/MoonRise by Stephen R. Schmitt and Cyrus
Rahman.  The sunrise and sunset functions use ideas from programs by
Michael Schwartz and Marc T. Kaufman.  The Hebrew calendar support was
taken from "hdate" by Amos Shapir.  The supported languages and
their translators are listed below.  Languages marked "complete"
support error messages in that language; all others only support the
substitution filter mechanism and month/day names.
.PP
\fBGerman\fR --
Wolfgang Thronicke
.PP
\fBDutch\fR --
Willem Kasdorp and Erik-Jan Vens
.PP
\fBFinnish\fR --
Mikko Silvonen (complete)
.PP
\fBFrench\fR --
Laurent Duperval (complete)
.PP
\fBNorwegian\fR --
Trygve Randen
.PP
\fBDanish\fR --
Mogens Lynnerup
.PP
\fBPolish\fR --
Jerzy Sobczyk (complete)
.PP
\fBBrazilian Portuguese\fR --
Marco Paganini (complete)
.PP
\fBItalian\fR --
Valerio Aimale
.PP
\fBRomanian\fR --
Liviu Daia
.PP
\fBSpanish\fR --
Rafa Couto
.PP
\fBIcelandic\fR --
Bj\[:o]rn Daví\[Sd]sson
.SH BUGS
.PP
If you find a bug in Remind, please report it to: dianne@skoll.ca
.PP
There's no good reason why read-only system variables are not
implemented as functions, or why functions like \fBversion()\fR, etc.
are not implemented as read-only system variables.
.PP
Hebrew dates in \fBRemind\fR change at midnight instead of sunset.
.PP
\fBRemind\fR has some built-in limits (for example, number of global
\fBOMIT\fRs.)
.PP
.SH BIBLIOGRAPHY
.PP
Nachum Dershowitz and Edward M. Reingold, "Calendrical Calculations",
\fISoftware\-Practice and Experience\fR, Vol. 20(9), Sept. 1990,
pp 899-928.
.PP
L. E. Doggett, \fIAlmanac for computers for the year 1978\fR, Nautical
Almanac Office, USNO.
.PP
Richard Siegel and Michael and Sharon Strassfeld, \fIThe First Jewish
Catalog\fR, Jewish Publication Society of America.
.PP
Jean Meeus, \fIAstronomical Algorithms, Second Edition\fR, Willmann-Bell, Inc.

.SH HOME PAGE
https://dianne.skoll.ca/projects/remind/
.SH MAILING LIST
https://dianne.skoll.ca/mailman/listinfo/remind-fans
.SH SEE ALSO
.PP
\fBrem\fR(1), \fBrem2ps\fR(1), \fBrem2pdf\fR(1), \fBtkremind\fR(1), \fBrem2html\fR(1)