.TH CLOCKALRM 1 "5 October 2001"
.SH NAME
clockalrm \- analogue (alarm) clock on text console
.SH SYNOPSIS
clockalrm OPTIONS
.SH DESCRIPTION
.B clockalrm
Shows analogue time on a text terminal.
.SS
Options
.TP 8
\fB-a ...\fR, \fB--alarm\fR=\fBMINUTES\fR[:\fBSECONDS\fR]
Sound alarm minutes/seconds before termination.
.TP 8
\fB-b\fR, \fB--bell-no\fR
Silent alarm.
.TP 8
\fB-c\fR, \fB--countdown\fR
Show analogue countdown clock.
.TP 8
\fB-C\fR, \fB--countdown-digital\fR
Digital countdown [YEARS:[DAYS:]]HOURS:MINS:SECS.
Displays YEARS as exactly 365 * 24 * 60 * 60-seconds intervals to go, 
not calender-years (an average calender-year is about 365.256 24h-days).
.TP 8
\fB-d ...\fR, \fB--date\fR=\fBDATE\fR
Terminate at date/time.  If a timezone is present (see below) date/time
is relative to it.
DATE can be given in formats (`.' can be any character, YMDHMS must be
0-9):

YYYY.MM.DD.HH.MM.SS (year.month.day.hour.minutes.seconds)
.br
DD\fB-\fRMM.YYYY.HH.MM.SS (day-month-year hour:minutes:seconds)
.br
MM\fB/\fRDD.YYYY.HH.MM.SS (month/day/year hour:minutes:seconds)
.br
HH.MM.SS (hour:minutes:seconds) Assumes present day.
.TP 8
\fB-e\fR, \fB--exit\fR
Print perceptions of time, then exit (debugging).
.TP 8
\fB-f\fR, \fB--fixed\fR
Use `H', `m', `s' to print clock arms.
.TP 8
\fB-g\fR, \fB--graphic\fR
Print arms ASCII-art style.
.TP 8
\fB-h\fR, \fB--help \fR
Print usage.
.TP 8
\fB-j ...\fR, \fB--set-colors\fR=\fBCOLOR[,COLOR[,COLOR[,...]]]\fR
Define colors list for the clock. Argument expects pairs of colors,
first foreground then background. These pairs are ordered: hour-arm,, 
minute-arm,, second-arm,, second-alarm-arm,, medal-background,.
Colors can be: black, blue, cyan, green, magenta, red, white, yellow, or
`\fBnop\fR'. `\fBnop\fR' does not alter the given color.

Example: 
--set-colors=cyan,green,cyan,red,cyan,magenta,red,black,black,blue
.TP 8
\fB-k ...\fR, \fB--sec-color\fR=\fBCOLOR\fR
Change color of second arm to black, blue, cyan, green, magenta, red, white, yellow.
.TP 8
\fB-K ...\fR, \fB--sec-color-alarm\fR=\fBCOLOR\fR
Change color of second arm during alarm to black, blue, cyan, green, magenta, red, white, yellow.
.TP 8
\fB-l\fR, \fB--little\fR
Smaller clock.
.TP 8
\fB-m\fR, \fB--medal\fR
Creates visible clock backdrop:
sets erase character to `\fB.\fR' and
sets foreground color of backdrop to blue.
See --print and  --set-colors for more control.
.TP 8
\fB-n\fR, \fB--no-sec-arm \fR
No seconds arm.
.TP 8
\fB-o ...\fR, \fB--offset\fR=\fBMINUTES\fR[\fB:SECONDS\fR]
Apply offset to --date option; positive for to the future, negative
towards the present. If no --date option, relative to the present.
.TP 8
\fB-p ...\fR, \fB--print\fR=\fB123\fR[\fB4\fR]
Character to print when not in --graphic mode for
1) hour, 2) minute, 3) second arm. 4) for the
background, 4) also applies in --graphic mode.

Cheat:
.br
`\fB--print\fR=\fBempty\fR' equals '--print=\ \ \ \ '
.br
`\fB--print\fR=\fBfizzz\fR' equals '--print=@^\ ^_'
--set-colors=nop,nop,nop,nop,nop,nop,nop,nop,green,nop
.br
`\fB--print\fR=\fBknitted\fR' equals  --print=XXXX
--set-colors=nop,nop,nop,nop,yellow,nop,yellow,nop,red,nop
.br
`\fB--print\fR=\fBknitted2\fR' equals  --print=XXXX
--set-colors=nop,nop,nop,nop,cyan,nop,cyan,nop,blue,nop
.br
`\fB--print\fR=\fBnomedal\fR' equals --set-colors=nop,nop,nop,nop,nop,nop,nop,nop,black,black
.br
`\fB--print\fR=\fBnormal\fR' equals '--print=Hms\ '
.br
`\fB--print\fR=\fBshade\fR' equals '--print=\\/\ /' 
--set-colors=nop,nop,nop,nop,nop,nop,nop,nop,magenta,nop
.br
`\fB--print\fR=\fBsimple\fR' equals '--print=\ \ \ \ '
--set-colors=blue,green,blue,red,blue,magenta,red,black,black,blue
.br
`\fB--print\fR=\fBterse\fR' equals '--print=...\ ' --sec-color blue
.br
`\fB--print\fR=\fBwakeup\fR' equals '--print=\ \ \ \ '
--set-colors=red,black,red,black,black,black,black,magenta,white,black 
--when-no
.TP 8
\fB-q\fR,\fB--quotidian\fR
Print week day name and month day number inside the clock, wrist-watch
style.
.TP 8
\fB-s ...\fR, \fB--sleep\fR=\fBSECONDS\fR
Let program sleep between sampling time, this also affects the beeps
of --alarm. Default is 1 second, 0 may produce curious alarms (and high
program load).
.TP 8
\fB-t ...\fR, \fB--text\fR=\fBTEXT\fR
Display text in upper/left corner.
.TP 8
\fB-u\fR, \fB--utc\fR, \fB--gmt\fR
Use UTC/GMT, instead of local time.
.TP 8
\fB-v\fR, \fB--version \fR
Print version
.TP 8
\fB-w\fR, \fB--when-short\fR
Always print time in HH:MM:SS format.
.TP 8
\fB-W\fR, \fB--when-full\fR
Always print time in words/numbers, complete date.
.TP 8
\fB-0\fR, \fB--when-no\fR
Never print time in words/numbers.
.TP 8
\fB-x\fR, \fB--am-pm \fR
Print AM, PM.
.TP 8
\fB-z ...\fR, \fB--zone\fR=\fBHOURS\fR[\fB:MINUTES\fR[\fB:SECONDS\fR]]
Give a current time offset. When clockalrm runs in local time
(no --gmt, --utc or -u argument), the offset is applied to local time
and follows local daylight savings time.
.TP 8
\fB-Z\fR, \fB--zero\fR
Give timezone offset causing the present to be 1 Jan 1970 00:00:00,
beginning of Epoch (count-up clock).
./.SH NOTE
./Alarm and exit moment is fixed to clock coordinates, not duration interval:
./if a daylight savings time switch happens, this will alter the duration up
./to alarm and exit.
.SH BUGS
Seems to work, but is not completely tested.
.SH AUTHOR
Jos.H.Boersema
.SH License
You are free to copy under the terms of the GNU General Public License.

Clockalrm is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; version 2 of the License, or (at your
option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software Foundation,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA