Ubuntu Manpage: tkremind - graphical front-end to Remind calendar program

NAME

       tkremind - graphical front-end to Remind calendar program

SYNOPSIS

       tkremind [options] [read_file [write_file [config_file]]]

DESCRIPTION

       TkRemind  is  a  graphical  front-end  to the Remind program.  It provides a friendly graphical interface
       which allows you to view your calendar and add reminders without learning the syntax of Remind.  Although
       not all of Remind's features are available with TkRemind, TkRemind gives you an opportunity to  edit  the
       reminder commands which it creates.  This allows you to learn Remind's syntax and then add extra features
       as you become a more sophisticated Remind programmer.

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

COMMAND-LINE OPTIONS

       TkRemind  itself  has  no  command-line  options.   However, it passes certain options on to Remind.  The
       options it passes are -b, -g, -x, -i and -m.  See the Remind man page  for  details  about  the  options.
       Note that TkRemind will respect the -m and -b1 options and adjust its appearance accordingly.

       Read_file  is the file from which TkRemind reads reminders.  It is in standard Remind format.  Write_file
       is the file to which TkRemind writes reminders which you add using the GUI.  If Read_file is omitted,  it
       defaults to $HOME/.reminders.  If Write_file is omitted, it defaults to Read_file.

       You  may  wish  to  have  a  different Write_file from Read_file if you want to collect all of TkRemind's
       reminders in one place.  Suppose your main file is $HOME/.reminders and you  want  TkRemind  to  put  its
       reminders in $HOME/.tkreminders.  In $HOME/.reminders, include the line:

            INCLUDE [getenv("HOME")]/.tkreminders

       Config_file  is  the  file  in  which  TkRemind  stores  its  options.   If it is omitted, it defaults to
       $HOME/.config/tkremindrc.

       If $HOME/.reminders is a directory, then TkRemind defaults to reading $HOME/.reminders  and  writing  new
       reminders  to  $HOME/.reminders/100-tkremind.rem.   If  you  want  to  keep your reminders in a directory
       $HOME/.reminders, you should create that directory before starting TkRemind.

THE CALENDAR WINDOW

       When you start TkRemind, 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.

NAVIGATING

       To change to the previous or next month, click the <- or -> button, respectively.  You can also  use  the
       left/right arrow keys or PageUp/PageDown to navigate.

       To change back to the current month, click Today or press the Home key.  To go to a specific month, click
       Go  To  Date....   This  pops  up a dialog box which allows you to select a month and enter a year.  Once
       you've done this, click Go to go to the date, or Cancel to cancel.

       To exit TkRemind, click Quit.

ADDING REMINDERS

To add a reminder, click button 1 in any day number in the calendar. The Add Reminder... 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 Remind 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 Remind should do if a reminder falls on a holiday or weekend.

Enter the body of the reminder into the Summary: text entry. If you want, you can enter a location, a
URL, and and longer description in the Location:, URL: and Description: boxes. If you enter anything
here, they will be added as INFO items to the reminder.

To add the reminder to the reminder file, click Add to reminder file. To close the dialog without adding
the reminder to the file, click Cancel. To preview the reminder, click Preview reminder. This pops up
the Preview reminder dialog box.

PREVIEWING REMINDERS

       The Preview reminder dialog box is an excellent way to learn Remind.   It  displays  the  Remind  command
       which  realizes  the  reminder  you entered using the Add Reminder... dialog.  You can edit the reminder,
       thereby gaining access to advanced features of Remind.  You can also use it simply  to  play  around  and
       discover Remind's idioms for expressing different types of reminders.

PRINTING

To print the current month's calendar, click Print... 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 rem2pdf installed, you can choose to produce PDF output rather than PostScript.)

Select the print destination by choosing either To file: or To command: in the print dialog. Press
Browse... 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 Match: 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 Fill page 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
Rem2PS or rem2pdf documentation.)

Finally, click Print to print or Cancel to cancel. Note that during printing, Remind is called with the
-itkremind=1 option and also an additional -itkprint=1 option. If you are producing PDF output, then the
option -itkpdf=1 is also supplied to Remind.

EDITING REMINDERS

       If you created a reminder with TkRemind, 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 Replace reminder.  You  can  delete  the  reminder  entirely  by
       selecting Delete reminder.  The remaining buttons, Preview reminder and Cancel operate identically to the
       dialog in "ADDING REMINDERS."

       Note  that  if  you  edit a reminder (using Preview reminder), any edits you made are not retained in the
       dialog box.  You should not attempt to edit such reminders; you  have  to  retype  them  in  the  Preview
       reminder dialog.

       If the reminder was not created with TkRemind, you can't edit it with TkRemind.

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

       If  a  reminder  has  location  or  description INFO items, then hovering over the reminder will pop up a
       window containing the location and/or description information.

