=pod

=encoding UTF-8

=head1 NAME

dclock - digital clock for X

=head1 SYNOPSIS

B<dclock> [-I<toolkitoption> ...] [-option ...]

=head1 DESCRIPTION

The I<dclock> program displays the time in digital format only. The time
is updated on a per second basis or on a per minute basis. This program
is nothing more than a wrapper around the dclock widget not associated
with any particular widget set.

When the clock is running, the user may change attributes by typing:

=over 4

=item E<32>E<32>B<r>     Toggles B<Reverse Video>.

=item E<32>E<32>B<s>     Toggles the B<seconds> display.

=item E<32>E<32>B<b>     Toggles the B<bell> attribute.

=item E<32>E<32>B<j>     Toggles the B<jump/scroll> attribute.

=item E<32>E<32>B<f>     Toggles the B<fade> attribute.

=item E<32>E<32>B<d>     Toggles the B<date> format.

=item E<32>E<32>B<u>     Toggles the location of B<date> (top/bottom).

=item E<32>E<32>B<m>     Toggles the B<military time> format.

=item E<32>E<32>B<a>     Toggles the B<alarm> clock.

=item E<32>E<32>B<t>     Toggles the B<tails> attribute.

=item E<32>E<32>B<:>     Toggles the B<blinking> colon.

=item E<32>E<32>B</>     Increases the tilt of the numbers.

=item E<32>E<32>B<\>     Decreases the tilt of the numbers.

=item E<32>E<32>B<+>     Increases the thickness of the numbers.

=item E<32>E<32>B<->     Decreases the thickness of the numbers.

=item E<32>E<32>B<E<gt>>     Increases the spacing between numbers.

=item E<32>E<32>B<E<lt>>     Decreases the spacing between numbers.

=item E<32>E<32>B<q>     quits the program.

=back

The third mouse button puts the clock in the mode where the alarm clock
can be set. The alarm must be set in 24-hour format to distringuish
between am and pm time. Digits can be changed by selecting the digit
with the left or middle mouse button. The Left button advances the time
while the Middle button moves the time backwards. Using the left or
middle button over the text at the bottom of the clock toggles the alarm
from actually being set (or, use the 'a' key).

=head1 OPTIONS

I<Dclock> accepts all of the standard X Toolkit command line options
along with the additional options listed below:

=over 4

=item B<-help>

This option indicates that a brief summary of the allowed options should
be printed on the standard error.

=item B<-bell>

=item B<-nobell>

This option, if enabled, indicates that the bell will beep once on the
half hour and twice on the hour.

=item B<-bellFile> I<filename>

This specifies a sound file to use to play the dclock hourly chime. If
unspecified, or the string C<NULL> is used, the system beep is used
instead. The sound file format must be understood by the executable
specified by option C<audioPlay>. The C<NULL> value is a means to
override a system-level setting to disable external sound playing.

=item B<-miltime>

=item B<-nomiltime>

This option, if enabled, causes the clock to display the time in 24 hour
(military) time format.

=item B<-utc>

=item B<-noutc>

This option, causes the clock to display the UTC (GMT) time rather than
the default local time.

=item B<-tails>

=item B<-notails>

This option places [or removes] C<tails> on the digits 6 and 9.

=item B<-scroll>

=item B<-noscroll>

When the time changes, the digits scroll from the previous digit to the
next digit. The -noscroll option turns the behavior off.

=item B<-blink>

=item B<-noblink>

The colon separating hours from minutes blinks on and off once per
second. With the -noblink option, it remains on permanently.

=item B<-persist>

=item B<-nopersist>

This option determines whether or not the clock display remains in the
reverse video state after the alarm goes off.

=item B<-fade>

=item B<-nofade>

This option, when enabled, causes the display to fade from one digit to
the next instead of jumping or scrolling. If fade is specified, the
scroll attribute will be automatically disabled.

=item B<-fadeRate> I<n>

