SUNCLOCK(1)

👑 SUNCLOCK(1) 👑

General Commands Manual — yes bestie, the whole manual, and it's a long one so buckle up 🫶

---

🌸 NAME 🌸

sunclock — a fancy clock for the X Window system 💅 it gives you local time (both legal time and solar time), sunrise, sunset, and a whole pile of geographical data, all through a point-and-click interface. iykyk ✨

---

🌈 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] [-helpcommand
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]

so like, everything starting from the little (**) marker is stuff you can also change at runtime, no big deal 💅 the rest is startup-only energy.

---

💖 DESCRIPTION 💖

sunclock is an X11 application that puts a map of the Earth on your screen and shows you which part of the globe is lit up by the sun 🌞. and that's not even the half of it — it also gives you:

• local time for the default timezone
• GMT time
• legal time and solar time for major cities
• latitude and longitude of those cities
• the mutual distances between arbitrary locations on Earth
• the position at zenith of the Sun and the Moon

it can draw meridians, parallels, tropics and arctic circles too, no cap. plus it has builtin functions that speed up time itself so you can watch the seasons evolve 🦋. it can be internationalized for various western languages, and yeah, you can customize the app-default file and add your own extra city entries. go off ✨

sunclock commutes between two states — the "clock window" and the "map window". the clock window shows a lil baby map of the Earth so it barely takes up any screen real estate 🎀, while the "map window" shows a big map and unlocks the more advanced functions. the Sunclock package ships with a resizable and zoomable vector map. external Earth maps can be loaded too (starting with version 3.51, the formats .jpg, .gif, .png, .xpm or .xpm.gz, and .vmf can be read — .vmf is the specific vector map format of sunclock). some additional formats could get added in the future. maybe. we'll see 💀

the map window can work in five different modes:

• "Legal time" mode: legal time of the default time zone and GMT time are displayed.
• "Coordinate" mode: click on a city and you get that city's coordinates (latitude, longitude), legal time and sunrise/sunset. 📍
• "Solar" mode: click anywhere on the map (a city or literally any other point) and it shows solar time and day length.
• "Hour Extension" mode: displays solar times from 00:00 to 23:00 in the bottom strip, according to the Sun position.
• "Distance" mode: shows distances in km and miles between two arbitrary locations. 🧚

depending on which mode you picked, the bottom line shows a short text with the info you asked for. and you can scroll that bottom line right or left by pressing PageUp/PageDown and Home/End. slay.

another whole functionality is the "Progress" feature, which lets you accelerate the evolution of time so you can just sit there and watch day/night periods and seasons do their thing 🍓. by default the Sun and Moon are also shown on the map (or rather, the positions on Earth where Sun and Moon are at zenith are shown). coordinates of meridians, parallels and cities, plus the names of cities, can all be displayed on the map.

every functionality is reachable through GUI actions on the main window or the auxiliary windows. the main window is resizable by pulling its edges — as much as your current window manager permits, anyway 🙈. there are 5 auxiliary windows:

• Menu Window. this is the main menu, and it offers a wide list of actions. launch it by typing H or by clicking once on the bottom strip with the left mouse button. each action can be obtained either 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 — for those, lower case rotates the switches in one direction and upper case in the other direction. and for those same switches, the left mouse button does the same thing as lower case, and the right mouse button does the same thing as upper case. 💅
• File Selector window. click the upper part of the main window with the middle mouse button to get here. it lets you select the Earth image file to load (formats *.vmf, *.xpm, *.xpm.gz, *.jpg, *.gif, *.png).
• Zoom window. click the upper part of the main window with the right mouse button. the zoom window lets you select a specific area on the Earth, translate it, 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. lets you interactively modify the list of shown cities and locations.
• Option window. lets you reconfigure pretty much everything on the fly (colors, fonts, etc), exactly like you would with the command line options. obsessed.

---

✨ OPTIONS ✨

