remind/man/tkremind.1.in

.TH TKREMIND 1 "@RELEASE_DATE@" "Remind" "VERSION @VERSION@"
.SH NAME
tkremind \- graphical front-end to Remind calendar program
.SH SYNOPSIS
.B tkremind \fR[\fIoptions\fR] [\fIread_file\fR [\fIwrite_file\fR [\fIconfig_file\fR]]]
.SH DESCRIPTION
\fBTkRemind\fR is a graphical front-end to the \fBRemind\fR program.
It provides a friendly graphical interface which allows you to view
your calendar and add reminders without learning the syntax of \fBRemind\fR.
Although not all of \fBRemind\fR's features are available with \fBTkRemind\fR,
\fBTkRemind\fR gives you an opportunity to edit the reminder commands which
it creates.  This allows you to learn \fBRemind\fR's syntax and then add
extra features as you become a more sophisticated \fBRemind\fR programmer.

\fBTkRemind\fR is written in Tcl, and requires version 8.5 (or higher)
as well as the tcllib extension.  It also requires a \fBwish\fR
binary.  If you are using Tcl/Tk 8.5, you may also need either the Img
or the tkpng extension to handle PNG images.

.SH COMMAND-LINE OPTIONS
\fBTkRemind\fR itself has only one command-line option:
\fB\-\-version\fR, which makes it print the version of \fBTkRemind\fR
and exit.  Any other command-line argument starting with \fB\-\fR to
\fBRemind\fR as an option.  In addition, \fBTkRemind\fR will respect
the \fB\-m\fR and \fB\-b1\fR options and adjust its appearance
accordingly.
.PP
\fIRead_file\fR is the file from which \fBTkRemind\fR reads reminders.
It is in standard \fBRemind\fR format.  \fIWrite_file\fR is the file
to which \fBTkRemind\fR writes reminders which you add using the GUI.
If \fIRead_file\fR is omitted, it defaults to \fB$HOME/.reminders\fR.
If \fIWrite_file\fR is omitted, it defaults to \fIRead_file\fR.
.PP
You may wish to have a different \fIWrite_file\fR from \fIRead_file\fR if
you want to collect all of \fBTkRemind\fR's reminders in one place.  Suppose
your main file is \fI$HOME/.reminders\fR and you want \fBTkRemind\fR to put
its reminders in \fI$HOME/.tkreminders\fR.  In \fI$HOME/.reminders\fR,
include the line:
.PP
.nf
	INCLUDE [getenv("HOME")]/.tkreminders
.fi
.PP

\fIConfig_file\fR is the file in which \fBTkRemind\fR stores
its options.  If it is omitted, it defaults to \fI$HOME/.config/tkremindrc\fR.

.PP
If \fB$HOME/.reminders\fR is a \fIdirectory\fR, then \fBTkRemind\fR defaults to
reading \fB$HOME/.reminders\fR and writing new reminders to
\fB$HOME/.reminders/100-tkremind.rem\fR.  If you want to keep your
reminders in a directory \fB$HOME/.reminders\fR, you should create that
directory before starting \fBTkRemind\fR.
.SH THE CALENDAR WINDOW
When you start \fBTkRemind\fR, it displays a calendar for the current
month, with today's date highlighted.  Reminders are filled into each
box on the calendar.  If a box contains many reminders, you can scroll
it up and down by dragging mouse button 2 in the box or by using the
scroll wheel (if your mouse has one.)  Note that there is no specific
indication of an over-full box; you'll just have to notice that the
box appears completely full.

.SH NAVIGATING
To change to the previous or next month, click the \fB<\-\fR
or \fB\->\fR button, respectively.  You can also use the left/right arrow
keys or \fBPgUp\fR/\fBPgDn\fR to navigate.

