.TH xcuckoo "" "" "X Application"
.PC "Cuckoo clock for X"
\fBxcuckoo
[\-command \fIcommand\^\fB]
[\-display \fIdisplay\^\fB]
[\-icon] 
[\-mode replace|append|prepend\^\fB]
[\-separator \fIstring\^\fB]
[\-update \fIseconds\^\fB]
[\-version]
[\-wait \fIseconds\^\fB]
[\-window \fIname\^\fB]\fR
.PP
.B xcuckoo
is an X application that, like its avian cousin, lays its eggs in
another's nest.
In its basic form,
.B xcuckoo
is a clock that displays the time in the form \fIhh\fB:\fImm\fR.
Alternatively, the display may be the
one-line output of an arbitrarily selected command.
The nest into which the egg is laid is the title bar of some window.
.PP
.B xcuckoo
runs until either it is terminated via one of the signals
.BR SIGHUP ,
.BR SIGINT ,
.BR SIGQUIT ,
or
.BR SIGTERM ,
or the host window no longer exists when it attempts to update the
title bar.
Upon termination,
.B xcuckoo
restores the original contents of the title bar, should that window still exist.
.SH "Command-line Options"
.B xcuckoo
recognizes the following command-line options:
.IP "\fB\-command \fIcommand\fR"
Display the output of
.IR command ,
instead of the default four-digit clock.
.IP "\fB\-display \fIdisplay\fR"
Open
.IR display .
.IP \fB\-icon\fR
Also take over the window's icon name.
.IP "\fB\-mode [replace|append|prepend]\fR"
How the output should relate to the normal contents of the title bar.
In
.B replace
mode, the egg replaces the normal contents of the bar;
in
.B append
mode, the egg is written to the right of the normal contents; and in
\fBprepend\fR (\fIsic\fR) mode, it is written to the left.
The default mode is
.BR replace .
.IP "\fB\-separator \fIstring\fR"
Write
.I string
between the egg and the normal contents of the title bar, should the mode be
.B appendn
or
.BR prepend .
.IP "\fB\-update \fIseconds\fR"
Update the egg after
.IR seconds .
The default is 60.
.IP \fB\-version\fR
Print the version number on standard output, then exit.
.IP "\fB\-wait \fIseconds\fR"
Wait
.I seconds
before abandoning attempts to locate the target window.
This is useful in startup scripts, when the target cannot be guaranteed to be
available immediately.
.IP "\fB\-window \fIname\fR
Lay the egg into the title bar of
.IR window .
.PP
Executing xcuckoo with no options is equivalent to executing
.DM
	xcuckoo -window 'TWM Icon Manager' -command 'date "+%H:%M"' \e
        	-mode replace -update 60 -wait 0
.DE
.PP
except that
.B date
is not actually executed \(em rather,
.B xcuckoo
calls
.BR localtime() .
.SH Resources
xcuckoo recognizes top-level resources stored in the
.B RESOURCE_MANAGER
property of the server's root window that have the same names as the
option keywords, except for
.BR display ,
as the display has to be opened in order to read the property and version.
They are as follows:
.DM
.ta 0.5i 2.0i
      window:	TWM Icon Manager
      icon:	false
      command:	date "+%H:%M"
      mode:	replace
      separator:	<space>
      update:	60
      wait:	0
.DE
.PP
Any value other than
.B true
for the icon resource is equivalent to
.BR false .
.SH Examples
The first example displays the current date and time every 30 seconds
to the left of the window name in the mailbox window:
.DM
	xcuckoo -window mailbox -command date -mode append -wait 30
.DE
.PP
The next example displays the number of users every 50 minutes in the
title bar of the root window:
.DM
	xcuckoo -command 'echo `who | wc -l` users' -update 3000
.DE
.PP
Finally, the next example displays a fortune (or its first line, at any rate)
every 30 seconds in the title bar of the
.B xterm
window:
.DM
	xcuckoo -command /usr/games/fortune -update 30
.DE
.SH "Environmental Variables"
.B xcuckoo
reads the environmental variable
.BR DISPLAY ,
which gives the number of the default host and display.
.SH "See Also"
.B
X,
X applications
.R
.SH Notes
Just like real cuckoos,
.B xcuckoo
may lay its eggs in more than one nest.
If the host application is terminated and its window identifier
reallocated before the next update takes place, then
.B xcuckoo
will be unaware that anything has happened and
proceed to impose on the new owner.
Of course, you are at liberty to interpret this behavior as a feature.
.PP
.II "Wight, Jim"
.II "Tomlinson, Gerry M."
.II "Marshall, Simon"
.II "Strickland, Malcolm"
.B xcuckoo
was written by
Jim Wight (j.k.wight@newcastle.ac.uk), of the
Computing Laboratory, The University, Newcastle upon Tyne, UK, NE1 7RU.
The idea was originally conceived by
Gerry M Tomlinson <gerry.tomlinson@newcastle.ac.uk>;
in fact an early version was called
.BR xgmt .
Simon Marshall <S.Marshall@uk.ac.hull.seq> and Malcolm Strickland 
<chuck-strickland@orl.mmc.com> provided ideas for enhancements.