so the program does not use Xt or any other more advanced toolkit, which means only (!) the options explicitly enumerated below may be used. periodt. 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. important ordering detail bestie: the individual config file ~/.sunclockrc is read after the system wide config file Sunclockrc, so its settings override those of the system wide config. and the command line options can be used to override ~/.sunclockrc itself. layers on layers 💅

• -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 counts as 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, you 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) — bestie, this one loads an Earth map image straight into the clock window the second sunclock starts. Iconic behavior, no notes. 🖼️
• -zoomimage *.jpg (or *.gif, *.png, *.vmf, *.xpm, *.xpm.gz) — same energy but for the zoom widget: the file you name becomes the image showing up in there. ✨
• -colorlevel level=0,1,2,3 — sets the whole color vibe of the thing. Let's break it down because it's giving ✨options✨:
  • 0 = monochrome. Day and night show up as mapbgcolor (white by default) and mapfgcolor (black by default), and shading? Not available, sorry bestie. Everything else — city names, coordinates — also goes monochrome.
  • 1 = few colors. The menus and city spots can get their own dedicated colors, but the meridians/parallels/tropics are still stuck in monochrome.
  • 2 = many colors. Now the meridians/parallels/tropics can also be drawn in color too. 💅
  • 3 = full colors.

In those first 3 modes, literally only .vmf vector maps can be loaded, and they save so much CPU power because the algorithm is just a simple inversion of colors to set the color of every point on the map. Monochrome mode is lowkey perfect for super slow CPUs — think PDAs with black and white screens, the ancestors of your phone fr. The full color mode (level=3) lets you load jpeg or other colorful images, and day and night can be drawn with all kinds of shading parameters. This one is the default and the recommended mode if you've got a reasonably recent machine with enough video RAM. 🔥

• -dock — okay so this option gives sunclock the ability to be docked in your window manager's buttons or menu bar, as long as that WM offers the possibility without needing special hints. (fvwm2 or windowmaker or afterstep will work perfectly well for that purpose — KDE or Gnome won't... 😭).

Under -dock, 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.) 😳