HYPERLINKS

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

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.

BACKGROUND REMINDERS

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

OPTIONS

The final button on the calendar window, Options, lets you configure certain aspects of TkRemind. The
configuration options are:

Start up Iconified
If this is selected, TkRemind starts up iconified. Otherwise, it starts up in a normal window.

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

Confirm Quit
If this is selected, you will be asked to confirm when you press Quit. If not, TkRemind quits
without prompting.

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.

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

Beep terminal when popping up a reminder
If selected, TkRemind beeps the terminal bell when a queued reminder pops up.

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

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

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.

E-mail reminders here if popup not dismissed
If you enter a non-blank e-mail address in this field, then TkRemind 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.

Name or IP address of SMTP server
TkRemind uses a direct SMTP connection to send mail. Enter the IP address of your SMTP server
here.

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"

Extra Argument for Remind
This specifies any extra arguments that should be passed to Remind when TkRemind invokes remind.
Unless you know what you are doing, leave this blank.

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.

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

Once you've configured the options the way you like them, press Apply Options to put them into effect,
Save Options to put them into effect and save them in $HOME/.config/tkremindrc, or Cancel to cancel any
changes you made.

KEYBOARD SHORTCUTS

       TkRemind's main window includes the following keyboard shortcuts:

       Ctrl-Q Quit

       Left Arrow
              Previous Month

       Right Arrow
              Next Month

       Home   Today

IMMEDIATE UPDATES

       If  you are running TkRemind on Linux and Remind has been compiled with inotify(7) support, then TkRemind
       redraws the calendar window immediately if $HOME/.reminders changes (or, if it is a directory, any  files
       in that directory change.)

       This lets TkRemind 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.)

ODDS AND ENDS

TkRemind performs some basic consistency checks when you add or preview a reminder. However, if you edit
a reminder in the previewer, TkRemind does not check the edited reminder. You can produce illegal
reminders which may cause problems. (This is one good reason to isolate TkRemind's reminders in a
separate file.)

TkRemind does not check the body of the reminder in any way. You can use the normal Remind substitution
sequences in the body. Furthermore, if you use expression-pasting in the body, TkRemind does not
validate the expressions.

When TkRemind invokes Remind, it supplies the option:

-itkremind=1

on the command line. So, in your Remind file, you can include:

IF defined("tkremind")
# Then I'm probably being invoked by TkRemind
ENDIF

You can use this to activate certain reminders in different ways for TkRemind (for example).

TkRemind uses tags to keep track of reminders in the script file. You can certainly mix "hand-crafted"
reminders with reminders created by TkRemind if you are aware of the following rules and limitations:

o TkRemind uses TAGs of the form TKTAGnnn where nnn is a number. You should not use such TAGs in
hand-crafted reminders.

o Hand-crafted reminders cannot be edited with TkRemind, and for hand-crafted timed reminders, you
will not be presented with the "Don't remind me again" option when they pop up.

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

SERVER MODE

Remind has a special mode for interacting with programs like TkRemind. This mode is called server mode
and is selected by supplying the -zj option to Remind.

In server mode, Remind 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:

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

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

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

where n is the number of reminders queued.

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

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

The value of the queue key is an array of JSON objects, each representing a queued reminder.

TRANSLATE Any string goes here
Returns the translation of "Any string goes here" according to Remind'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:

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

As you see, the value of the translation 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.

If the argument to TRANSLATE is not in the translation table, then Remind will not issue any
response at all to the TRANSLATE command.

TRANSLATE_DUMP
Returns the contents of the translation table. The JSON object looks like this:

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

The value of the table key is a dictionary of original-to-translated strings.

DEL qid
Delete the reminder with queue-id qid from the queue.

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

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

Additional status lines written are as follows:

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

In this line, tt is the trigger time of the reminder (expressed as a string), now is the current
time, tags (if present) is the tag or tags associated with the reminder, and body is the body of
the reminder. This response causes TkRemind to pop up a reminder notification. qid is a unique
identifier for this reminder. You may delete it from the queue by sending a DEL qid command to
the server. Note that qids are not stable across re-reads; if Remind restarts itself to re-read
the reminder file, then the qid values are likely to change, and any reminder deleted with a DEL
qid command is likely to be re-queued.

{"response":"newdate"}

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

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

If Remind was compiled with support for inotify(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.

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

AUTHOR

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

       TkRemind is Copyright (C) 1996-2025 by Dianne Skoll.

FILES

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

       $HOME/.config/tkremindrc -- TkRemind saved options.

HOME PAGE

       https://dianne.skoll.ca/projects/remind/