SUNCLOCK(1)

NAME
sunclock - show illuminated portion of Earth

SYNOPSIS
sunclock [ options ]

DESCRIPTION
sunclock is an X11 application that displays a map of the Earth and indicates the illuminated portion of the globe by drawing sunlit areas dark on light, night areas as light on dark. It also displays the current date and time. It is possible to define locations on the main map that will display a place name. If the user clicks on one of these places the time display will change to the timezone of that location.

OPTIONS
The program does not use the X Toolkit, and hence only those options explicitly enumerated below may be used. Neither are any resources used.

-version
    Show program version and patch level, and then exit.

-display dispname
    Give the name of the X server to contact.

-iconic
    Start iconic. Usually you will want to specify this option.

-geometry +x+y
    Specify the position of the window. Only the position is used; any size information given is ignored.

-icongeometry +x+y
    Specify the position of the icon. Only the position is used; any size information given is ignored.

-animateicon

-a  Animate the icon by continuous scrolling. Many window managers permit only a fixed icon size of 64x64 pixels. This option makes the whole icon map visible over time.

-fg Colour
    Set the foreground colour to 'Colour'. This is the colour which is used to draw the map outline in the daylight areas.

-bg Colour
    Set the background colour to 'Colour'. This is the colour which is used for the background in the daylight areas. Night areas are shown with foreground and background colours reversed.

Users may keep a file in their home directory called ~/.sunclockrc. This file can contain lines of the following format:

[+]name latitude longitude timezone

where name is the ascii name of the place to be shown on the map. If the name starts with a '+', the label will be displayed above the dot instead of below. latitude and longitude are floating point numbers representing the geographical location of the place. Western longitudes and southern latitudes should be entered as negative numbers. timezone is the name of the timezone that the place is in. This should be the name of a file under /usr/share/zoneinfo; incorrect timezones cause the clock to display GMT. It is also possible to reference a file in a directory relative to /usr/share/zoneinfo, for example Canada/Eastern instead of EST5EDT.

The user may click on the dot on the map associated with a place defined in the .sunclockrc file. When this is done, the time displayed will now be shown in the timezone for that location.

HOW IT WORKS
sunclock calculates the position of the Sun using the algorithm in chapter 18 of:

Astronomical Formulae for Calculators by Jean Meeus, Third Edition, Richmond: Willmann-Bell, 1985.

and Mercator projects the illuminated area onto map image. The Sun's position is calculated to better than one arc-second in accuracy.

BUGS
The maps are not rescaled if you resize the open window or icon. (I don't want to have to store a vector database for the map.) The program contravenes section 4.1.9 of the ICCCM in that its icon window is a fixed size, and any WM_ICON_SIZE property of the root window is ignored.

The illuminated area shown is the area which would be sunlit if the Earth had no atmosphere. The actual illuminated area is larger because of atmospheric refraction and twilight.

AUTHOR
John Mackin, Basser Department of Computer Science, University of Sydney, Sydney, Australia; <john@cs.su.oz.AU>. Based on a Suntools program by John Walker, Autodesk, Inc.; <kelvin@acad.uu.NET>.

Stephen Martin, Fujitsu Systems Business of Canada, smartin@fujitsu.ca; added support for interactive map.

Wolfram Gloger, wmglo@dent.med.uni-muenchen.de; added animation of icon, miscellaneous minor fixes.