Provided by: sunclock_3.57-2_amd64 bug

NAME

       sunclock  -  a  fancy  clock for the X Window system, providing local time (legal time and
       solar time), sunrise, sunset and various geographical  data  through  a  point  and  click
       interface.

SYNOPSIS

       sunclock [ options ]

       where the list of licit options is the following long list (starting from (**) the options
       are configurable at runtime):

       [-help]  [-listmenu]  [-version]  [-citycheck]  [-display  name]   [-sharedir   directory]
       [-citycategories  value]  [-clock]  [-map] [-dock] [-undock] [-menu] [-nomenu] [-selector]
       [-noselector] [-zoom] [-nozoom] [-option] [-nooption] [-urban] [-nourban]

       (**)  [-language name] [-rcfile file] [-command string] [-editorcommand string]  [-mapmode
       *   <L,C,S,D,E>]   [-dateformat  string1|string2|...]  [-image  file]  [-clockimage  file]
       [-mapimage file] [-zoomimage  file]  [-clockgeom  <geom>]  [-mapgeom  <geom>]  [-auxilgeom
       <geom>]  [-menugeom  <geom>]  [-selgeom  <geom>]  [-zoomgeom  <geom>] [-optiongeom <geom>]
       [-urbangeom  <geom>]   [-title   name]   [-clockclassname   name]   [-mapclassname   name]
       [-auxilclassname  name]  [-classname  name] [-setfont <field>|<fontsetting>{|<languages>}]
       [-verbose]  [-silent]  [-synchro]  [-nosynchro]  [-zoomsync]   [-nozoomsync]   [-placement
       (random,  fixed,  center,  NW,  NE,  SW,  SE)]  [-placementshift  x y] [-extrawidth value]
       [-decimal]    [-dms]    [-city    name]    [-position    latitude|longitude]     [-addcity
       size|name|lat|lon|tz]  [-removecity  name  (name|lat|lon)] [-rootdx value] [-rootdy value]
       [-fixedrootpos] [-randomrootpos] [-screensaver] [-noscreensaver]  [-rootperiod  value  (in
       seconds)]  [-animation]  [-noanimation]  [-animateperiod  value  (in  seconds)] [-progress
       number[s,m,h,d,M,Y]]   [-jump    number[s,m,h,d,M,Y]]    [-aspect    mode]    [-colorlevel
       level=0,1,2,3]  [-fillmode  number=0,1,2]  [-coastlines]  [-contour] [-landfill] [-shading
       mode=0,1,2,3,4,5]  [-diffusion   value]   [-refraction   value]   [-night]   [-terminator]
       [-twilight]  [-luminosity] [-lightgradient] [-nonight] [-darkness value<=1.0] [-colorscale
       number>=1] [-mag value] [-magx value] [-magy value] [-dx value ] [-dy  value]  [-spotsizes
       s1|s2|s3|...  (0<=si<=4, 1<=i<=citycategories)] [-sizelimits w1|w2|w3|... (wi = zoom width
       values, 1<=i<=citycategories)] [-citymode mode=0,1,2,3]  [-objectmode  mode=0,1,2]  [-sun]
       [-nosun]   [-moon]   [-nomoon]   [-tropics]   [-notropics]   [-meridianmode  mode=0,1,2,3]
       [-parallelmode   mode=0,1,2,3]   [-meridianspacing   value]    [-parallelspacing    value]
       [-dottedlines]   [-plainlines]   [-bottomline]   [-nobottomline]  [-reformat]  [-vmfcolors
       color1|color2|color3...] [-vmfrange a|b|c|d] [-vmfcoordformat format] [-vmfflags  integer]
       [-setcolor field|color]

