1README for Sunclock version 3.xx
2--------------------------------
3
4Sunclock is a sophisticated clock for the X Window system. It is
5based on an earlier version by John Mackin, itself derived from the
6Suntools program by John Walker. Many possibilities of the original
7astronomy routines are now exploited.
8
9Sunclock displays a map of the Earth and shows which portion is illuminated
10by the sun. It can commute between two states, the "clock window" and
11the "map window". The clock window displays a small map of the Earth
12and therefore occupies little space on the screen, while the "map window"
13displays a large map and offers more advanced functions: local time
14of cities, Sun and Moon position, etc.
15
16A customizable list of cities is loaded by sunclock at start-up (and can
17be modified interactively, as well). Using the information provided for
18these cities, the map window can operate in five different modes:
19
20- "Legal time" mode: legal time of default time zone and GMT time are
21 displayed.
22- "Coordinate" mode: by clicking on a city, users get coordinates
23 (latitude, longitude) of that city, legal time and sunrise/sunset.
24- "Solar" mode: by clicking on a point of the map (either a city or
25 another point), solar time and day length are shown.
26- "Hour Extension" mode: displays solar times from 00:00 to 23:00 in bottom
27 strip, according to the Sun position.
28- "Distance" mode: shows distances in km and miles between two arbitrary
29 locations.
30
31A further functionality is the "Progress" feature, which allows to accelerate
32the evolution of time, so as to observe the evolution of day/night periods
33and seasons.
34
35The sunclock package includes a vector map of the Earth (loosely
36derived from the xearth package by Kirk Lauritz Johnson), which is
37capable of building Earth maps of arbitrary sizes without losing the
38accuracy of details (within certain limits...)
39
40Meridians, Parallels, Equator, Tropics and Arctic circles can also be
41drawn. All these actions are performed through mouse clicks
42on the map or on the bottom strip, and/or with keyboard shortcuts.
43There is inline help available by typing 'h' or by clicking on the
44bottom strip -- so that no further explanation should be needed.
45Commuting between the clock and map states is obtained by typing '!'
46or simply <Space>.
47
48By default, the Sun and Moon are also shown on the map (rather, the
49positions of Earth where Sun and Moon are at zenith are shown).
50Coordinates of meridians, parallels, cities, the names of cities can
51be displayed on the map.
52
53If you are using a monochrome display, there is an option
54 -colorlevel <value>
55that will enable sunclock to run in monochrome mode (in that case,
56use -colorlevel 0).
57
58Under pseudocolor displays (depth <= 8), sunclock allocates private
59colormaps as soon as they are needed; there is also a builtin machanism
60which automatically quantizes true-color Earth maps which would have too
61many distinct colors for Pseudocolor displays. At the moment, sunclock
62can read .jpg, .xpm or .xpm.gz images, and also its own .vmf vector map
63format. Other image formats have to be converted to xpm or jpg before
64being loaded - e.g. with the netpbm or with the Imagemagick package.
65
66Sunclock is internationalized and currently supports the following
67localizations:
68 de (German), en (English), es (Spanish), fr (French), it (Italian),
69 nl (Dutch), no (Norwegian), pl (Polish), se (Swedish), also
70not all translations are up-to-date. Using iso8859-2 encoded fonts
71is required for Polish (other currently supported languages work with
72iso8859-1 or iso8859-15). Thus, for Polish, a special setting of the
73fonts in Sunclockrc is needed (edit the file by uncommenting the
74appropriate font settings).
75
76Sunclock versions 3.xx are released under the GPL.
77
78
79demailly@fourier.ujf-grenoble.fr
80
81==============================================================================
82
83Starting from version 3.30 on, the recommended image format is JPEG,
84(although you can still use the .xpm or .xpm.gz format as before).
85We suggest you to download (actually very nice!) Earth maps from the
86xglobe/xplanet home sites
87 http://www.radcyberzine.com/xglobe/
88 http://www.vterrain.org/Imagery/whole_earth.html
89 http://apollo.spaceports.com/~jhasting/planets.html
90A bundled package of Earth maps is also provided on
91 ftp://ftp.ac-grenoble.fr/ge/geosciences/sunclock_jpg_maps.tgz
92
93More information on geographic names, city coordinates, timezones can be
94obtained from
95 http://gnpswww.nima.mil/geonames/GNS/
96
97==============================================================================
98
99Please check the WARNING file for more comments, especially on recent
100changes which affect sunclock's behaviour. Take also a look to CHANGES
101if you want to review all changes which occurred during the development.
102
103==============================================================================
104
105Original README
106---------------
107
108X11 version by John Mackin, <john@cs.su.oz.AU>, based on a Suntools program
109by John Walker, <kelvin@acad.uu.NET>.
110
111This program is a clock that shows which portion of the Earth's surface is
112illuminated by the Sun. It is designed to be usually iconic, but can be
113opened for a larger display with the time updated every second and both the
114local timezone and UTC displayed. The Suntools version had a menu that
115allowed you to speed up time, show different dates, etc., but I have
116never implemented any of that in the X version; there is some support
117for it in the code, however.
118
119The program should have been written using Xt rather than raw Xlib, and I
120tried that at first. I couldn't get the icon window to work, though, so I
121abandoned that version. Hence, the program does _not_ accept most Xt-style
122command line options; valid options are given in the manual page.
123
124The program has been tested on a number of different clients (MIPS, Sun,
125VAX) and servers (MIPS colour console, Sun MIT mono, NCD-16/19), under X11R3
126and R4. If you find bugs, please report them to me, john@cs.su.oz.AU.
127
128To build the program, decide whether you want to use imake or not. If you
129don't, link Makefile.dist to Makefile, and edit it, otherwise edit the
130Imakefile and use xmkmf. The program uses two fonts, one for the icon
131display and one for the large window display. The names of these fonts
132are compiled in. The font names comes from -DBIGFONT and -DSMALLFONT
133in the Makefile. If you are not using imake, you will need to supply
134a -DSYSV option if you are System V. You should supply -DNEW_CTIME if
135you are using the table-driven ctime and a "struct tm" contains
136a tm_zone field. If neither of the ways of getting the local timezone
137name works on your system, please let me know.
138
139The original Suntools program, in case you want it, was posted as Volume 1,
140Issue 79 of comp.sources.sun.
141
142This program is public domain and may be freely copied as long as the
143notices at the top of sunclock.c remain intact.
144