remind/man/tkremind.1.in

.TH TKREMIND 1 "@RELEASE_DATE@" "User Commands" "VERSION @VERSION@"
.UC 4
.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 no command-line options.  However, it passes
certain options on to \fBRemind\fR.  The options it passes are
\fB\-b\fR, \fB\-g\fR, \fB\-x\fR, \fB\-i\fR and \fB\-m\fR.  See the
\fBRemind\fR man page for details about the options.  Note that
\fBTkRemind\fR will respect the \fB\-m\fR and \fB\-b1\fR options and
adjust its appearance accordingly.

\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.

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.  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 PageUp/PageDown to navigate.

To change back to the current month, click \fBToday\fR or press the
Home key.  To go to a specific month, click \fBGo To Date...\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.

To exit \fBTkRemind\fR, click \fBQuit\fR.

.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 six 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 control associates a time with the reminder.
You can also specify advance notice, possibly repeating.

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

Enter the body of the reminder into the \fBBody:\fR text entry.

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.

.SH PRINTING
To print the current month's calendar, click \fBPrint...\fR on the
main calendar window.  This brings up the print dialog.  Printing
either produces a PostScript file or sends PostScript to a UNIX command.
(If you have \fBrem2pdf\fR installed, you can choose to produce
PDF output rather than PostScript.)

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 \fBRem2PS\fR or \fBrem2pdf\fR documentation.)

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.


.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 edit a reminder (using \fBPreview reminder\fR),
any edits you made are \fInot\fR retained in the dialog box.  You
should not attempt to edit such reminders; you have to retype them
in the \fBPreview reminder\fR dialog.

If the reminder was not created with \fBTkRemind\fR, you can't edit
it with \fBTkRemind\fR.

.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.

.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.  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 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 characters "%d" are replaced with the lined number of the file
containing the reminder, and "%s" are replaced with the file name.
Useful strings might be "emacs +%d %s" or "gvim +%d %s"

.TP
.B Extra Argument for Remind
This specifies any extra arguments that should be passed to Remind
when \BTkRemind\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 KEYBOARD SHORTCUTS
\fBTkRemind\fR's main window includes the following keyboard shortcuts:

.TP
.B Ctrl-Q
Quit
.TP
.B Left Arrow
Previous Month
.TP
.B Right Arrow
Next Month
.TP
.B Home
Today

.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
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 1996-2024 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, \fBrem2ps\fR, \fBrem2pdf\fR, \fBrem2html\fR