You might want to customize the size and suitable options so sunclock fits with the size of your dockable applets. Like, for 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. That's literally it, no other effect than reallowing the use of options that were "frozen" under -dock. Use it e.g. to exit the application when sunclock has been started in dock mode. 🫶
• -synchro — with this option, sunclock updates all windows simultaneously. Which, 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, so bestie you don't even need to specify it. ⭐
• -dateformat string1|string2|... — sets 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's the tea on the placeholders: %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 you want, 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 too, 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, no biggie.
• -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 zooming behaves with respect to horizontal and vertical directions. Mode = 0 means no synchronizations are made, mode = 1 means the zoom factors are always made to be equal, and mode = 2 (the more subtle one, iykyk) means the horizontal and vertical zoom factors are adjusted so that the region near the central point of the zoomed area will be conformal to its actual geometry on Earth — like it won't appear distorted horizontally or vertically. That won't be true elsewhere though, especially if the zoomed area is large. 🌍
• -zoomsync — when this 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 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. Default 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 to 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) — sets where the urban window sits relative to the main window (or relative to the menu, when the menu's up). x = horizontal shift, y = vertical shift. Wanna know how the relative math works? It's the same deal as the -menugeom option above, go peek at that 💖
• -auxilgeom +(xcoord)+(ycoord) — same energy but for the auxiliary windows (menu, zoom, selector, option). x = horizontal shift, y = vertical shift, and every single relative displacement gets set to (x,y). All of them. At once. Slay 🫶
• -mag value — rescales the image by a magnification factor of value, and value has to be at least 1.0, no cap. What that means: the window only shows a fraction of the whole map, specifically 1/<value> x 1/<value> of it. Default is 1.0.
• -magx value — literally -mag but only the x direction (width) gets rescaled. Default magx is 1.0.
• -magy value — same as -mag but only the y direction (height) gets rescaled. Default magy is 1.0.
• -dx value (degrees) — -dx and -dy let you set the longitude (respectively the latitude) of the city or location that the zoom area should be centered on. Values go in degrees. Default (dx,dy) is (0.0,0.0).
• -dy value (degrees) — see -dx above bestie, it's the latitude half of that duo 💅
• -coastlines — in the builtin vector map, generates coast lines without filling in the land areas.
• -contour — same as before but uses a smart algorithm that eliminates lines, especially at lower resolutions. Heads up: if the coasts are super irregular, some parts may just disappear 😭 but the overall picture looks sharper.
• -landfill — in the builtin vector map, fills the land areas without generating coast lines.
• -fillmode 0,1,2 — quick cheat sheet: fillmode=0 = -coastlines, fillmode=1 = -contour, fillmode=2 = -landfill. That's it, that's the whole option.
• -dottedlines — meridians and parallels get drawn as dotted lines ✨
• -plainlines — meridians and parallels get drawn as plain lines instead.
• -bottomline — draws a line at the bottom of the map, so the map is separated from the text strip that shows time and coordinates.
• -nobottomline — doesn't draw that bottom line. This is the default.
• -command string — sets an external action or program that gets called through keyboard shortcut x. Default is an empty command.
• -helpcommand string — sets an external action or program that gets called through keyboard shortcut double h (call help). Default is "xterm -fn 9x15 -cr green -ms red -e man sunclock &".
• -jump number[unit] (where unit=s,m,h,d,M,Y) — the number of seconds (or minutes, hour, days, Months, Years, depending on the unit) by which the current date and time should be shifted. No blank space between the number and its unit, okay? If the unit is absent, the number is understood to be in seconds by default. Super useful to get sunclock display info on earlier or later epochs 🕰️
• -progress number[unit] (where unit=s,m,h,d,M,Y) — the number of seconds (or minutes, hour, days, Months, Years) by which the time progression should operate. Again: no blank space between the number and its unit, and if the unit is absent it defaults to seconds. Handy for getting sunclock to progress by steps other 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) — -rootdx and -rootdy set the position where the sunclock map gets copied onto the root window in rootwindow or screensaver modes. -rootdx 0.0 = left side, -rootdx 1.0 = right side, -rootdy 0.0 = top, -rootdy 1.0 = bottom of the root window. Default is 0.5 for both values, i.e. a centered map 🎯
• -rootdy value (degrees) — see -rootdx above. (Yes it says degrees, we're just relaying the facts bestie.)
• -fixedrootpos — uses the rootdx and rootdy values above to fix the position of the map on the root window. This is the default unless -screensaver has been specified.
• -randomrootpos — instead of using rootdx and rootdy to fix the position, it just uses a random position instead. This is the default when the -screensaver option has been set.
• -screensaver — starts sunclock in screensaver mode. Heads up: no window and no GUI controls are available in that case, and the only way to terminate the program is to kill it explicitly 💀
• -noscreensaver — doesn't start sunclock in screensaver mode. This is the default.
• -rootperiod value (in seconds, between 1 and 120 sec) — sets the period for refreshing the root window. Default is 30 seconds. This only takes effect when writing the map onto the root window is active (strike twice on [ or hit the relevant box in the Option window). And writing onto the root window gets disabled by using the ] key.
• -animation — starts animation mode right away when sunclock launches. Main character energy from the jump ✨
• -noanimation — doesn't start animation mode on launch — this is the default. Anyway, sunclock can switch between animation/noanimation modes by typing key ' (apostrophe) at runtime.
• -animateperiod value (in seconds, between 0 and 5 sec) — sets the period for animating the map. Default is 0 seconds, which means 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 only takes effect 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 a nonnegative integer meant to indicate the size of the city (1: major city, 2: important city, 3: less important city, ...). The size argument can also be set to 0, with the effect of hiding the corresponding city while keeping all of its other parameters in memory. The city can then be shown again with latitude and longitude, which 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), and incorrect timezones cause the clock to display GMT. It's 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) — initializes the program so it displays data of city name, respectively (name, with latitude and longitude specified). This only becomes effective if that city is listed in the systemwide RC file Sunclockrc or in the user's private ~/.sunclockrc. The operating mode gets set to Coordinates mode.
• -position latitude|longitude — initializes the program so it displays data of the position specified by two coordinates (in degrees). The operating mode gets set to Solar time mode. Notice that it uses a vertical bar | (a blank space is also admitted instead of a |).
• -addcity size|name|lat|lon|tz — adds a city to the list of cities to be displayed. They must be defined by exactly 5 parameters: size, name, latitude, longitude, timezone, in this order, with parameters 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 category, i.e. major city) to some maximum number, and -citycategories specifies that maximum. 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) get represented by the symbol of size s1, category 2 cities by the symbol of size s2, etc. The default setting is -spotsize 1|2|3|4|5. Assigning size si=0 means 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 only city categories 2 and 4 appear, 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). So -sizelimits 0 is equivalent to -sizelimits 0|0|0|0|0, and -sizelimits 0|400 is equivalent to -sizelimits 0|400|400|400|400.

