NAME

xmemo - memo for X

xfortune - fortune for X

xyow - yow for X

SYNOPSIS

xmemo [-toolkitoption ...] [-option ...] message_text

xfortune [-toolkitoption ...] [-option ...]

xyow [-toolkitoption ...] [-option ...]

DESCRIPTION

You can tell xalarm to pop up warning windows at specified times before the alarm is to trigger, in order to warn you of the impending triggering of the alarm, and specify what message you want the alarm to display.

You can also make xalarm read alarm times and dates, along with the message to display in the alarm, from alarm files. This can be done once by xalarm, or you can make it read from the file periodically, as an xalarm daemon. This enables you to forget your regular or important appointments, but xalarm will tell you by popping up at the appropriate time.

In the event that the current X session is terminated before xalarm has finished, xalarm saves its alarm (if it is not already in the alarm file) so that it will automatically be restarted the next time xalarm is invoked. Any daemons connected to the display will go away.

This means that you can set an alarm even if you are likely to terminate the X session underwhich you are currently running before it triggers, and the alarm will still trigger on whatever display you are then connected to at the time.

The alarm window itself consists of a box of buttons and an area containing the alarm message. To give you an opportunity to carry on after the alarm has triggered and be late anyway, xalarm allows you to snooze the alarm. For the completely absent-minded, xalarm can also repeatedly re-trigger after a specified interval.

To help with setting the alarm, each popup displays the current time, and the alarm itself also displays the time since the alarm last triggered.

USING XALARM TO SET AN ALARM

This form is suitable for inclusion as a menu option under a window manager.

The window is also popped up if an invalid alarm or warning time is given (see below for date and time syntax), or if you specify that confirmation should be sought before setting the alarm.

The window gives you an opportunity to change the alarm setting, warning times, and the message xalarm will display when the alarm is triggered.

The popup resizes itself to edit any message larger than the space given by default. The keymap used by the Athena Dialog widget is modelled on the text buffer keymap of the editor/environment emacs(1). Text may be entered when the pointer is anywhere within the popup.

This popup window comprises of four separate windows, dealing with the alarm time, date, the warning time(s) and confirmation of all the settings (where you can also re-edit the alarm message).

If the confirmation window is popped up, then you can re-edit the alarm time, date, or warning time(s) by switching through the windows using the edit buttons. Confirmation of a window's settings is made using the enter buttons, and the translations resource is set so that the return key will do the same thing.

From the confirmation window you can also save the alarm settings in your own alarm file. You can make xalarm read alarms from this alarm file.

If confirmation is not enabled, then the window for confirmation of all settings will not be popped up even if the other windows are.

Also see the examples section.

USING XALARM TO READ AN ALARM FILE

This form is suitable for inclusion in your X start up or initialisation script. It is suited to those who start up X on a regular (eg. daily) basis.

Each line in the file should consist of an optional date on which the alarm is to trigger, optionally followed the by time and/or message. If the time and/or date are/is specified, then they must be separated from the date by a `-' on its own. If both the time and message are given, the time must come first.

If no date is specified, it is assumed to be today. If no time is specified, the alarm will trigger at the current time on whatever date is given.

The format for entries in an alarm file is therefore:

				date [- [time] [message]]
	or
				      - [time] [message]

To make it easier to put entries into the alarm file, xalarm can create them for you. You can save settings by pressing the save button in the confirmation window when you have set the alarm that you want. The settings are saved in the alarm file ~/.xalarms.

You can use XALARMFILEPATH to include alarms shared among a number of people. If a path in the list is not absolute, then it is assumed to be relative to your home directory.

Blank lines and any line with `#' or `!' as the first character are ignored. This can be used to structure and comment the alarm file.

All other command line options and resources still apply. See below for the date and time formats. Also see the examples section.

USING A DAEMON TO READ AN ALARM FILE

This form is suitable for inclusion in your X start up or initialisation script. It is suited to those whose X sessions typically span days.

The daemon behaves in the same way as invoking xalarm with the file option, except that it periodically attempts to scan the alarm file(s). The interval between scanning may be a date in the form of +days, or one of the special symbols daily (equivalent to +1) or weekly. See below for more on date formats.

