     SUNCLOCK(1)                                                     SUNCLOCK(1)
                                    Feb 26, 2001

     NAME
          sunclock - a fancy clock for the X Window system, providing time and
          geographical data through point and click actions.

     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.  In addition to providing
          local time for the default timezone, it also displays GMT time, legal
          and solar time of major cities, their latitude and longitude, and the
          mutual distances of arbitrary locations on Earth. Sunclock can display
          meridians, parallels, tropics and arctic circles. It has builtin
          functions that accelerate the speed of time and show the evolution of
          seasons. Sunclock can be internationalized for various western
          languages.  It is possible to customize the app-default file and add
          new entries for additional cities.

          Sunclock 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 Sunclock
          package includes a resizable and zoomable vector map . External Earth
          maps can also be loaded (as to version 3.30, formats .jpg, format of
          sunclock]). Some additional formats could be added in the future.

          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 speed up the evolution of time, so as to
          observe the evolution of day/night periods and seasons.

          Depending on the mode chosen, the bottom line shows a short text
          displaying the required information. The bottom line can be scrolled
          to the right or to the left by pressing the horizontal key arrows.

                                        - 1 -          Formatted:  March 9, 2001

     SUNCLOCK(1)                                                     SUNCLOCK(1)
                                    Feb 26, 2001

     OPTIONS
          The program does not use the Xt nor any other more advanced toolkit,
          and hence only those options explicitly enumerated below may be used.
          The only needed resource is the list of coordinates and timezones of
          cities to be displayed. Users can possibly customize the system-wide
          prepackaged configuration file Sunclockrc, or their individual
          configuration file ~/.sunclockrc.

          -help
               Show brief help and exit.

          -listmenu
               Explanations on the actions available from the builtin menu.

          -version
               Show program version and exit.

          -verbose
               Make Sunclock verbose. The program then sends to stderr some
               internal information on the operations performed. This is
               disabled by default.

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

          -language  name
               Select language to be used in the sunclock menu and help.

          -bigfont  name
               Select the big font (used in the bottom line of the map window,
               in the menu and file selection windows). Default is 6x13

          -smallfont  name (used in the bottom
               Default is 6x10.

          -rcfile  filename
               Select a configuration file that is possibly different than the
               system wide app-default Sunclock or the user default
               ~/.sunclockrc. The rcfile (or user default) has a higher priority
               than the system wide app-default, but it can be overriden by the
               command line options which still have a higher priority.

          -sharedir  directory
               Set the directory where system wide shared Earthmaps are located.
               Default is /usr/share/sunclock/earthmaps.

          -mapimage  file.xpm.(gz)
               Start sunclock with an Earth map image loaded in the map window.

          -clockimage  file.xpm.(gz)
               Start sunclock with an Earth map image loaded in the clock

                                        - 2 -          Formatted:  March 9, 2001

     SUNCLOCK(1)                                                     SUNCLOCK(1)
                                    Feb 26, 2001

               window. Those maps are supposed to be somewhat smaller than for
               the map window, but sunclock will still accept large ones in the
               clock window...

          -mono
               Use monochrome settings (recommended only for monochrome
               screens!).  Day and night appear respectively as white and black,
               and no shading is available. Only .vmf vector maps can be used in
               that case.

          -invert
               This is essentially the same as the -mono option, except that
               menus and cities can be in colors. This mode only involves 12
               colors in total, and can be used for Pseudocolor displays which
               have only a small number of available colors. Also, the -mono and
               -invert options considerably reduce both memory and CPU usage,
               and can be useful on slower machines.

          -private
               Force the allocation of a private colormap. This option has no
               effect on truecolor displays, and is also disabled in case -mono
               is set.  On pseudocolor displays (depth <= 8), the -private
               option allows sunclock to run even when the environment makes
               intensive use of colors. An automatic quantization of colors is
               performed so that true-color Earth maps using hundreds of colors
               can still be displayed (of course, one may observe in some cases
               a loss of quality).

          -dock
               With this option, sunclock locks the size of the first launched
               window, if this is a (small) clock. Also, this window cannot be
               closed unless all other windows are closed as well.

          -synchro
               With this option, sunclock updates all windows simultaneously.
               This, of course, requires more CPU time and may slow down
               sunclock's operation if too many windows have been opened. The
               default is to update only the active window.

          -nosynchro
               With this option, sunclock only updates the active window. This
               is the default.

          -title
               With this option, sunclock provides hints to the window manager
               so that the title bars can appear.

          -notitle
               With this option, sunclock does not provide hints to the window
               manager so that the title bars might not appear. Many window
               managers do it anyway (supplying the missing hints when

                                        - 3 -          Formatted:  March 9, 2001

     SUNCLOCK(1)                                                     SUNCLOCK(1)
                                    Feb 26, 2001

               necessary), so this option may not be effective for some window
               managers.

          -clock
               Start in the clock state. This is the default and thus need not
               be specified.

          -dateformat string1|string2|...
               Set the format(s) used in the text output in the bottom strip of
               the clock. The default date format consists of 3 strings:

            %H:%M%_%a%_%d%_%b%_%y|%H:%M:%S%_%Z|%a%_%j/%t%_%U/52

          Here %H,%M,%S stand for hour, minutes, seconds, %a for dayname, %b for
          monthname, %d for monthday number, %j for yearday number, %m for month
          number, %y for year last two digits, %Y for year number, %t for number
          of days in year (365 or 366), %Z for timezone, %U for week number
          (week #1 is the week with the first thursday of the year); all other
          characters are reproduced as such, except %_ which stands for a blank
          space, %% which stands for % and %| which stands for |. The vertical
          bar | is used as a delimiter to indicate successive time formats.
          There can be as many formats as desired, and the actual selection
          cycles through all these formats by clicking on the bottom strip with
          the mouse. The first string (i.e. the one preceding the first bar) is
          taken as the default format.

          -map Start in the map state.  Useful to start right away with advanced
               functionalities.

          -decimal
               Initializes coordinate values of geographical data in decimal
               degrees.  However, this can still be switched at runtime.

          -dms Initializes coordinate values of geographical data in degrees,
               minutes and seconds. However, this can still be switched at
               runtime.

          -menu
               Raise the menu window along with the map window. This has no
               effect unless the -map option is also set.

          -nomenu
               Don't raise the menu window along with the map window. This has
               no effect if the clock is raised first.

          -mapmode * (single character = C, D, E, L or S)
               Start the map functions in mode (C)oordinates, (D)istances, hour
               (E)xtension, (L)egal time or (S)olar time respectively. Any other
               specification is ignored. Default is legal time mode.

                                        - 4 -          Formatted:  March 9, 2001

     SUNCLOCK(1)                                                     SUNCLOCK(1)
                                    Feb 26, 2001

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

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

          -placement <choice> (random,fixed,center,NW,NE,
               Specify whether commuting between clock and map windows should
               proceed with letting the the window centers, respectively, the
               NW, NE, SW, SE corners fixed, or rather whether it should operate
               randomly, or through user defined placement. Default is NW
               placement.

          -horizshift w
               Specify number of pixels which should separate the central bottom
               points of map and menu windows. The default is 0 and may need to
               be adjusted according to the window manager used.

          -vertshift h
               Specify number of pixels which should separate the map and menu
               windows.  The default is 12 and may need to be adjusted according
               to the window manager used.

          -spotsize size
               Define size=0 [=no spots] or 1,2,3 to use either thin circles,
               medium size spots or big spots and circles to represent cities.
               Size=3 can be useful for monochrome displays on which cities are
               hardly visible, otherwise small color spots of size 1 or 2 are
               better).  Default is 2 for color mode and 3 for monochrome mode.

          -coastlines
               In the builtin vector map, generate coast lines without filling
               the land areas.

          -contour
               As before, but use a smart algorithm which eliminates lines,
               especially at lower resolutions (in case the coasts are very
               irregular, some parts may disappear but the overall picture looks
               sharper).

          -landfill
               In the builtin vector map, fill the land areas without generating
               coast lines.

          -fillmode 0,1,2
               Fillmode=0 is equivalent to -coastlines, fillmode=1 is equivalent
               to -contour, and fillmode=2 is equivalent to -landfill.

                                        - 5 -          Formatted:  March 9, 2001

     SUNCLOCK(1)                                                     SUNCLOCK(1)
                                    Feb 26, 2001

          -dottedlines
               Use dotted lines to represent meridians and parallels.

          -plainlines
               Use plain lines to represent meridians and parallels.

          -command string
               Specify an external action or program that will be called by
               keyboard shortcut 'x'. Default is empty command.

          -jump number[unit](whereunit=s,m,h,d,M,Y)
               Number of seconds (respectively minutes, hour, days, Months,
               Years) by which the current date and time should be shifted. No
               blank space should separate the number and its unit. If the unit
               is absent, the number is understood to be expressed by default in
               seconds. Useful to get sunclock display information on earlier or
               later epochs.

          -progress number[unit](whereunit=s,m,h,d,M,Y)
               Number of seconds (respectively minutes, hour, days, Months,
               Years) by which the time progression should operate. No blank
               space should separate the number and its unit. If the unit is
               absent, the number is understood to be expressed by default in
               seconds. Useful to get sunclock progress by other steps than the
               predefined ones (by default the steps cycle between the values 1
               mn, 1 hour, 1 day, 7 days, 30 days).

          -city name
               Initialize program so as to display data of city 'name'. This
               becomes effective only if the above mentioned city is listed in
               the app-default or rc file. The operating mode is set to
               Coordinates mode.

          -position latitudelongitude
               Initialize program so as to display data of the position
               specified by two coordinates (in degrees). The operating mode is
               set to Solar time mode.  -shading mode=0,1,2,3,4 Start sunclock
               with the specified shading mode. Mode 0 means that the night area
               is not displayed. In higher modes, the night area is displayed,
               with increasingly sophisticated shading algorithms. Mode 1 stands
               for no shading (i.e. just bright and dark colors are shown). Mode
               2 shades the terminator area -- the area in which the sun is
               partially hidden by the horizon. Mode 3 shades the region in
               which there is still substantial luminosity left after sunset
               (depending on the diffusion parameter below). Default is 6 below
               horizon. Mode 4 additionally represents the luminosity values in
               all parts of the illuminated area.

          -terminator
               Equivalent to -shading 2

                                        - 6 -          Formatted:  March 9, 2001

     SUNCLOCK(1)                                                     SUNCLOCK(1)
                                    Feb 26, 2001

          -twilight
               Equivalent to -shading 3

          -luminosity
               Equivalent to -shading 4

          -diffusion value(degrees)
               Sets the amplitude of the area in which diffusion of light in the
               atmosphere is still sufficient to keep some luminosity after
               sunset.  Default is 3 degrees.

          -refraction value(degrees)
               Sets the value of the refraction angle for tangential sun rays at
               sunset.  This is related to the fact that the sun sometimes looks
               bigger at sunset.  Changing the refraction degree slightly
               affects the computation of sunrise and sunset times. Default is
               0.1 degree.

          -night
               Start sunclock with the night region displayed (by default, it
               is).

          -cities
               Start sunclock with the cities displayed (by default, they are).

          -sun Start sunclock with the Sun position displayed (by default, it
               is).

          -meridians
               Start sunclock with meridians displayed (by default, they
               aren't).

          -parallels
               Start sunclock with parallels displayed (by default, they
               aren't).

          -tropics
               Start sunclock with tropics and arctic circles displayed (by
               default, they aren't).

          -nonight -nocities -nosun -nomeridians -noparallels -notropics
               These options just negate the above ones.

          -landcolor color
               Specifies the color of land areas produced by the builtin vector
               map. Default is Chartreuse2. This option has no effect on
               external image earthmaps being loaded.

          -watercolor color
               Specifies the color of water (sea) areas. Default is RoyalBlue.

                                        - 7 -          Formatted:  March 9, 2001

     SUNCLOCK(1)                                                     SUNCLOCK(1)
                                    Feb 26, 2001

          -arcticcolor color
               Specifies the color of arctic areas. Default is LemonChiffon.

          -textbgcolor color
               Specifies the bottom text background color. Default is Grey92.

          -textfgcolor color
               Specifies the bottom text foreground color. Default is Black.

          -dircolor color
               Specifies the color used for representing directories in the file
               selection widget. Default is Blue.

          -imagecolor color
               Specifies the color used in the file selection widget for
               representing the image files whose formats are recognized and can
               be read. Default is Magenta.

          -citycolor0 color
               Specifies the color of cities (as described in ~/.sunclockrc or
               in the systemwide app-default file), when they have not yet been
               clicked on with the mouse. Default is Orange.

          -citycolor1 color
               Specifies the color to be applied to the city which has been
               selected just before the last selection, during the process of
               calculating distances.  Default is Red.

          -citycolor2 color
               Specifies the color to be applied to the last selected city. The
               name and coordinates of this city are displayed in the bottom
               line. Default is Red3 (darker red).

          -markcolor1 color
               Specifies the color to be applied to the first marked position
               (any location on Earth other than one of the cities). Default is
               Pink1.

          -markcolor2 color
               Specifies the color to be applied to the second marked position.
               Default is Pink2.

          -linecolor color
               Specifies the color to be applied to meridian and parallel lines.
               Default is White.

          -tropiccolor color
               Specifies the color to be applied to Equator/Tropics/Arctic
               circles.  Default is White.  -suncolor color Specifies the color
               to be applied to Sun.  Default is Yellow.

                                        - 8 -          Formatted:  March 9, 2001

     SUNCLOCK(1)                                                     SUNCLOCK(1)
                                    Feb 26, 2001

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

          name: latitude longtitude timezone

          where name is the ascii name of the place to be shown on the map.
          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 /lib/zoneinfo, incorrect timezones cause the clock to
          display GMT. It is also possible to reference a file in a directory
          relative to /lib/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 city name and
          its corresponding local time and time zone will be displayed in the
          bottomline.

     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.

     AUTHORS
          John Walker, Autodesk, Inc., <kelvin@acad.uu.NET>, wrote the original
          Suntools program from which sunclock is derived.

          John Mackin, Basser Department of Computer Science, University of
          Sydney, Sydney, Australia, <john@cs.su.oz.AU>, wrote the X11 version
          out of Suntools.

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

                                        - 9 -          Formatted:  March 9, 2001

     SUNCLOCK(1)                                                     SUNCLOCK(1)
                                    Feb 26, 2001

          Jean-Pierre Demailly, Universit de Grenoble I, demailly@fourier.ujf-
          grenoble.fr added support for numerous new options and functions in
          the interface, and made them available through the GUI.

                                       - 10 -          Formatted:  March 9, 2001