Help Text for RISC OS MoonTool

Contents

• Introduction
• Using MoonTool
• Moon phases
• Gamma correction
• Saving the window positions, etc.
• Selecting a different time/date
• Test Mode
• Quitting
• Options
• Accuracy
• Differences between the RISC OS version and the original
• Technical details
• History (of my versions)
• Credits
• Copyright
• Disclaimer
• Contact details

Introduction

The original version of the program was called "A Moon For The Sun" since it was written for Sun workstations. Sometime around 1993 Eduoard Poor ported MoonTool to RISC OS 3.

Later, in early 1999, I saw a request for the moon to appear the right way up in the program (Eduoard was based in New Zealand so naturally the moon drawn by his version was the wrong way up for those of us in the Northern hemisphere). Also requested was the ability to calculate the moon phase/information for times other than the current date/time. Since both these things had been on my list of "Things to get around to one day" I decided I'd finally get on and do them.

Note that for MoonTool to work correctly the clock in your computer must be set correctly and your TimeZone/DST must also be correct. See your RISC OS user guide for more information.

MoonTool is compatible with RISC OS 3.1 and later.

Using MoonTool

Initially a small window will open that displays a picture of the moon as it appears in the sky (although it is always shown upright). Clicking on the moon in this small 'icon' window will open the main window which contains various pieces of information about the date and relative positions of the sun, moon and earth. Closing the window, or clicking Select on the Moon graphic, will cause the smaller 'icon' window to be re-opened.

Moon phases

You can also open/close the Moon phases window by clicking with Adjust on the Moon icon or the Moon in the main MoonTool window.

Gamma correction

In the Gamma Correction window, there is a small image showing two grey-scales and the Moon at both full and new phases. Between the grey-scales is a line of alternate blocks of solid grey and 'dithered' grey. Ideally, these blocks should look as close to each other in 'brightness' as possible.

To save the gamma correction setting, use Save choices from the main menu.

Saving the window positions, etc.

Selecting a different time/date

Note that whilst test-mode is active the Choose Time window will not work as expected. Rather than following the time selected test mode will simply 'step' each time a change is made. It's probably best not to mix the two.

The window contains a number of icons:

Current

When this option is selected, MoonTool will use the current date and time (as obtained from your computer's clock) and update its display(s) in real time.
The time adjustment icons will be shaded and un-selectable whilst this option is selected.
Note that this option doesn't have an immediate effect. You must click on the "Use" button to cause MoonTool to effect it.

Update

This option, when selected, causes MoonTool to update its displays in line with the time showing in the time selection window.
It can sometimes be useful (especially on older/slower machines) to turn this option off when selecting a time as the calculations MoonTool performs are relatively time consuming and so slow things down.
Note that this option takes immediate effect - you don't need to click on "Use".

Bump arrows

Use these arrows to select the date and time of day you're interested in. If you've ticked "Update" then MoonTool's various displays will be updated as the values are changed.

Now

Clicking this button causes the current date and time to be entered into the time selection window.

Cancel

Resets whatever options were in force when the time selection window was opened. If the button is clicked with Select then the window will also be closed. Clicking with Adjust keeps the window open.

Use

Causes MoonTool to use the options (or time/date) in the window. As with "Cancel", clicking with Adjust rather than Select will cause the window to stay open on the screen.

Test Mode

If you select "Test mode" from the menu then test mode will be engaged at the last selected speed ('Slow' initially). When test mode is engaged it can be cancelled either by reselecting it from the menu, or by selecting "Off" from the Test Mode submenu.

You can simultaneously engage test mode and select a speed by selecting one from the Test Mode submenu. The three speeds are (very approximately):

• Slow, 1-2 hours per second, normal speed update.
• Fast, about 3 days per second, updated quickly.
• Ludicrous, about a week per second, updated quickly.

Quitting

Options

The options are:

Start up 'iconified': -i

This is set as standard. If for some reason you want MoonTool to open its main window at startup (rather than the little 'icon' window) then removing the -i from the !Run file will make this happen.
Conversely, replacing the -i will cause MoonTool to open the small 'icon' window rather than the main window at startup.

Hemisphere: -n or -s

You can select either Northern or Southern hemisphere in the !Run file by including the flags -n or -s as appropriate.
By default, MoonTool assumes Northern hemisphere.

Open phases window at startup: -p

This flag will cause MoonTool to open the moon phases window at start-up.

Start in test mode -t

This flag causes MoonTool to start up in test mode (at the default, ie. slow, speed).

Use outline fonts in the windows: -o

This flag causes MoonTool to use outline fonts in its windows. Depending on the machine and monitor/screen-mode combination you are using you may find that outline fonts improve/reduce readability.

Brighten text in the windows: -b

You may find, especially at large screen sizes, that the grey-on-black text in the MoonTool windows is too hard to read. The -b option causes MoonTool to display all text (that has a black background) in white rather than grey.

Accuracy

If you feel like checking up on MoonTool there are tables of moon phases, etc. available on the 'net, for example:

• Moon Phase times for 1990 - 2005:
  http://aa.usno.navy.mil/AA/data/docs/MoonPhase.html
• Virtual Reality Moon Phase pictures:
  http://tycho.usno.navy.mil/vphase.html

Differences between the RISC OS version and the original

The "ghost moon" drawing is my own interpretation of how this should be done. I believe that the Sun/X11 versions have an option to use colour or monochrome when drawing the moon and show the dark area of the moon in blue. I haven't bothered with the monochrome option (it doesn't really seem worth it...) and chosen to make the dark moon look dark. If you really do want it to be blue, this is possible (see below in the "techie" section).