Once started, the daemon immediately reads the alarm file(s), starting those alarms which are within the date given. It then sleeps until the number of days given ahead (on the following Sunday if given as weekly) at just passed midnight before trying again, ad infinitum. The daemon dies when the connection to the display is lost.

Note that any xalarm processes that the daemon invokes will try to connect to the same display each time. If you move displays, xalarm cannot know.

Also see the examples section.

TIMES

Absolute times may be suffixed with `am' or `pm', and are assumed to be in hours if given with 1 or 2 digits.

Times relative to the present time must be prefixed by `+', and are assumed to be in minutes if given with 1 or 2 digits.

The special symbols now and noon may also be used, and are equivalent to +0 and 12:00, respectively. Hours and minutes may be separated with `:', `.' or `-'.

To prevent ambiguities, hours and minutes must be in their usual ranges. If a time of an hour or more is wanted, you must state it in hours and minutes. It is not possible to specify days in the time.

The format is a super-set (by far) of the format recognised by leave(1).

Also see the examples section.

DATES

Alternatively, the date may be specified as the number of whole days into the future, by prefixing the number with `+'. The special symbols today, tomorrow and week may also be used, and these symbols may be combined. They are equivalent to +0, +1 and +7, respectively.

Note that if there is more than one word in the date, then the date must be quoted to stop the shell treating them as separate arguments.

When given as an argument to the -date option, week means ``seven days into the future''. However, when it is used as an argument to the -file or -daemon options, it means ``until the end of the current week'' (up to and including the coming Sunday), as in weekly. This is to make it easier to get xalarm to set all the alarms for the current week.

Because the alarm is set in milliseconds, you cannot set an alarm for more than 49 days into the future (on the assumption that your machine has 32-bit unsigned longs).

All symbols must consist of at least the first 3 characters of the name. Unlike calendar(1), tomorrow always means tomorrow.

Also see the examples section.

WARNINGS

Also see the examples section.

RINGING

The first two cause the terminal bell to be rung, and quiet does nothing. Otherwise it is assumed to be a shell script and is executed under a Bourne shell (sh(1)). You can also control the volume at which the terminal bell is rung.

Note that if the script contains more than one word then the whole script must be quoted to stop the shell treating them as separate arguments.

Also see the examples section.

SNOOZING AND PESTERING

Snoozing is done by selecting a time to snooze using the +mins buttons (they can be pressed as often as necessary) and pressing the snooze button. The snooze time may be zeroed by clicking on the snoozetime button (it has these two functions; display and zero). For the really lazy, the initial value of snoozetime can be set either by the relevant command line option or by its resource.

Pestering is done either by the relevant command line option or by its resource. The alarm will then re-popup after the specified interval, a bit like snooze on autopilot.

Note that if you snooze the alarm, pestering is temporarily disabled and you will have to rely on the snoozed alarm.

Also see the examples section.

MORE ON XALARM

xalarm makes maximum use of resources, as well as having a number of command line options, and these can be used to control most of the appearance of xalarm and (just about) all of its behaviour. Both command line options and useful resources are listed below.

When xalarm is invoked it immediately attempts to fork off a child and exit itself, leaving the child to continue with the alarm. The child disappears when the X session on which display xalarm is using is terminated.

You can exit from xalarm at any time by pressing the available quit button.

XMEMO, XFORTUNE & XYOW

Note that xfortune and xyow require fortune(6) and yow(6) respectively - yow(6) comes with emacs(1). Also note that since they are front ends to xmemo, you can actually give extra message text to include on the command line. If you specify a time in the future, you can edit the message text when asked to confirm (if enabled).

OPTIONS

-help

Print a (possibly) helpful usage message.

-version

Print out the version number of xalarm in the form version.patchlevel.

-restart[only]

This option makes xalarm attempt only to restart those alarms which had not finished when a previous X session was terminated.

-kill pid|all

This option sends a signal to the process number pid, or to all xalarm processes, on the current host. If the process is an xalarm, owned by you, it will exit. Note these are what ps(1) thinks are xalarm processes, and only on the current host.

-d[a]emon +days|daily|weekly

This option starts a new xalarm daemon on the current host connected to the current display. See the above description for more on alarm files, dates and daemons.

-f[ile] +days|date|today|tomorrow|weekly