To change back to the current month, click \fBToday\fR or press the
\fBHome\fR key.  To go to a specific month, click \fBGo To Date...\fR
or press \fBg\fR.  This pops up a dialog box which allows you to
select a month and enter a year.  Once you've done this, click
\fBGo\fR to go to the date, or \fBCancel\fR to cancel.  Note also that
all pop-up windows in \fBTkRemind\fR can be dismissed by pressing
\fBEsc\fR or \fBControl-w\fR.

To exit \fBTkRemind\fR, click \fBQuit\fR or press \fBControl-q\fR..

.SH CHANGING THE VIEW
By default, \fBTkRemind\fR shows the calendar for an entire month.
The \fBView...\fR menu lets you pick from the following choices: Display
an entire month, or display one, two or four weeks' worth of reminders.
If you change the view, \fBTkRemind\fR remembers the change and that
view becomes the default view next time you start \fBTkRemind\fR

In the monthly view, the Next and Previous navigation buttons and keyboard
shortcuts move by one month.  In all other views, they move by one week.
This is true even for views that display multiple weeks.

You can press the keys \fB1\fR, \fB2\fR, \fB4\fR or \fBm\fR over the
main calendar window to change the view to one week, two weeks, four weeks
or one month, respectively.

.SH ADDING REMINDERS
To add a reminder, click button 1 in any day number in the calendar.
The \fBAdd Reminder...\fR dialog will pop up, with values preselected for
the day you clicked.

The dialog has seven basic groups of controls.  The first three lines
select one of three types of reminders.  Choose the type of reminder
with the radio buttons, and choose the values of the days, months, and
years by selecting values from pull-down menus.  The pull-down menus
appear when you click the raised value buttons.

The next control specifies an expiry date for the reminder.  Select
the check button to enable an expiry date, and fill in the values
using pull-down menus.

The third control specifies how much advance notice you want (if any),
and whether or not weekends and holidays are counted when computing advance
notice.

The fourth control specifies which days \fBRemind\fR considers
as part of the weekend.  This can affect the interpretation of "weekday"
in the second and third types of reminders.

The fifth group of controls associates a time and possible duration
with the reminder.  You can also specify advance notice, possibly
repeating.

The sixth control allows you to specify whether the reminder is a
TODO, and if so, its completion date.  Typing a slash "/" in the
"Complete through:" field automatically fills in the date of the
calendar entry.  Otherwise, enter a completion date in the form
YYYY-MM-DD.  You can also enter a number in the "Max overdue days:"
field to limit how many days past the due date \fBRemind\fR will keep
reminding you of the TODO.

The seventh control specifies what \fBRemind\fR should do if a reminder
falls on a holiday or weekend.

Enter the body of the reminder into the \fBSummary:\fR text entry.  If
you want, you can enter a location, a URL, and a longer description
in the \fBLocation:\fR, \fBURL:\fR and \fBDescription:\fR boxes.  If
you enter anything here, they will be added as \fBINFO\fR items to the
reminder.

To add the reminder to the reminder file, click \fBAdd to reminder file\fR.
To close the dialog without adding the reminder to the file, click
\fBCancel\fR.  To preview the reminder, click \fBPreview reminder\fR.
This pops up the \fBPreview reminder\fR dialog box.

.SH PREVIEWING REMINDERS
The \fBPreview reminder\fR dialog box is an excellent way to learn
\fBRemind\fR.  It displays the \fBRemind\fR command which realizes the
reminder you entered using the \fBAdd Reminder...\fR dialog.  You can
edit the reminder, thereby gaining access to advanced features of
\fBRemind\fR.  You can also use it simply to play around and discover
\fBRemind\fR's idioms for expressing different types of reminders.
.PP
\fBNOTE\fR: If you hand-edit a reminder, then that reminder will
\fInot\fR be editable in TkRemind's graphical reminder dialog any more.
You will have to hand-edit it to change it.

.SH SEEING A SINGLE DAY'S REMINDERS
Right-click on any day number in the calendar to pop up a window with
that day's reminders in Agenda Mode.  You can left- or right-click the
current date and time indicator at the bottom of the calendar window
to see today's reminders in Agenda Mode.  You can also press \fBt\fR
over the main calendar window to see today's reminders in Agenda Mode.

