### sunclock-3.31 README file

    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.