This option makes xalarm read alarms from the alarm file(s). See the above description for more on the alarm file and dates.

-date +days|date|today|tomorrow|week

This option indicates the date on which the alarm is to be triggered. See the above description for more on dates.

-t[ime] +time|time|now|noon

This option indicates at what time the alarm is to be triggered. See the above description for more on times.

-w[arn] time[,time...]

Indicate the time(s) before the alarm is due to trigger when a warning should be given. They need not be in any particular order, and should be in the same format as relative times, but without the preceding `+'. Note that multiple times must be separated by commas but without spaces.

-c[onfirm]

This option overrides the resource value and forces xalarm to ask for confirmation, unless the alarm is due to trigger immediately.

-warnwords [-ww] number_of_words

Indicate the number of words from the alarm message you wish to display with the warning.

-l[ist]

List the process numbers of any xalarm processes running on the current host. Note that this lists what ps(1) thinks are xalarm processes, and only on the current host.

-r[eset] pid|all

This option sends a signal to the process number pid, or to all xalarm processes, on the current host. If the process is an xalarm, owned by you, it will pop up the confirmation window to allow you to re-edit the alarm settings. If the process is an xalarm daemon, it will have no effect. Note these are what ps(1) thinks are xalarm processes, and only on the current host.

-p[ester] time

Indicate the time that xalarm should wait before re-triggering. It should be in the same format as relative times, but without the preceding `+'.

-s[nooze] time