In the Agenda Mode display, hovering over a reminder will show ancillary
information such as a Location, URL or Description.  Clicking on a reminder
will open an editor on the REM command that created the reminder.  You can
also navigate in the Agenda Mode window one day at a time using the
forward and back arrow buttons or left/right arrow keys or \fBPgUp\fR/\fBPgDn\fR.
You can get back to today by clicking \fBToday\fR or pressing the
\fBHome\fR key.

You can dismiss the Agenda Mode window by clicking \fBOK\fR or pressing
the \fBEsc\fR key.

.SH PRINTING
To print the current month's calendar, click \fBPrint...\fR on the
main calendar window or press \fBp\fR or \fBControl-p\fR.  This brings
up the print dialog.  Printing either produces a PostScript or PDF
file, or sends PostScript or PDF to a UNIX command.

Note that you must have \fBrem2pdf\fR installed in order to be
able to print.

Select the print destination by choosing either \fBTo file:\fR or
\fBTo command:\fR in the print dialog.  Press \fBBrowse...\fR to bring
up a file browser.  In the file browser, you can enter a filename in
the text entry, double-click on a filename in the listbox, or
double-click on a directory to navigate the file system.  You can also
type the first few characters of a file name in the text entry box and
press space to complete the name to the first matching entry.

The \fBMatch:\fR box contains a filename wildcard which filters files
in the listbox.  You can change the filter and press enter to rescan
the directory.

Select the appropriate paper size and orientation.  Activate
\fBFill page\fR if you want the calendar to fill the page.  This should
be the normal case unless you have many reminders in a particular
day.  (See the \fBrem2pdf\fR documentation.)

If you activate \fBAvoid over-full boxes\fR, then \fBTkRemind\fR
will pass the \fB\-\-avoid\-overfull\fR option to \fBrem2pdf\fR.  This
will make it try to fit many reminders into a calendar box by shrinking
the font.  This option, if activated, also automatically activates
\fBFill page\fR.

Finally, click \fBPrint\fR to print or \fBCancel\fR to cancel.  Note
that during printing, \fBRemind\fR is called with the
\fB-itkremind=1\fR option and also an additional \fB-itkprint=1\fR
option.  If you are producing PDF output, then the option \fB-itkpdf=1\fR
is also supplied to \fBRemind\fR.

If you click on \fBShow Command\fR rather than \fBPrint\fR, then
\fBTkRemind\fR won't actually print anything.  Instead, it will pop
up a text window with the command that it \fIwould have used\fR to print
the calendar.  You can adjust the command as needed and then click \fBRun\fR
to run the modified command.  This lets you specify \fBrem2pdf\fR options
that are not directly supported by \fBTkRemind\fR.

.SH EDITING REMINDERS

If you created a reminder with \fBTkRemind\fR, it will turn red as the
mouse cursor passes over it in the calendar window.  Click
button-1 over the reminder and you will be presented with a dialog
window whose state is identical to the one used to create the reminder.
At this point, you can change the reminder by editing the dialog
entries and selecting \fBReplace reminder\fR.  You can delete the
reminder entirely by selecting \fBDelete reminder\fR.  The remaining
buttons, \fBPreview reminder\fR and \fBCancel\fR operate identically
to the dialog in "ADDING REMINDERS."

Note that if you have hand-edited a reminder (using \fBPreview
reminder\fR), or if the reminder was hand-created in the first place,
then clicking on it will \fInot\fR pop up the TkRemind
reminder-editing dialog.  Instead, TkRemind will start up a text
editor (if you have configured one) so you can hand-edit the reminder.

.SH USING A TEXT EDITOR