---

• -shading mode=0,1,2,3,4,5 — start sunclock with a specific shading mode, your choice bestie. Mode 0 = the night area is literally not displayed at all. Higher modes show the night area, with increasingly sophisticated shading algorithms. Mode 1 = no shading whatsoever (just bright colors and dark colors, that's it). Mode 2 shades the terminator area — that's the zone where the sun is partially hidden by the horizon. Mode 3 shades the region where there's still substantial luminosity left after sunset (this depends on the diffusion parameter down below). Default is 3˚ below horizon. Mode 4 also 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) — though ngl, this has nothing to do with the actual luminosity values. 💅
• -nonight — start sunclock with the night region not drawn. Equivalent to -shading 0.
• -night — start sunclock with the night region in plain shading mode. 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 where 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 (iconic behavior honestly). 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 contrast between day and night areas. A 0.0 value means the night area will not be distinguishable from day, while 1.0 means 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 output, 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 🎀

Okay so bestie, you can keep a file in your 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. 😭

fr fr, that last one is not a bug so much as a vibe — the map is showing you the ideal, not the weather report.

👑 AUTHORS 👑

okay so bestie, this program has layers of history and you're gonna respect every single one of them, because sunclock is giving collaborative masterpiece energy and the lineage is iconic 💖

• John Walker, Autodesk, Inc., kelvin@acad.uu.NET — he wrote the original Suntools program, and that's the whole thing sunclock is derived from. like, the blueprint. the origin story. the moment it all began 🎀
• John Mackin, Basser Department of Computer Science, University of Sydney, Sydney, Australia, john@cs.su.oz.AU — he took that Suntools situation and wrote the X11 version out of it. glow-up era, fr fr ✨
• Stephen Martin, Fujitsu Systems Business of Canada, smartin@fujitsu.ca — he added support for interactive map. yes, the clicky fun part. thank him personally, no cap 🫶
• Jean-Pierre Demailly, Université de Grenoble I, demailly@fourier.ujf-grenoble.fr — he worked out versions 3.xx, and that's the era where it ate. it added so many new major features: loading maps, shading, zoom functionalities, and configuration of options on the fly at runtime, through a point and click GUI interface 👑

---

not to be dramatic but four whole humans across three continents poured themselves into this and it's lowkey the most wholesome thing in this entire manual 😭

so yeah, that's the whole page! you made it to the end bestie, i'm so proud of you 💅✨ go make something cool with it, and remember: every flag you type is standing on the shoulders of some very dedicated people. main character energy all around 🌈💜

this was SUNCLOCK(1), dated June 22, 2006 — yeah it's vintage, it's classic, it's serving timeless 🦋