Indicate the time that snoozetime should initially have when the alarm triggers. It should be in the same format as relative times, but without the preceding `+'.

-alarmaudio [-aa] bell|beep|quiet|shell script

The method by which xalarm should announce the fact that the alarm has been triggered. See above for a description on the different options.

-warningaudio [-wa] bell|beep|quiet|shell script

As above, but for when any warning windows are popped up.

-q[uiet]

This is equivalent to specifying -alarmaudio quiet -warningaudio quiet, or setting the relevant resources to quiet.

-v[olume] percentage

The percentage of full volume at which the terminal bell should ring, if it is rung. This currently applies to the terminal bell only.

-nowarn [-nw]

This option overrides the resource value and forces xalarm not to give any warnings. This is the same as setting the warning times resource to the empty string.

-noconfirm [-nc]

This option overrides the resource value and forces xalarm not to ask for confirmation.

-nowarnwords [-nww]

This option overrides the resource value and forces xalarm not to display any of the alarm text with any warnings. This is the same as setting the warningwords resource to zero.

-nopester [-np]

This option overrides the resource value and forces xalarm not to re-trigger the alarm once it has popped up. This is the same as setting the pester resource to zero.

-noalarmaudio [-naa] -nowarningaudio [-nwa]

These options make the relevant resource values quiet, and are equivalent to setting the audio method to quiet.

message_text

The remaining unrecognised text is used as the message displayed with the triggering of the alarm. Note that each separate argument is assumed to be a single line, so words must be quoted if they are to appear on the same line. For example:

% xalarm "On one line" Secondline "Third line"

It is a good idea always to use quotes, even when a line is only one word. Newlines within arguments are recognised, so that input from other tools can be used:

% xalarm -time now "`fortune -l`"

Also note that xalarm deletes its copy of any arguments, including any message, given on the command line, so your boss can't see them by looking at the xalarm process.

EXAMPLES

	xclock &
	xbiff &
	xalarm -file today -confirm -warnwords 3
	exec twm

If you do not want to know about the alarms that remain from the previous X session, you could first restart them silently. Here they are restarted with warnings set at 15 and 30 minutes prior to each alarm's triggering.

To check the week's appointments, including some shared alarm files, warning 1 hour, and 30 and 15 minutes before each alarm (if you set the variable in your X initialisation script, rather than your login script, you may need to export it):

	XALARMFILEPATH=\
		/usr/local/lib/seminars.xlm:/usr/local/lib/meetings.xlm
	export XALARMFILEPATH
	xalarm -restartonly -noconfirm -warn 15,30
	xalarm -file weekly -confirm -warn 1:00,30,15

Or to start an xalarm daemon, which is to scan the alarm file on a daily basis. Each alarm should not ask for confirmation, but should give warnings 30 and 15 minutes before triggering, and pester every 5 minutes thereafter:

	xalarm -daemon daily -noconfirm -warn 15,30 -pester 5

The alarm file might contain, for example, the lines:

	# This is just a comment.
	! So is this.  Format is: date [- [time] [message]]
	!                     or:       - [time] [message]
	Wednesday - 12:30pm Football !!!
	Sun 29 september - 9pm Drag yourself home.
	Oct 4 - Contrib sometime today...

So that every Wednesday I have an alarm set for 12:30pm; on Sunday September 29 there is an alarm to be set for 9pm; on October 4 the alarm is to trigger straight away.

A twm(1) window manger entry which forces xalarm to ask for confirmation, and have the triggered alarm re-trigger every 5 minutes:

	Menu "Utilities" {
		...
		"alarm":	f.exec "xalarm -confirm -pester 5 &"
		...
	}

The following examples show how to set the alarm from the command line. It is often more convenient to invoke xalarm without specifying the time and, where necessary, the date and/or message as arguments (using a window manager, say, as above), using the popup window to enter these options.

If this was the method of entry, the option arguments would be entered in the relevant Dialog box instead, just as they appear below (except that there is no need to quote multi-word arguments).

To only restart those xalarm processes that were set before a previous X session was terminated, not including those in the alarm file:

% xalarm -restartonly

To set an alarm for tomorrow at noon, so as to avoid missing yet another meeting:

% xalarm -date tomorrow -time noon "MEETING!!!"

To set an alarm on Tuesday week (that is one week on from the next Tuesday) at 3:30 in the afternoon:

% xalarm -date "Tues week" -time 3-30pm

To set an alarm for March 10th (my very own personal public holiday), first thing in the morning, just in case I have forgotten:

% xalarm -date "10 march" -time 9am "Birthday boy!"

To set an alarm for 5 o'clock in the evening without confirmation, with the snooze time initially 10 minutes, but with the default alarm message:

% xalarm -time 5pm -snooze 10 -noconfirm

To set an alarm for 2 hours in advance, warning 1 minute and 5 minutes before it, with a message other than the default:

% xalarm -time +2.00 -warn 5,1 "Get off your bottom"

To set a completely silent alarm for 4.30 (not specifying am/pm, so it is whichever is first), with the default warnings and a message other than the default:

% xalarm -quiet -time 4:30 "Time to sneak off home!"

To reset a running xalarm we first find out its process number, and then we can reset it:

	% xalarm -list
	xalarms: 12345 12321
	% xalarm -reset 12345

% xmemo -display foo:0.0 "Bob!" "The bar for lunch?"

To display a fortune (a random adage from hell) at a specific geometry in 5 minutes:

% xfortune -geometry +10+300 -time +5

To display a Zippy quote (yow!!!), characteristically harassing you every minute and making some noise each time it triggers by executing a shell script:

% xyow -pester 1 -alarmaudio "play -v30 yow.au"

In this example, -v30 is the option to make play play the audio data in the file yow.au at maximum volume.

WIDGET HIERARCHY

	XAlarm (applicationShell)
		Alarm! (transientShell)
			alarm (form)
				buttons (form)
					quit (command)
					snooze (command)
					snooze1 (command)
					snooze5 (command)
					snooze15 (command)
					snoozetime (command)
				message (label)
		When? (transientShell)
			when (form)
				time (dialog)
					label (label)
					value (asciiText)
					ok (command)
					editdate (command)
					editwarnings (command)
					quit (command)
				date (dialog)
					label (label)
					value (asciiText)
					ok (command)
					edittime (command)
					editwarnings (command)
					quit (command)
				warnings (dialog)
					label (label)
					value (asciiText)
					ok (command)
					edittime (command)
					editdate (command)
					quit (command)
				confirm (dialog)
					label (label)
					value (asciiText)
					ok (command)
					cancel (command)
					save (command)
					quit (command)
		Warning! (transientShell)
			warning (form)
				dismiss (command)
				message (label)
				reset (command)
				quit (command)

EXAMPLE RESOURCES

	! For some nice colours...  If you have X11R5:
	*customization:				-color
	! Otherwise:
	XAlarm*background:			LightYellow
	XAlarm*foreground:			IndianRed
	XAlarm*Command.background:		IndianRed
	XAlarm*Command.foreground:		LightYellow
	XAlarm.When?.when.Dialog.background:	MidnightBlue
	XAlarm.Warning!.warning.background:	HotPink
	XAlarm.Alarm!.alarm.background:		DarkGreen
	! This is what you normally get...
	XAlarm*background:			White
	XAlarm*foreground:			Black
	XAlarm*Command.background:		Black
	XAlarm*Command.foreground:		White
	! Perhaps the most commonly used resources...
	XAlarm.confirm:				True
	XAlarm.warnings:			5,15
	XAlarm.warningwords:			0
	XAlarm.pester:				0
	XAlarm.snooze:				0
	XAlarm.volume:				50
	XAlarm.alarmaudio:			bell
	XAlarm.warningaudio:			bell
	! If the fonts are not to your taste, try "-new century schoolbook-"
	! instead of "-times-".
	XAlarm*font: -*-times-bold-r-*-*-14-*-*-*-p-*-iso8859-1
	XAlarm.When?.when.confirm.value*font: -*-times-bold-i-*-*-14-*-*-*-p-*-iso8859-1
	XAlarm.Alarm!.alarm.message.font: -*-times-bold-i-*-*-34-*-*-*-p-*-iso8859-1
	! If you want a more compact alarm window, try these...
	XAlarm.Alarm!.alarm.buttons.snooze1.fromVert:	quit
	! This will vary depending on button labels & font...
	XAlarm.Alarm!.alarm.buttons.snooze1.horizDistance:	-93
	XAlarm.Alarm!.alarm.buttons.snooze5.fromVert:	quit
	XAlarm.Alarm!.alarm.buttons.snooze15.fromVert:	quit
	XAlarm.Alarm!.alarm.buttons.snoozetime.fromHoriz:	snooze
	! Plus, if you want...
	XAlarm.Alarm!.alarm.message.fromHoriz:		buttons
	! This will vary depending on button labels & font...
	XAlarm.Alarm!.alarm.message.vertDistance:		-33
	! Some other defaults...
	XAlarm.Alarm!.alarm.background:		Black
	XAlarm.Alarm!.alarm.message.label:		Alarm Call!!!
	XAlarm.Alarm!.alarm.buttons.quit.label:	Quit
	XAlarm.Alarm!.alarm.buttons.snooze.label:	Snooze
	XAlarm.Alarm!.alarm.buttons.snooze1.label:	+1 min
	XAlarm.Alarm!.alarm.buttons.snooze5.label:	+5 mins
	XAlarm.Alarm!.alarm.buttons.snooze15.label:	+15 mins

TOOLKIT OPTIONS

-display display

This option specifies the X server to contact.

-geometry geometry

This option specifies the preferred size and position of xalarm. It is a little meaningless to specify a size; it is as large as need be.

-xrm resourcestring

This option specifies a resource string to be used. This is especially useful for setting resources that do not have separate command line options.

ENVIRONMENT

DISPLAY

to get the default host and display number.

XENVIRONMENT

to get the name of a resource file that overrides the global resources stored in the RESOURCE_MANAGER property.

XALARMFILEPATH

a colon separated list of file names to be used in conjunction with ~/.xalarms for xalarm to look for alarms to set.

USER

The user's login name. This may be used by xalarm when looking for the user's name for the alarm title, or the user's xalarm processes.

HOME

The user's home directory. This may be used by xalarm when looking for the user's alarm file.

FILES

~/.xalarms

The name of the alarm file looked at by xalarm for alarms to set and where alarms are saved. See also the environment variable XALARMFILEPATH.

~/.xalarms.died

The name of the alarm file where xalarm stores its alarm which had not finished when the X session under which it was running was terminated.

SEE ALSO

BUGS

Preamble:

Because of the way xalarm has evolved (it started as a 24-hour period one-off alarm clock), its dealing with dates, alarm files and the interface to these is not ideal. Nobody said evolution was perfect.

If you want to report a bug, or anything else, please first give as much information as you can. See COMMENTS at the end of the manual.

General:

Each alarm is a separate, forked, xalarm process, each with its own connection to the display. There is no way to get xalarm to set more than one alarm or to display on several displays at once.

Because xalarm is one of those clients you tend to start from a window manager or from an X initialisation script, you may not see error messages that these xalarm processes write to standard error. You will only see them if this output also goes to, or is redirected to, your display.

If your shell initialisation script does any output, xalarm may get confused when trying to list other xalarm processes (and therefore also when killing or resetting all xalarm processes).

Daemons:

If you terminate the session which an xalarm daemon is running under, the daemon does not exit until just before it re-tries to start new alarms from the alarm file. It is possible, but unlikely, that someone else may have got your particular display connection (not physical display) in the meantime. xalarm cannot know when this happens.

It would be nice to be able to tell daemon and normal xalarm processes apart when listing them.

Saving to file:

The date saved in the alarm file is the exact date the alarm would trigger, not the date specified in the date input popup window. Both types of behaviour have their advantages, but only this behaviour is implemented.

The same happens with those alarms that are saved when the X session under which they are running is terminated. This type of behaviour does seem more useful than the alternative.

Currently does not satisfactorily save alarms with multi-line messages.

Restarting:

Because uncompleted alarms are saved in the same format as the alarm file format, the resource environment of restarted alarms is inherited from the xalarm which restarted them. This is not necessarily the same as the original resource environments of these alarms.

Times & Dates:

xalarm is at the mercy of the system clock.

The message informing at what time xalarm is to trigger may appear to be wrong if the clocks go forwards or backwards between the present and the time it is due to trigger.

If the time is relative to the present and confirmation is sought, the alarm and warnings are set from when the time is confirmed, not from when xalarm was invoked.

Date and symbol names are recognised by the first three characters only, the rest are ignored. This is why week and weekly are equivalent, and midday and midnight are not implemented. There is no real wild carding within dates.

You can only set an alarm that will trigger within the next 49 days (on the assumption that your machine has 32-bit unsigned longs).

Editing:

The dialog box uses a subset of the emacs(1) editor/environment keymap for text buffers (which is certainly not a bug!).

However, the return key event is translated by default into the confirm button event, as it is translated similarly in the alarm time and warning dialog boxes. To insert a newline, use ctrl-m (since under emacs(1) the return key is a synonym for ctrl-m, under X they generate different events), or just change the relevant resource(s) so that return produces the desired effect. The resources, followed by the necessary value, are:

XAlarm.When?.time.value.translations

XAlarm.When?.date.value.translations XAlarm.When?.warnings.value.translations XAlarm.When?.confirm.value.translations

#override <Key>Return: newline()

Resetting & Killing:

Signalling is implemented very simply, and if the process signalled is not an xalarm, strange things may occur. Usually, nothing will happen.

However, killing does not use the KILL signal, and is therefore relatively safe to use even though your ps(1) can never be 100% reliable.

Still, this can mean that when you reset or kill all xalarm processes, not all will have been signalled.

Input:

Doesn't take input from a pipe etc.

Audio:

Doesn't parse the alarm or warning message to produce voice output(!)

COPYRIGHT

AUTHOR

CONTRIBERS

Big thanks yet again have to go to Gisle Hannemyr, Norsk Regnsesentral (NCC), J Braham Levy, UDSP Lab, University of Keele and Ex-Tek Associates (UK), and Stefan Haenssgen, Informatik Rechnerabteilung, University of Karlsruhe, for their help with ideas, comments and code, in the making of xalarm version 3.03. Thanks also to Paul Moore and Kirk Morgan for their help in porting xalarm for versions 3.04 and 3.05.

For version 3.06, look no further than Charles Durst.

For getting version 3 from version 2 in the first place, thanks have to go to Bill Leonard, Harris Computer Systems Division, Florida, for harassing me with suggestions for improvements to make xalarm version 3 a useful tool and this manual page easier to understand, and Andreas Stolcke, International Computer Science Institute, Berkeley, for his help fixing code. Without both, xalarm would still be pretty much as version 2.

Thanks also to J Braham Levy, Stefan Haenssgen, Jamie Zawinski, Jason Venner and Kimmo Suominen for their help with version 3.

For their help and suggestions with xalarm "over the years", I would also like to thank (in no real order) Steve Aronson, Dave Brooks, Reiner Hammer, Jay Lawlor, Janet Anstett, Gordon Freedman, Francois-Regis Colin and Jeffrey Mast. If I've missed anyone, sorry.

COMMENTS