README for Sunclock version 3.xx -------------------------------- Sunclock is a sophisticated clock for the X Window system. It is based on an earlier version by John Mackin, itself derived from the Suntools program by John Walker. Many possibilities of the original astronomy routines are now exploited. Sunclock displays a map of the Earth and shows which portion is illuminated by the sun. It can commute between two states, the "clock window" and the "map window". The clock window displays a small map of the Earth and therefore occupies little space on the screen, while the "map window" displays a large map and offers more advanced functions. The map window can work in five different modes: - "Legal time" mode: legal time of default time zone and GMT time are displayed. - "Coordinate" mode: by clicking on a city, users get coordinates (latitude, longitude) of that city, legal time and sunrise/sunset. - "Solar" mode: by clicking on a point of the map (either a city or another point), solar time and day length are shown. - "Hour Extension" mode: displays solar times from 00:00 to 23:00 in bottom strip, according to the Sun position. - "Distance" mode: shows distances in km and miles between two arbitrary locations. - "Progress" mode: allows to accelerate the evolution of time, so as to observe the evolution of day/night periods and seasons. Meridians, Parallels, Equator, Tropics and Arctic circles can also be drawn. All these actions are performed through mouse clicks on the map or on the bottom strip, and/or with keyboard shortcuts. There is inline help available by typing 'h' or by clicking on the bottom strip -- so that no further explanation should be needed. Commuting between the clock and map states is obtained by typing '!' or simply <Space>. Starting from version 3.20, the sunclock package includes a vector map of the Earth (loosely derived from the xearth package by Kirk Lauritz Johnson), which is capable of building Earth maps of arbitrary sizes without losing the accuracy of details (within certain limits...) If you are using a monochrome display, there are options -mono and -invert that will enable sunclock to run in spite of the low resources. Under pseudocolor displays (depth <= 8), it might be useful to use the -private option. However (starting from version 3.30), sunclock has a builtin machanism which automatically quantizes true-color Earth maps which would have too many distinct colors for Pseudocolor displays; it also allocates a private color map when needed. At the moment, sunclock can read .jpg, .xpm or .xpm.gz images, and also its own .vmf vector map format. Other image formats have to be converted to xpm or jpg before being loaded - e.g. with the netpbm or with the Imagemagick package. Sunclock versions 3.xx are released under the GPL. demailly@fourier.ujf-grenoble.fr ============================================================================== WARNING (obsolete?) ------- If you are upgrading from a version of sunclock prior to 3.20, notice that the internationalization files were probably installed elsewhere, either in the app-defaults directory or at the root of the share directory /usr/share/sunclock/ Starting with 3.20, this is no longer the case, the file Sunclock.** are by default installed in /usr/share/sunclock/i18n Thus you can probably remove the obsolete Sunclock.** files from their older place /usr/X11R6/lib/X11/app-defaults -- or something like this. ============================================================================== Original README --------------- X11 version by John Mackin, <john@cs.su.oz.AU>, based on a Suntools program by John Walker, <kelvin@acad.uu.NET>. This program is a clock that shows which portion of the Earth's surface is illuminated by the Sun. It is designed to be usually iconic, but can be opened for a larger display with the time updated every second and both the local timezone and UTC displayed. The Suntools version had a menu that allowed you to speed up time, show different dates, etc., but I have never implemented any of that in the X version; there is some support for it in the code, however. The program should have been written using Xt rather than raw Xlib, and I tried that at first. I couldn't get the icon window to work, though, so I abandoned that version. Hence, the program does _not_ accept most Xt-style command line options; valid options are given in the manual page. The program has been tested on a number of different clients (MIPS, Sun, VAX) and servers (MIPS colour console, Sun MIT mono, NCD-16/19), under X11R3 and R4. If you find bugs, please report them to me, john@cs.su.oz.AU. To build the program, decide whether you want to use imake or not. If you don't, link Makefile.dist to Makefile, and edit it, otherwise edit the Imakefile and use xmkmf. The program uses two fonts, one for the icon display and one for the large window display. The names of these fonts are compiled in. The font names comes from -DBIGFONT and -DSMALLFONT in the Makefile. If you are not using imake, you will need to supply a -DSYSV option if you are System V. You should supply -DNEW_CTIME if you are using the table-driven ctime and a "struct tm" contains a tm_zone field. If neither of the ways of getting the local timezone name works on your system, please let me know. The original Suntools program, in case you want it, was posted as Volume 1, Issue 79 of comp.sources.sun. This program is public domain and may be freely copied as long as the notices at the top of sunclock.c remain intact.