The fadeRate attribute takes an integer value which specifies the number
of milliseconds to wait between iterations when fading from one digit to
the next. A larger value will make the fade slower and more pronounced.
The default is 50.

=item B<-audioPlay> I<filename>

Specifies an executable to use to play audio files for the bell and
alarm. The default is none, which falls back to using the system bell
for both the dclock bell and alarm.

=item B<-date> I<C<format>>

The date is printed under the time in the specified font. The string
displayed is in the C<format> argument. The format corresponds to the
system call strftime() (see strftime(3)).

  dclock -date "Today is %A"

Useful examples of strftime() formatting:

=over 2

=item E<32>E<32>B<%A>     Full weekday name

=item E<32>E<32>B<%a>     Three-char weekday name (Sun, Mon, Tue...)

=item E<32>E<32>B<%B>     Full month name

=item E<32>E<32>B<%b>     Three-char month name (Jan, Feb, Mar...)

=item E<32>E<32>B<%d>     The date (numerical day number of the month)

=item E<32>E<32>B<%Y>     Full year (4 digits)

=item E<32>E<32>B<%y>     2-digit year number

=back

E<10>

=item B<-dateup>

By default, the date string is at the bottom of the display. This option
starts it at the top, instead.

=item B<-alarm>

=item B<-noalarm>

The alarm is turned on or off. Alarm rings bell and toggles reverse
video.

=item B<-alarmTime> I<HH:MM>

If alarm is set, it goes off at time specified in 24-hour format.

=item B<-alarmFile> I<filename>

This specifies a sound file to use to play the dclock alarm. If
unspecified, or the string C<NULL> is used, the system beep is used
instead. The sound file format must be understood by the executable
specified by option "audioPlay". The C<NULL> string is a means to
override a system-level setting to disable external sound playing.

=item B<-seconds>

This option will update the clock every second and display the time
including the seconds.

=item B<-slope> I<value>

Sets the angle of the digits according to the (floating-point) slope
value value.

=item B<-thickness> I<width_factor>

Sets the segment thickness as a (floating-point) ratio to digit width.

=item B<-spacing> I<space_factor>

Sets the digit spacing as a (floating-point) ratio to digit width.

=item B<-smallsize> I<space_factor>

Sets the seconds digit size as a (floating-point) ratio to the digit
size of the minutes and hours digits.

=item B<-second_gap> I<space_factor>

Sets the spacing of the seconds digits from the other digits as a
(floating-point) ratio to digit width.

=item B<-bg> I<color>

This option specifies the color to use for the background of the window.
The default is ``darkslategray''.

=item B<-bd> I<color>

This option specifies the color to use for the border of the window. The
default is ``black''.

=item B<-bw> I<number>

This option specifies the width in pixels of the border surrounding the
window.

=item B<-fg> I<color>

This option specifies the color to use for displaying text and digit
segments. The default is ``chartreuse''.

=item B<-led_off> I<color>

This option specifies the color to use for displaying digit segments
when turned off. The default is ``darkgreen''.

=item B<-fn> I<font>

This option specifies the font to be used for displaying normal text.
The default is ``Fixed''.

=item B<-geometry> I<geometry>

This option specifies the preferred size and position of the clock
window.

=item B<-display> I<host>:I<display>

This option specifies the X server to contact.

=item B<-xrm> I<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.

=back

=head1 X DEFAULTS

It understands all of the core resource names and classes as well as:

=over 4

=item B<geometry (>class B<Geometry)>

Specifies the width and height and, optionally, the preferred position
of the clock.

=item B<foreground (>class B<Foreground)>

Specifies the color for the digits. Using the class specifies the color
for all things that normally would appear in the foreground color. The
default is ``chartreuse''.

=item B<background (>class B<Background)>

Specifies the background color, by default ``DarkSlateGray''.

=item B<led_off (>class B<Foreground)>

Specifies the color of the digit segments when ``off''. This can be set
to be the background color, or it can be set to a color just slightly
different from the background, matching the segment colors, to give just
a hint of color. Default ``DarkGreen'' works well with the default
segment color of ``chartreuse''.