The Moon sprites used were obtained by scaling down a rather nice picture of the full moon I obtained from a PD source some years ago.

Technical details

It's possible to change the way that the dark moon is drawn by editing MoonTool's Messages (and possibly Sprites) files. Specifically, the Messages file contains the definition of the pixel translation table used to darken pixels in the sprite.

It should also now be possible to create a version of MoonTool for a different language without having to re-compile. The Messages and Templates files should now contain all the language specific words/phrases.

History (of my versions)

3.27 (19 Aug 2003)

• Added the Text Dump facility.

3.26 (27 Sep 1999)

• Added the Gamma Correction facility.
• Toggling the size of the 'icon' window now switches between the small and large versions.
• Test mode now updates the window(s) more quickly for fast/ludicrous speed.
• Gamma and big/small 'icon' window state is now saved along with the window positions (hence Save positions => Save choices).
• There is no longer any need to delete the WinPosns file if you change which of the small/large 'icon' windows you use.
• Now tested (and confirmed working) under RISC OS 4.

3.25 (28 Apr 1999)

• Added a workaround for a problem with the RISC OS 3.1 Wimp which caused the text in the windows not to update properly.
• Corrected the spelling of kilometres.

3.24 (05 Apr 1999)

• Redesigned the windows to give a much cleaner and more elegant layout. This was prompted by the much larger Moon sprite (twice the size of the original).
• Month names are now displayed abbreviated in all windows but the User time window and years are displayed in two-digit year format.
• Tweaked the moon-drawing to pre-calculate some of the trig. stuff it uses. This gives a significant improvement to the speed of updating the moon-phase sprite (with a 132 pixel high sprite the old code was much too slow).
• The moon-icon sprite is now created on-the-fly from the large sprite. This looks much better than just letting the Wimp plot the large one at half-size.
• Added large icon option. This causes the full-size moon-phase sprite to be used rather than the half-size one.
• Removed the hemisphere specific sprites - the northern hemisphere sprites are now rotated at load time if need be. In addition the sprites that are created on the fly are now blank in the sprite file to make the archive smaller :)
• Added code to open/close the Phases window when the Moon icon is clicked with Adjust.
• Added interactive help.
• Workaround for a problem with the Moon: the string of 'itty-bitty' craters that runs in a vertical line through the middle of the sprite looked a mite nasty (they don't exactly look good on the real Moon, to be honest) so have been de-emphasised to counter the effects of the scaling, etc. that the Moon sprite has gone through.
• Added the -b (brighten) and -o (outline fonts) options.

3.11 (16 Mar 1999)

• Fixed the Julian date as displayed in the main MoonTool window (it was 0.5 too high).
• Fixed a small problem that could cause the moon-phases window not to update properly when 'Current' is re-enabled in the user time window.
• Added a menu option to save the positions of the windows.
• Changed the layout of the moon phases window to make it the same height as the main MoonTool window and less 'fussy'.
• Tweaked the ghost-moon/earth light pixel translation table to look better, especially in 256+ colour modes.

3.10 (24 Feb 1999)

• Updated the core algorithms to the latest ones available in the Sun/X11 versions.
• Re-wrote the Desktop specific code to suit my tastes and fit the DeskLib style better.
• Improved the handling of the time selection window considerably and made it into a proper dialog window rather than a menu.
• Added the main menu and Info window.
• Split the moon phases into an independent window. Added code to open this window at startup if requested.
• Closing the main window now "iconifies" the program (ie. acts as if the moon button had been clicked).
• Added code to give (pinboard) iconised windows sensible titles.
• Added Test Speed menu.
• Re-worked the phase-hunting function to (hopefully!) work correctly.

2.00 (19 Feb 1999)

• My initial release with Northern/Southern hemisphere correction, user selectable time and high-resolution moon graphics. Still substantially based on Eduoard's original port (ie. the version 2.0 referred to in the original help text)

Credits

Original RISC OS port by Edouard Poor, circa 1993.
This RISC OS port by Musus Umbra, 1999.

RISC OS MoonTool was built using DeskLib (the freeware desktop C library for RISC OS machines).

I'd like to thank the following people for variously suggesting improvements, offering advice and prompting me to update the program in the first place: Alan Gray, Reg Hemms, Raymond Ling, Michael Rozdoba, Graham Jenkins, Fionn Taylor & Matthew Somerville.

Copyright

Please leave the original attribution information intact so that credit and blame may be properly apportioned.

Disclaimer

I am, however, interested in bug reports and feedback and will do my best to help if you do have problems.

Contact details