If you have set the "text editor" option correctly, right-clicking
on a reminder will bring up a text editor on the file containing
the reminder.  The cursor will be positioned on the line that
generated the reminder.  In addition, if you have a reminder that
is editable with an editor but was not created using \fBTkRemind\fR,
it will be underlined when you move the cursor over it, and
you can edit it in a text editor by either left- or right-clicking
on the reminder.
.PP
If a reminder has location or description \fBINFO\fR items, then
hovering over the reminder will pop up a window containing the
location and/or description information.

.SH HYPERLINKS

If a reminder has a "Url:" INFO string set, then middle-clicking
will open the URL using \fBxdg-open\fR.

.SH ERRORS

If there are any errors in your reminder file, the "Queue..." button
changes to "Errors...".  Click on "Errors..." to see the Remind error
output.  Click "OK" to close the error window; this makes the button
in the main TkRemind window to revert to "Queue..."  You can click on
any error message to open an editor on the file and line number that
caused the error.

.SH BACKGROUND REMINDERS

If you create "timed" reminders, \fBTkRemind\fR will queue them in
the background and pop up boxes as they are triggered.  Additionally,
if you created the reminder using \fBTkRemind\fR, you will be given the
option of "turning off" the reminder for the rest of the day.
\fBTkRemind\fR achieves queuing of background reminders by running
\fBRemind\fR in \fIserver mode\fR, described later.

.SH OPTIONS

The final button on the calendar window, \fBOptions\fR, lets you configure
certain aspects of \fBTkRemind\fR.  You can also pop up the options
window by pressing \fBo\fR.  The configuration options are:

.TP
.B Start up Iconified
If this is selected, \fBTkRemind\fR starts up iconified.  Otherwise,
it starts up in a normal window.

.TP
.B Show Today's Reminders on Startup
If this is selected, \fBTkRemind\fR shows a text window containing reminders
which would be issued by "remind \-q \-a \-r" on startup, and when the date
changes at midnight.

.TP
.B Confirm Quit
If this is selected, you will be asked to confirm when you press
\fBQuit\fR.  If not, \fBTkRemind\fR quits without prompting.

.TP
.B Automatically close pop-up reminders after a minute
If this is selected, pop-up reminder boxes will be closed after one minute
has elapsed.  Otherwise, they remain on your screen forever until you
explicitly dismiss them.

.TP
.B Use system notifications when issuing a reminder
This option is available only for Tcl/Tk version 9.0 or later, or if
you have the \fBnotify-send\fR program installed; it will be greyed
out if neither condition is true.  If selected, then when a reminder
is popped up, it will also be sent to the desktop notification system,
causing a notification to appear.

.TP
.B Beep terminal when popping up a reminder
If selected, \fBTkRemind\fR beeps the terminal bell when a queued reminder
pops up.

.TP
.B Deiconify calendar window when popping up a reminder
If selected, does what it says.

.TP
.B Run command when popping up a reminder
If this entry is not blank, the specified command is run whenever a
background reminder pops up.

.TP
.B Feed popped-up reminder to command's standard input
If selected, feeds the text of the reminder to the command described
above.  The text of the reminder is prefixed by "HH:MM ", where HH:MM
is the time of the reminder.

.TP
.B E-mail reminders here if popup not dismissed
If you enter a non-blank e-mail address in this field, then \fBTkRemind\fR
will e-mail you a reminder if you don't dismiss the popup box within
one minute.  This is useful if you need to leave your terminal but
want your reminders to "follow" you via e-mail.

.TP
.B Name or IP address of SMTP server
\fBTkRemind\fR uses a direct SMTP connection to send mail.  Enter the
IP address of your SMTP server here.

.TP
.B Text Editor
This specifies a text editor to invoke when a reminder is right-clicked.
The sequence "%d" is replaced with the line number of the file
containing the reminder, and "%s" is replaced with the file name.
Useful strings might be "emacs +%d %s" or "gvim +%d %s"

.TP
.B Extra Arguments for Remind
This specifies any extra arguments that should be passed to Remind
when \fBTkRemind\fR invokes \fBremind\fR.  Unless you know what
you are doing, leave this blank.