DESCRIPTION

       sunclock  is an X11 application that displays a map of the Earth and shows the illuminated
       portion of the globe.  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, the mutual distances of arbitrary locations on Earth, the position at zenith of
       Sun  and  Moon.  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 enter additional city entries.

       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 (starting with version 3.51, formats .jpg, .gif, .png, .xpm or .xpm.gz,
       .vmf  can be read [.vmf is the specific vector map 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.

       Depending  on the mode chosen, the bottom line shows a short text displaying the requested
       information. The bottom line can be scrolled to the right or to the left by  pressing  the
       PageUp/PageDown and Home/End key arrows.

       A  further  functionality  is  the  "Progress" feature, which allows one to accelerate the
       evolution of time, so as to observe the evolution of day/night  periods  and  seasons.  By
       default,  the Sun and Moon are also shown on the map (rather, the positions of Earth where
       Sun and Moon are at zenith are shown).  Coordinates of meridians, parallels,  cities,  the
       names of cities can be displayed on the map.

       All functionalities can be accessed though GUI actions on the main window or the auxiliary
       windows. The main window is resizable by pulling the window edges - as the current  window
       manager permits it.  There are 5 auxiliary windows:

       -  Menu  Window.  This  is  the  main menu, which offers a wide list of actions.  The menu
       window is launched by typing 'H' or clicking on the  bottom  strip  with  the  left  mouse
       button  once.  Each  action can be obtained by using the indicated keyboard shortcut or by
       clicking with the mouse on the corresponding entry. Upper/lower case is irrelevant, except
       for  options  or  actions  which  have  more  than 2 switches. Lower case then rotates the
       switches in one direction, upper case in the other direction. For those switches, the left
       mouse  button will have the same effect as lower case, and the right mouse button the same
       effect as upper case.

       - File Selector window. It can be accessed by clicking on  the  upper  part  of  the  main
       window  with  the  middle  mouse  button. It allows one to select the Earth image file (in
       formats *.vmf *.xpm, *.xpm.gz, *.jpg, *.gif, *.png) to be loaded.

       - Zoom window. It can be accessed by clicking on the upper part of the  main  window  with
       the right mouse button. The zoom window allows one to select a specific area on the Earth,
       to translate or zoom it up to 100 times.  High  resolutions  (larger  than  10)  are  only
       recommended  with  the  "huge"  Earthmap  of 11 Mbytes, which offers clean images up to 20
       times magnification at least.

       - Urban selector window. Allows one to modify interactively the list of shown  cities  and
       locations.

       -  Option  window.  Allows  one  to reconfigure pretty much everything on the fly (colors,
       fonts, etc), exactly as with the command line options.

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. The system administrator  can
       possibly  customize  the  system-wide prepackaged config file Sunclockrc before installing
       the package, while users can tweak their individual configuration  file  ~/.sunclockrc  at
       any  time. The individual config file ~/.sunclockrc is read *after* the system wide config
       file Sunclockrc, and therefore its settings override those of the system wide config.  The
       command line options can be used to override ~/.sunclockrc itself.

       -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 information on the
              internal operations performed. This is disabled by default.

       -silent
              Make Sunclock silent about internal operations performed. This is the default.

       -citycheck
              At start-up, check that there are no repetitions in the list of cities (a  city  is
              considered to be repeated if it appears twice under the same name, with coordinates
              differing by at most 0.5 degree).  By default no check is performed on Sunclockrc -
              which is supposedly correctly set up...

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

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

       -title name
              Change  the specification of the string which should appear in the title bar of the
              main and auxiliary windows. Default is the application name, i.e., sunclock.

       -classname name
              Change the specification of class application  name.  Default  is  Sunclock.  Other
              specifications  can  be  passed  so  that  aware  window  managers might use it for
              configuration  purposes.  You  might  e.g.   pass  -classname  NoTitle-Sticky,  and
              configure  properly  your  WM so that it removes the title bar, and make the window
              sticky with respect to the Desktop Pager. With fvwm, you could use for instance

       Style "*NoTitle*"    NoTitle, WindowListHit, Sticky

       Style "*ShowTitle*"  Title, WindowListHit, Slippery

       Style "*Sticky*"     Sticky

       to specify such a behaviour.

       -setfont  <field>|<fontsetting>{|<languages>}
              Select the font for the given  text  field  (clockstrip,  menustrip,  city,  coord,
              menu).  Optionally, one can specify a list of languages for which this font setting
              should apply. If the <languages> option is not specified, the font setting  applies
              to all languages.

       -rcfile  filename
              Read a configuration file that is different from the user default ~/.sunclockrc (if
              this option is not set, the user config file  defaults  to  ~/.sunclockrc).  Notice
              that  the app-default config file Sunclockrc is read first, and the file set by the
              -rcfile option is read afterwards; therefore its settings override those set by the
              system wide config file. Reading further config files is possible at runtime, using
              the option window. Set -rcfile with a void string "" if you wish to bypass the user
              config file step.

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

       -image  *.jpg (or *.gif, *.png, *.vmf, *.xpm, *.xpm.gz)
              Start sunclock with an Earth map image loaded in the clock  and  map  windows.  The
              same map is then used for both windows, but the clock image is usually scaled down.

       -mapimage  *.jpg (or *.gif, *.png, *.vmf, *.xpm, *.xpm.gz)
              Start sunclock with an Earth map image loaded in the map window.

       -clockimage  *.jpg (or *.gif, *.png, *.vmf, *.xpm, *.xpm.gz)
              Start sunclock with an Earth map image loaded in the clock window.

       -zoomimage  *.jpg (or *.gif, *.png, *.vmf, *.xpm, *.xpm.gz)
              Use specified file as image in the zoom widget

       -colorlevel  level=0,1,2,3
              Sets  the  color  level (0=monochrome, 1=few colors, 2=many colors, 3=full colors).
              With the "monochrome" setting, day and  night  appear  respectively  as  mapbgcolor
              (white  by default) and mapfgcolor (black by default), and no shading is available;
              all other features (city names, coordinates) appear also as monochrome.   With  the
              "few  colors"  setting,  the menus and city spots can be represented with dedicated
              colors, but the meridians/parallels/tropics are still monochrome.  With  the  "many
              colors"  oprions, meridians/parallels/tropics can also be drawn in color.  In these
              first 3 modes, only .vmf vector maps can be loaded.  These modes save a lot of  CPU
              power  -  since  a simple algorithm of inversion of colors is used to set colors of
              all points in the map.  Monochrome mode can be useful for very slow CPUs,  such  as
              those  in  use  in  PDAs with black and white screen. The full color mode (level=3)
              allows one to load jpeg or other colorful images; day and night can be  drawn  with
              various  shading parameters. This is the default and recommended mode if you have a
              reasonably recent machine with enough video RAM.

       -dock  This option is meant to give sunclock the  ability  to  be  docked  in  the  window
              manager  buttons or menu bar, providing that the WM offers this possibility without
              requiring special hints (fvwm2 or windowmaker or afterstep will work perfectly well
              for that purpose, KDE or Gnome won't...) Under the -dock option, sunclock locks the
              size of the first launched window, which is necessarily a small clock.  Also,  that
              initial  window can no longer be closed by typing 'K' or 'Q'. (The only way to exit
              the application, then, is to kill it with xkill, or to undock  it  first  with  the
              -undock  option from the Option window).  The user might want to customize the size
              and suitable options so that sunclock fits with the size of the  dockable  applets.
              As an example, sunclock could be invoked as follows:

              sunclock  -language  fr  -nobottomline  -dock  -clockgeom  63x42+2+190  -dateformat
              "%H:%M:%S|%a%_%d%_%b|%b%_%Y|%j%_%U/52" -command "xdiary"

       -undock
              Undocks sunclock. This option has no  other  effect  than  reallowing  the  use  of
              options that were "frozen" under -dock. It can be used e.g. to exit the application
              when sunclock has been started in dock mode.

       -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.

       -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.
       There are a few other switches, such  as  %h  for  hour  in  12-hour  mode,  %P  fo  AM/PM
       indicator, %G for hour in GMT time, %N for minutes in GMT time.

       -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 main (map, clock) window.

       -nomenu
              Don't  raise  the menu window along with the main (map, clock) window.  This is the
              default.

       -selector
              Raise the selector window along with the main (map, clock) window.

       -noselector
              Don't raise the selector window along with the main (map, clock) window.   This  is
              the default.

       -zoom  Raise the zoom window along with the main (map, clock) window.

       -nozoom
              Don't  raise  the zoom window along with the main (map, clock) window.  This is the
              default.

       -option
              Raise the option window along with the main (map, clock) window.

       -nooption
              Don't raise the option window along with the main (map, clock) window.  This is the
              default.

       -urban Raise the urban window along with the main (map, clock) window.

       -nourban
              Don't  raise the urban window along with the main (map, clock) window.  This is the
              default.

       -aspect  mode
              Sets the aspect mode, i.e. the  way  by  which  zooming  behaves  with  respect  to
              horizontal  and  vertical  directions.  Mode = 0 means that no synchronizations are
              made, mode = 1 means that the zoom factors are always made to be equal,  mode  =  2
              (the  more  subtle  one)  means  that  the horizontal and vertical zoom factors are
              adjusted so that the region located near the central point of the zoomed area  will
              be  conformal to its actual geometry on Earth, i.e. will not appear to be distorted
              horizontally or vertically.  This won't be true elsewhere,  though,  especially  if
              the zoomed area is large.

       -zoomsync
              When  the  option  is  set,  the zoom window will open in synchronization mode: any
              zooming action made from the main map or from the zoom window will  take  place  as
              the  mouse  button  is released (or as a key is pressed).  This is the default when
              the zoom window has not been opened (synchronization is automatically set).

       -nozoomsync
              When set, the zoom window will open in non-synchro  mode.  Synchronizing  the  zoom
              will  still  be  possible, though, by clicking on the "Synchro" button. By default,
              synchronization does not occur when  the  zoom  window  is  opened,  unless  option
              -zoomsync has been set.

       -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.

       -placement <choice> (random,fixed,center,NW,NE,SW,SE)
              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.

       -placementshift x y
              Relative displacement <clock window> --> <map window>, to apply with respect to the
              -placement  specification.  If placement is NW, then the NW window corner will move
              by (x,y) pixels. Defaut is (0,0), i.e.  no modification to apply to the  -placement
              specification.

       -extrawidth value
              When using the 'enlarge window' command specified by key '>', the width of the full
              X display is used, minus some default width equal to 10 pixels.  This is enough the
              accommodate the width of window borders of most window managers. In case it is not,
              -extrawidth <value> can be used to change this setting.

       -clockgeom (width)x(height)+(xcoord)+(ycoord)
              Specify the geometry of the clock window, i.e.  its  size  and  position  (absolute
              position with respect to the left upper corner of the screen).

       -mapgeom (width)x(height)+(xcoord)+(ycoord)
              Specify  the  geometry  of  the  map  window,  i.e. its size and position (absolute
              position with respect to the left upper corner of the screen).

       -menugeom +(xcoord)+(ycoord)
              Specify the relative position (x = horizontal shift, y =  vertical  shift)  of  the
              menu  window  with respect to the main window, starting from the bottom edge of the
              main window (from its top edge in case of SW or SE placements, see  above).  The  y
              value may need an adjustment, according to the height of the title bar allocated by
              the window manager, if any.  In the case of  the  menu  window,  width  and  height
              solely  depend  on the menufont, and therefore any given specification of width and
              height is ignored. The default relative position is x = 0, y = 30.

       -selgeom (width)x(height)+(xcoord)+(ycoord)
              Specify the geometry of the selector window. The position specification is relative
              to  the  main  window  (or to the menu, when the menu is raised).  See above option
              -menugeom for further explanations. The default geometry of the selector window  is
              600x180+0+30.

       -zoomgeom (width)x(height)+(xcoord)+(ycoord)
              Specify  the geometry of the zoom window. The position specification is relative to
              the main window (or to the menu, when  the  menu  is  raised).   See  above  option
              -menugeom  for  further  explanations.  The  default geometry of the zoom window is
              500x320+0+30.

       -optiongeom (width)x(height)+(xcoord)+(ycoord)
              Specify the geometry of the option window. The position specification  is  relative
              to  the  main  window  (or to the menu, when the menu is raised).  See above option
              -menugeom for further explanations. The height specification depends solely on  the
              selected  menufont  and  is  therefore  ignored. The default geometry of the option
              window is 630x80+0+30.

       -urbangeom +(xcoord)+(ycoord)
              Specify the relative position (x = horizontal shift, y =  vertical  shift)  of  the
              urban  window  with  respect  to  the main window (or to the menu, when the menu is
              raised). See above option -menugeom for further explanations.

       -auxilgeom +(xcoord)+(ycoord)
              Specify the relative position (x = horizontal shift, y =  vertical  shift)  of  the
              auxiliary  windows  (menu,  zoom, selector, option). All relative displacements are
              set to (x,y).

       -mag value
              Rescale the image by a magnification factor equal to  <value>,  which  must  be  at
              least  equal to 1.0. This means that the window only shows a fraction of the entire
              map namely, 1/<value> x 1/<value>. Default value is 1.0.

       -magx value
              Same as for the -mag option, but only the x direction (width) is rescaled.  Default
              value for magx is 1.0.

       -magy value
              Same  as  for  the  -mag  option,  but  only  the y direction (height) is rescaled.
              Default value for magy is 1.0.

       -dx value (degrees)
              Options -dx and -dy allow to set the longitude, respectively the latitude,  of  the
              city  or  location at which the zoom area should be centered.  The values should be
              given in degrees. Default (dx,dy) is (0.0,0.0).

       -dy value (degrees)
              See -dx above.

       -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.

       -dottedlines
              Use dotted lines to represent meridians and parallels.

       -plainlines
              Use plain lines to represent meridians and parallels.

       -bottomline
              Draw  a  line  at  the  bottom  of the map, to separate the map from the text strip
              showing time and coordinates.

       -nobottomline
              Don't draw the bottom line. This is the default.

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

       -editorcommand string
              Specify  an  external  file  editor  program  that  will be called through keyboard
              shortcut double 'h' (call help). Default  is  "/usr/lib/sunclock/emx  -edit  0  -fn
              9x15" (included emx editor, in no-edit mode...)

       -jump number[unit] (where unit=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] (where unit=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).

       -rootdx value (between 0.0 and 1.0)
              Options -rootdx and -rootdy allow to set the position where  the  sunclock  map  is
              copied  on  the root window in rootwindow or screensaver modes. '-rootdx 0.0' means
              on the left side, '-rootdx 1.0' on the right side, '-rootdy 0.0' means at the  top,
              '-rootdy  1.0'  at  the  bottom of the root window. Default is 0.5 for both values,
              i.e. a centered map.

       -rootdy value (degrees)
              See -rootdx above.

       -fixedrootpos
              Use the above rootdx and rootdy values to fix the position of the map on  the  root
              window. This is the default unless -screensaver has been specified.

       -randomrootpos
              Instead  of using the above rootdx and rootdy values to fix the position of the map
              on the root window, just use a random position instead.  This  is  the  default  in
              case the -screensaver option has been set.

       -screensaver
              Start sunclock in screensaver mode (no window nor any GUI controls are available in
              that case, and the only way to terminate the program is to kill it explicitly).

       -noscreensaver
              Do not start sunclock in screensaver mode. This is the default.

       -rootperiod value (in seconds, between 1 and 120 sec)
              Set the period for refreshing the root window. Default is 30 seconds.   This  takes
              effect  only  when  writing the map onto the root window is active (strike twice on
              '[' or hit the relevant box in the Option window).  Writing onto the root window is
              disabled by using the ']' key.

       -animation
              Start the animation mode right away when sunclock is launched.

       -noanimation
              Don't  start  the  animation  mode when sunclock is launched - this is the default.
              Sunclock can anyway switch between the animation/noanimation modes by typing key  '
              (apostrophe) at runtime.

       -animateperiod value (in seconds, between 0 and 5 sec)
              Set the period for animating the map. Default is 0 seconds, which means that images
              are switched as fast as sunclock can compute them. Otherwise time is shifted by the
              current  progress value (as set by the -progess option) after waiting the number of
              seconds prescribed by the animateperiod value.  This takes  effect  only  when  the
              animation  is  active  (strike  on  the ' key or hit the relevant box in the Option
              window).

       -addcity size|name|latitude|longitude|timezone

       where name is the ascii name of the place to be shown on  the  map.   The  first  argument
       "size" is an nonnegative integer meant to indicate the size of the city (1: major city, 2:
       important city, 3: less important city, ...). The argument "size" can also be  set  to  0,
       with the effect of hiding the corresponding city, while keeping in memory all of its other
       parameters. The city can then be shown again with  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
       (or whatever directory is used on your system), 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.

       -city name (name|lat|lon)
              Initialize program so as to display data of city 'name', respectively  (name,  with
              latitude  and  longitude  specified).  This  becomes  effective  only  if the above
              mentioned city is listed in the systemwide RC file  Sunclockrc  or  in  the  user's
              private ~/.sunclockrc. The operating mode is set to Coordinates mode.

       -position latitude|longitude
              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.   Notice
              that with a vertical bar | (a blank space is also admitted instead of a |).

       -addcity size|name|lat|lon|tz
              Adds  a city in the list of cities to be displayed on the map. They must be defined
              by exactly 5 parameters: size, name, latitude, longitude, timezone, in this  order,
              with parameters being separated by a vertical bar |. Blank characters may appear in
              the name if double quotes are used to mark  the  group  of  parameters  (but  there
              shouldn't  be any blank characters in the other parameters). In the RC config file,
              blank characters should be replaced by the octal character 037 (i.e. Ctrl-Q  Ctrl-_
              within emacs).

       -removecity name (name|lat|lon)
              Removes  name  (respectively name|lat|lon) from the list of cities to be displayed.
              Same remarks as above for blank characters.

       -citycategories value
              Specifies the maximal number of city categories: categories range from  1  (highest
              catgory,  i.e.  major  city)  to  some  maximum  number. The option -citycategories
              specifies that maximum number. It can only be used at start-up, not at runtime. The
              default value is 5.

       -spotsizes s1|s2|s3|... (0<=si<=5, 1<=i<=citycategories)
              With  this  setting, major cities (category 1) will be represented by the symbol of
              size s1, category 2 cities by the symbol off size s2, etc.  The default setting  is
              -spotsize  1|2|3|4|5.  Assigning size si=0 means that the corresponding category of
              cities (rank i) will not be displayed.  If there are less data than the  number  of
              city  categories  (5  by default), the last given data is repeated as many times as
              needed, e.g.   -spotsizes  2  is  equivalent  to  -spotsizes  2|2|2|2|2.   Example:
              specifying  -spotsizes  0|2|0|3|0 will let appear only city categories 2 and 4, but
              those of category 4 will appear with the symbol normally  allocated  to  cities  of
              category 3. This is useful in combination with the option -sizelimits (see below).

       -sizelimits w1|w2|w3|...
              (wi  =  zoom  width values, 1<=i<=citycategories) With this setting, cities of rank
              i=1,2,3,... will appear if (and only if) the width of the zoomed map  is  at  least
              equal  to wi (as it would appear if the Earth would be entirely displayed...) . The
              default is 0|580|2500|6000|12000 (no constraint for major  cities,  rank  4  cities
              appear  only  if  the  width is at least 6000 pixels, e.g. if an original window of
              width 800, say, has been applied a zoom at least equal to 7.5).  Thus -sizelimits 0
              is  equivalent  to  -sizelimits  0|0|0|0|0,  -sizelimits  0|400  is  equivalent  to
              -sizelimits 0|400|400|400|400.

       -shading mode=0,1,2,3,4,5
              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 3˚ below horizon. Mode 4 additionally represents  the
              luminosity  values  in  all  parts  of  the illuminated area. Mode 5 represents the
              gradient of luminosity from the brightest area (facing the sun) to the darkest area
              (opposite  to  the sun); this has nothing to do, though, with the actual luminosity
              values.

       -nonight
              Start sunclock with the night region not drawn. This is equivalent to -shading 0.

       -night Start sunclock with the night region in plain shading mode. This is  equivalent  to
              -shading 1.

       -terminator
              Equivalent to -shading 2

       -twilight
              Equivalent to -shading 3

       -luminosity
              Equivalent to -shading 4

       -lightgradient
              Equivalent to -shading 5

       -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.

       -darkness value (in the range 0.0 ... 1.0)
              Sets  the  constrast  between day and night areas. A 0.0 value means that the night
              area will not be distinguishable  from  day,  while  1.0  means  that  it  will  be
              completely black. Default is 0.5.

       -colorscale value (integer in the range 1 ... 256)
              Sets  the  number  of color subdvisions which will be in use for producing shading,
              that is, the number of colors ranging from  bright  colors  (day)  to  dark  colors
              (night). Default is 16.

       -meridianmode mode=0,1,2,3
              Start  sunclock with meridians displayed or not, according to the mode, mode=0 : no
              meridians, mode=1 : meridians drawn, mode=2 : meridians drawn with  labels  at  the
              bottom, mode=3 : meridians drawn with labels at the top.  The default mode is 0 (no
              meridians).

       -parallelmode mode=0,1,2,3
              Start sunclock with parallels displayed or not, according to the mode, mode=0 :  no
              parallels,  mode=1  :  parallels drawn, mode=2 : parallels drawn with labels at the
              left hand side, mode=3 : parallels drawn with labels at the right  hand  side.  The
              default mode is 0 (no parallels).

       -meridianspacing value (degree)
              Specify  how  many degrees (or fractions of degree) should separate meridians drawn
              on the map.

       -parallelspacing value (degree)
              Specify how many degrees (or fractions of degree) should separate  parallels  drawn
              on the map.

       -citymode mode=0,1,2,3
              Start  sunclock  with  cities  displayed or not, according to the mode, mode=0 : no
              cities, mode=1 : cities drawn, mode=2 : cities drawn with  their  names,  mode=3  :
              cities  drawn  with their coordinates.  The default mode is 1 (cities shown without
              names or coordinates).

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

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

       -moon  Start sunclock with the Moon position displayed (by default, it is).

       -notropics -nosun -nomoon
              These options just negate the above ones.

       -objectmode mode=0,1,2
              Mode=0 stands for no objects (Sun, Moon) at all, mode=1 for objects just  drawn  by
              their symbol, mode=2 for objects drawn with their symbol and coordinates in decimal
              degrees (or degrees, minutes, seconds, using the ˚ key switch).

       -reformat
              This option only produces an effect when a *.vmf file is loaded. The file  is  then
              reformatted  according to the allowed syntax and normal line length, and printed to
              stdout. To capture the aoutput, one should redirect the standard output to  a  file
              (with a '> file' as usual).

       -vmfcolors color1|color2|color3...
              Redefine  the list of colors to be used in the .vmf file. This option has no effect
              when loading files with other formats. Default is NULL string (so that the  default
              colors  are  loaded). The string "|" is also considered to be a void string and can
              be used in the option widget to enforce default colors back.

       -vmfrange a|b|c|d
              Define the range in which point coordinates (latitude, longitude)  should  vary  in
              the  *.vmf  files,  default  is  -90|90|-180|180.  This  option  can  be  useful in
              combination with -reformat to make a linear change of coordinates in a *.vmf file.

       -vmcoordformat format
              Set the format for the output of double values produced via the  -reformat  option.
              The   default   format  is  "%7.3f  %8.3f"  (format  for  latitude  and  longitude,
              respectively), unless the -vmfrange has been modified, in which  case  the  default
              becomes  "%g %g" (from the POSIX rules, this stands for 6 significant digits in any
              position).

       -vmfflags number
              Sets the flags (integer value) for a *.vmf file. Each bit is a distinct  flag.  The
              zeroth  order bit (i.e. &1) determines whether features which have their own zeroth
              bit set are to be drawn in clock window mode (if the zeroth bit  is  not  set,  the
              feature  will  always  be  drawn).  Other  bits  are  used to control whether given
              features  are  to  be  drawn  or  not.  For  instance  setting  -vmfflags  2   with
              timezones.vmf  will  let  the  timezone regions appear, while -vmfflags 6 will also
              show the timezone boundary lines.  (Only  bits  0,  1,  2  are  currently  used  in
              timezones.vmf).

       -setcolor field|color
              Sets  the  color  of  a  specified field in the sunclock widgets.  The color can be
              specified as any litteral value (red, yellow, etc..., as defined  in  the  resource
              file rgb.txt), or as a 6 digit hexadecimal value #ijklmn, or even 12 digits (for 48
              bits  displays!)  The  field  can  take  any  of  the  following  values   (between
              parentheses, the meaning and default value):

       clockbg (clock background color; White)

       clockfg (clock foreground color; Black)

       mapbg (map background color; White)

       mapfg (map foreground color; Black)

       menubg (menu text background color; Grey92)

       menufg (menu text foreground color; Black)

       buttonbg (button background color; Grey84)

       buttonfg1 (button very dark border color ; Black)

       buttonfg2 (button dark border color ; Grey50)

       buttonfg3 (button light border color ; Grey95)

       buttonfg4 (button very light border color ; White)

       weak (color for disabled menu commands; Red)

       clockstripbg (background color of bottom strip in clock window; Grey92)

       clockstripfg (foreground color of bottom strip in clock window; Black)

       mapstripbg (background color of bottom strip in map window; Grey92)

       mapstripfg (foreground color of bottom strip in map window; Black)

       zoombg (background color of the small monochrome map used in the zoom widget; White)

       zoomfg (foreground color of the small monochrome map used in the zoom widget; Black)

       optionbg (background color of option text entry; White)

       optionfg (foreground color of option text entry; Black)

       caret (color of text caret; SkyBlue2)

       change (color for temporary changes; Brown)

       choice (color for selected changes and choices; SkyBlue2)

       directory (color of text indicating directory entries; Blue)

       image (color of text indicating image files; Magenta)

       cityname (color of text indicating city names; Red)

       city0 (color of unmarked cities; Orange)

       city1 (color of marked cities, main selection; Red)

       city2 (color of marked cities, secondary selection; Red3)

       mark1 (color of first mark; Pink1)

       mark2 (color of secondary mark; Pink2)

       line (color of geodesic lines; White).

       meridian (color of meridians; White).

       parallel (color of parallels; White).

       tropic (color of Equator/Tropics/Arctic circles; White)

       sun (color of Sun; Yellow)

       moon (color of Moon; Khaki)

       star (color of Stars; White)

       root (color of Root window on which stars will be drawn; Black)

PRIVATE CONFIGURATION FILE

       Users  may keep a file in their home directory called ~/.sunclockrc. This file can contain
       specify any number of options which are also available as command line options:

       mapmode: L

       language: en

       city: Washington

       map

       mapimage: /usr/share/sunclock/earthmaps/jpeg/caida.jpg

       tropics

       twilight

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  projects  the  illuminated  area  onto the map image by an equidistributed (latitude,
       longitude) cylindrical projection.  The Sun's position is calculated to  better  than  one
       arc-second in accuracy.

BUGS

       Sunclock  makes  intensive  use  of pointers and memory allocation/deallocation, so memory
       leaks might still be possible under some circumstances.  However,  the  program  has  been
       thoroughly  debugged,  and crashes seem to be rather rare. As new features are introduced,
       older ones may become broken during the phase of development :-(

       The illuminated area shown is the area which would be sunlit if the Earth atmosphere would
       be  absolutely  uniform.   The actual illuminated area may depend on weather, temperature,
       atmospheric refraction and diffusion, etc.

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.

       Jean-Pierre  Demailly,  Université  de Grenoble I, demailly@fourier.ujf-grenoble.fr worked
       out versions 3.xx, which  add  many  new  major  features  (loading  maps,  shading,  zoom
       functionalities, configuration of options on the fly at runtime, through a point and click
       GUI interface).

                                          June 22, 2006                               SUNCLOCK(1)