=item B<bell (>class B<Boolean)>

Specifies whether or not a bell should be rung on the hour and half
hour.

=item B<font (>class B<Font)>

Specifies the font to be used for the date.

=item B<militaryTime (>class B<Boolean)>

Specifies whether the military (24hr) time format should be used.

=item B<utcTime (>class B<Boolean)>

Specifies whether UTC (GMT) time should be used, rather than local time.

=item B<reverseVideo (>class B<ReverseVideo)>

Specifies that the foreground and background colors should be reversed.

=item B<scroll (>class B<Boolean)>

Specifies whether the digits should scroll or not.

=item B<fade (>class B<Boolean)>

Specifies whether the digits should fade or not.

=item B<fadeRate (>class B<Time)>

The number of milliseconds of delay between iterations of fading.

=item B<seconds (>class B<Boolean)>

Specifies whether the seconds should be displayed or not.

=item B<tails (>class B<Boolean)>

Specifies whether tails should be put on the digits 6 and 9.

=item B<date (>class B<String)>

Specifies the date format to use. The format corresponds to the system
call strftime() (see strftime(3)).

=item B<dateUp (>class B<Boolean)>

Specifies whether the date is shown at the top or at the bottom.

=item B<blink (>class B<Boolean)>

Specifies whether the colon separating hours from minutes should blink
on and off once per second or remain on permanently.

=item B<alarm (>class B<Boolean)>

Specifies whether the alarm should go off at the specified time
(alarmTime).

=item B<alarmTime (>class B<String)>

Specifies the time alarm goes off if alarm is set.

=item B<alarmPersist (>class B<Boolean)>

Specifies whether the alarm should remain in reverse video after the
alarm goes off, or return to normal video.

=item B<angle (>class B<Float)>

Defines the slope of the digits (default 6).

=item B<smallRatio (>class B<Float)>

Defines the size of the seconds digits compared to the minutes digits
(default 2/3).

=item B<secondGap (>class B<Float)>

Defines the amount of space between the minutes digits and the seconds
digits (default 0.3).

=item B<widthFactor (>class B<Float)>

Determines the width of segments as a ratio to digit width (default
0.13).

=item B<spaceFactor (>class B<Float)>

Determines the spacing between digit as a ratio to digit width (default
0.09).

=item B<bellFile (>class B<String)>

Specifies an audio file to play for the hourly bell (no default).

=item B<alarmFile (>class B<String)>

Specifies an audio file to play for the alarm (no default).

=item B<audioPlay (>class B<String)>

Specifies an executable to use to play the bell and alarm audio files,
if they are specified. Otherwise, the system bell is used (default is
F</usr/bin/play>).

=back

=head1 ENVIRONMENT

=over 4

=item B<DISPLAY>

To get the default host and display number.

=item B<XENVIRONMENT>

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

=back

=head1 SEE ALSO

B<xrdb>(1),
B<strftime>(3),
B<X>(7).

=head1 BUGS

Dclock believes the system clock.

Scrolling from 9 to 10 O'Clock seems weird, but chances are you won't
notice it.

Scrolling can take so long that dclock may lag behind system time by a
fraction of a second and eventually skip a second to catch up. In modern
times, it should be dealing with this by tracking seconds with a
separate thread.

=head1 COPYRIGHT

Copyright (c) 1988, Dan Heller. Revisions copyright (c) 1993 and 1999,
Tim Edwards.

=head1 AUTHOR

Original dclock by Dan Heller (1988) <argv@sun.com> or
<dheller@cory.berkeley.edu>

Fade & tails by Steve Reinhardt, <steven@fts.webo.dg.com>

Derived geometry by Tim Edwards (1993) <tim@stravinsky.jhuapl.edu>

Antialiasing, color fades, and audio play by Tim Edwards (1999)
<tim@stravinsky.jhuapl.edu>

Manual page in POD format by Ricardo Mones (2023) <mones@debian.org>