.TP
.B Change entry font...
This button pops up a font selection dialog that lets you change the
font used to draw calendar items in the calendar boxes.

.TP
.B Change heading font...
Similar to Change entry font, but applies to calendar heading
(the month and day names and the day numbers.)

.PP
Once you've configured the options the way you like them,
press \fBApply Options\fR to put them into effect, \fBSave Options\fR
to put them into effect and save them in $HOME/.config/tkremindrc, or
\fBCancel\fR to cancel any changes you made.

.SH IMMEDIATE UPDATES

If you are running \fBTkRemind\fR on Linux and \fBRemind\fR has been
compiled with \fBinotify\fR(7) support, then \fBTkRemind\fR redraws
the calendar window \fIimmediately\fR if \fB$HOME/.reminders\fR
changes (or, if it is a directory, any files in that directory
change.)
.PP
This lets \fBTkRemind\fR react immediately to hand-edited reminders or
to reminder files that are imported from another calendar system (for example,
you may have a cron job that periodically imports your Google Calendar
entries into Remind format.)

.SH ODDS AND ENDS
\fBTkRemind\fR performs some basic consistency checks when you add or
preview a reminder.  However, if you edit a reminder in the previewer,
\fBTkRemind\fR does \fInot\fR check the edited reminder.  You can
produce illegal reminders which may cause problems.  (This is one good
reason to isolate \fBTkRemind\fR's reminders in a separate file.)
.PP
\fBTkRemind\fR does \fInot\fR check the body of the reminder in any
way.  You can use the normal \fBRemind\fR substitution sequences in
the body.  Furthermore, if you use expression-pasting in the body,
\fBTkRemind\fR does \fInot\fR validate the expressions.
.PP
When \fBTkRemind\fR invokes \fBRemind\fR, it supplies the option:
.PP
.nf
	\-itkremind=1
.fi
.PP
on the command line.  So, in your \fBRemind\fR file, you can include:
.PP
.nf
	IF defined("tkremind")
		# Then I'm probably being invoked by TkRemind
	ENDIF
.fi
.PP
You can use this to activate certain reminders in different ways
for \fBTkRemind\fR (for example).
.PP
\fBTkRemind\fR uses tags to keep track of reminders in the
script file. You can certainly mix
"hand-crafted" reminders with reminders created by \fBTkRemind\fR
if you are aware of the following rules and limitations:
.TP
o
\fBTkRemind\fR uses \fBTAG\fRs of the form \fBTKTAG\fR\fInnn\fR
where \fInnn\fR is a number.  You should not use such \fBTAG\fRs
in hand-crafted reminders.
.TP
o
Hand-crafted reminders cannot be edited with \fBTkRemind\fR, and
for hand-crafted timed reminders, you will not be presented with
the "Don't remind me again" option when they pop up.

.PP
However, rather than mixing hand-edited files with \fBTkRemind\fR-generated
ones, it is better to make \fB$HOME/.reminders\fR a directory and keep
your hand-edited files in a separate \fB*.rem\fR file than \fBTkRemind\fR's
\fB100-tkremind.rem\fR file.

.SH SERVER MODE

\fBRemind\fR has a special mode for interacting with programs like
\fBTkRemind\fR.  This mode is called \fIserver mode\fR and is
selected by supplying the \fB\-zj\fR option to \fBRemind\fR.

In server mode, \fBRemind\fR operates similar to daemon mode, except
it reads commands (one per line) from standard input and writes status
lines to standard output.  Each status line is a JSON object.

The commands accepted in server mode are:

.TP
EXIT
Terminate the \fBRemind\fR process.  EOF on standard input does the
same thing.  \fBRemind\fR exits immediately without printing
a JSON status line.

.TP
STATUS
Return the number of queued reminders.  The JSON object looks
something like this:
.nf

{"response":"queued","nqueued":n,"command":"STATUS"}

.fi
where \fIn\fR is the number of reminders queued.

.TP
QUEUE or JSONQUEUE
Returns the contents of the queue.  The JSON object looks something
like this:
.nf

{"response":"queue","queue":[ ... ],"command":"QUEUE"}

.fi
The value of the \fBqueue\fR key is an array of JSON objects, each
representing a queued reminder.

.TP
TRANSLATE Any string goes here
Returns the translation of "Any string goes here" according to \fBRemind\fR's
translation table.  Note that there must be exactly one space after
TRANSLATE and before the string you wish to translate.  The JSON object
that results from "TRANSLATE New Moon" might look like this:
.nf

{"response":"translate","translation":{"New Moon":"Nieuwe maan"},"command":"TRANSLATE"}

.fi
As you see, the value of the \fBtranslation\fR key is an object whose
key is the original text and value is the translated text.  A
front-end can use TRANSLATE do its own localization; for example,
TkRemind uses it to localize the moon phase popup window for the
SPECIAL MOON display.
.RS
.PP
If the argument to TRANSLATE is not in the translation table, then
\fBRemind\fR \fIwill not issue any response at all\fR to the TRANSLATE command.
.RE
.TP
TRANSLATE_DUMP
Returns the contents of the translation table.  The JSON object looks
like this:
.nf

{"response":"translate_dump","table":{...},"command":"TRANSLATE_DUMP"}

.fi
The value of the \fBtable\fR key is a dictionary of original-to-translated
strings.

.TP
DEL \fIqid\fR
Delete the reminder with queue-id \fIqid\fR from the queue.

.TP
REREAD
Re-read the reminder file.  Returns the following status line:

.nf

{"response":"reread","command":"REREAD"}

.fi

.PP
Additional status lines written are as follows:

.TP
.nf

{"response":"reminder","ttime":tt,"now":now,"tags":tags,"qid":qid,"body":body}

.fi
In this line, \fItt\fR is the trigger time of the reminder (expressed
as a string), \fInow\fR is the current time, \fItags\fR (if present)
is the tag or tags associated with the reminder, and \fIbody\fR is the
body of the reminder.  This response causes \fBTkRemind\fR to pop up a
reminder notification.  \fIqid\fR is a unique identifier for this
reminder.  You may delete it from the queue by sending a \fBDEL\fR
\fIqid\fR command to the server.  Note that \fIqid\fRs are not stable
across re-reads; if \fBRemind\fR restarts itself to re-read the reminder
file, then the \fIqid\fR values are likely to change, and any reminder
deleted with a \fBDEL\fR \fIqid\fR command is likely to be re-queued.
.TP
.nf

{"response":"newdate"}

.fi

This line is emitted whenever \fBRemind\fR has detected a rollover of
the system date.  The front-end program should redraw its calendar
or take whatever other action is needed.

.TP
.nf

{"response":"reread","command":"inotify"}

.fi

If \fBRemind\fR was compiled with support for \fBinotify\fR(7), then
if it detects a change to the top-level reminder file or directory,
it issues the above response.  The front-end should redraw its
calendar since this response indicates that a change has been made
to the reminder file or directory.

.PP
Please note that \fBRemind\fR can write a status message \fIat any time\fR
and not just in response to a command sent to its standard input.  Therefore,
a program that runs \fBRemind\fR in server mode must be prepared to handle
asynchronous status messages.

.SH AUTHOR
TkRemind was written by Dianne Skoll <dianne@skoll.ca>

\fBTkRemind\fR is Copyright (C) 1996-2026 by Dianne Skoll.

.SH FILES

$HOME/.reminders -- default reminder file or directory.

$HOME/.config/tkremindrc -- \fBTkRemind\fR saved options.

.SH HOME PAGE
https://dianne.skoll.ca/projects/remind/
.SH SEE ALSO
\fBremind\fR, \fBrem2pdf\fR, \fBrem2html\fR